JSephus

A portable ES6 class for an attractive SVG loading element.

Home

Quick-start guide

Reference documentation

Download

GitHub

Reference documentation

v1.0.0

Contents

Constructor

new JSephus

To instantiate a new class, use the ES6 syntax new JSephus(). The constructor has two arguments:

Usage

var jsph = new JSephus("jsph-svg", 41);

See also

createSVG, init, n



Methods

init

Summary

Draw a JSephus object in the parent SVG element.

Arguments

Argument Type Description
instant boolean Whether to fade-in or instantly show the loader. Default false.

Usage

jsph.init();

Details

After instantiating a new JSephus object, this function initialises that object: it calculates the position of the circles, creates these elements as well as the text element and appends them to the parent SVG in the DOM. By default, this happens in a ‘pretty’ way: the elements fade-in in a short amount of time. Setting the argument instant to false removes this transition and instantly shows the loader.

It is necessary to call init after setting properties using the setProperty method to show the changes.

See also

createSVG, setProperty, setProgress



setProperty

Summary

Styling the loader by changing the display properties of the JSephus object.

Arguments

Argument Type Description
property string, array, object In case of string or array: the name(s) of the properties to change. In this case it also needs a value argument. Otherwise: a JSON object with as keys the names of the properties to set and as values the desired values of these properties.
value value, array, null Which value to change the corresponding property to. Its type depends on the selected property.

Usage

jsph.setProperty("radius", 15);

jsph.setProperty(["radius", "dist"], [15, 100]);

jsph.setProperty({
  "alpha": 0.1,
  "fontSize": "50",
  "textOpacity": "0.5"
});

// chaining setProperty & init
jsph.setProperty("radius", 15).init();

Details

This is the workhorse JSephus styling method. In order to know which properties can be set, see Properties. In case of erroneous input, this function returns informative errors, so don’t be afraid to play around!

See also

Properties, init, setProgress



setProgress

Summary

Set the progress value of the loader element. This function updates the loader to the new state.

Arguments

Argument Type Description
proportion number The progress proportion to set the JSephus loader at. This number needs to be between 0 and 1.

Usage

jsph.setProgress(0.5);

See also

init, reset, start



reset

Summary

Set the progress value of the loader element to 0. If text is hidden but property displayText is true, also show the text element.

Usage

jsph.reset();

See also

init, setProgress, start, hideText



start

Summary

Animate the progress until 100% in a given amount of time.

Arguments

Argument Type Description
time integer The time in milliseconds that it should take the loader to animate from 0% to 100%. Default 10000 (10 seconds)
callback function Function to call after the progress has reached 100%. The argument of this function is the JSephus element.

Usage

// run for 10 seconds
jsph.start();

// run for 5 seconds, hide text after done
jsph.start(5000, jsph => jsph.hideText());

See also

init, reset, reverse, hideText



reverse

Summary

Animate the progress down to 0% in a given amount of time.

Arguments

Argument Type Description
time integer The time in milliseconds that it should take the loader to animate from 100% to 0%. Default 10000 (10 seconds)
callback function Function to call after the progress has reached 0%. The argument of this function is the JSephus element.

Usage

// run for 10 seconds
jsph.reverse();

// run for 5 seconds, hide text after done
jsph.reverse(5000, jsph => jsph.hideText());

See also

init, reset, start, hideText



stop

Summary

Stops the animation initiated by start or reverse.

Usage

jsph.stop();

See also

start, reverse, reset



hideText

Summary

Hide the text element (by setting its opacity to 0).

Usage

jsph.hideText();

See also

showText, reset, displayText, textOpacity, textColour



showText

Summary

Show the text element (by setting its opacity to textOpacity), even when displayText is set to false.

Usage

jsph.showText();

See also

showText, reset, displayText, textOpacity, textColour



Static methods

Static methods do not require an instance of the JSephus class. They can be called as elements of the class specification: JSephus.method().

createSVG

Summary

Creates a proper SVG element for JSephus and appends it to the window DOM.

Arguments

Argument Type Description
parentId string The parent <div> of the <svg>
svgId string The id of the new <svg>
viewBoxWidth number The width of the internal coordinate system
viewBoxHeight number The height of the internal coordinate system

Usage

JSephus.createSVG("parentDiv", "jsph-svg", 512, 512);

Details

JSephus uses the viewBox of the SVG element to calculate the midpoint, distances, translation distances, and radii of its circles. I recommend setting the margins or the padding of the parent div to resize the loading element, not to change any properties of the SVG itself. Of course, if you are an SVG pro, feel free to play around with viewBoxes and such.

See also

init, setProperty, dist, radius, transDist



Properties

These are the properties that can be changed through the setProperty method.

Name type description
n integer The number of circles in the loading element. No default (set by the constructor).
colour boolean Whether the elements have colour or grayscale. Default true.
alpha number Number between 0 and 1 that indicates the opacity of the circles. 0 indicates fully transparent. Default 1.
dist number Distance of the circles from the midpoint, expressed in terms of svg coordinate units set by the viewBox in the constructor. Default 2/3rds the shortest distance from the middle to the edge of the box.
radius number Radius of the circles themselves. Default 10.
precision number Precision (step size) of the animation started by start or reverse. Has to be larger than 0, smaller than 1. Default 0.001.
displayText boolean Whether to show the animated text in the middle of the loader. Default true. Override through showText or hideText possible.
fontSize CSS string Font size of the text element. This accepts CSS strings so it is possible to use relative units such as “1rem”. Default 60.
fontFamily CSS string The font family of the text element. Default system font stack.
textOpacity CSS string String of a number between 0 and 1 that indicates the opacity of the text element. “0” indicates fully transparent. Default "1.0".
textColour CSS string Colour of the text. Default "rgb(60, 150, 120)".
disappear boolean Whether the circles should disappear when they are “killed”. Default true.
transDist number How far the circles should travel outward when they are “killed”. Default dist * 1/5.
transDuration CSS string String indicating how long it should take a “killed” element to move and / or disappear. Default "0.4s"
transFunction CSS string What should the css transition-timing-function property of the transition be. Default “cubic-bezier(.59, .01, .39, .97)”.
textTransform CSS string CSS string indicating the transform to be applied to the text element. Can be used to properly align text in case the font displays strangely, or simply to move the text to a corner, for example. Default "translate(0px, 0px)".