JSignage API
From SpinetiX Support Wiki
jSignage is a feature-rich JavaScript library dedicated to building professional digital signage applications on SpinetiX Hyper Media Player(s). The main purpose of jSignage is to make things like animations, interactivity and event handling, DOM traversal and manipulation, Ajax calls, data feed parsing etc., much more simpler than using standard JavaScript code.
If you're new to jSignage, we recommend that you check out the jSignage introductory page first.
Note that this is the API documentation for jSignage core; the links to the jSignage plugins are listed below.
Contents
Layers
Layers are the building blocks of jSignage documents. A layer can be broadly defined as a rectangular region on the screen where something (such as an image, some text, a playlist etc.) is shown for a certain amount of time.
New layers are created with: $.<layerType>( { attributes } ) where <layerType> can be media, textArea, playlist, carousel etc.
- All the layers share a common set of attributes (to define their screen layout and active time interval) and common set of functions (to work with layers).
- Frame decorations can be used to improve the presentation of any layer, for instance to add a frame, a shadow or to make rounded corners.
The layers can be classified as following:
| Category | Layer types |
|---|---|
| Basic layers | |
| Advanced layers | |
| Interactive layers | |
| Plugins layers |
Example:
// create a new media layer and add it to the DOM tree
$.media({ id: 'movie', width: 1280, height: 720, href: 'clip.avi' }).addTo( 'svg' );
// easily build multi-zone layouts
$('svg').add( [
$.video( id: 'main', left: '25%', height: '80%', href: 'coke.avi' } ),
$.playlist( {
id: 'leftbar', left: '0%', width: '25%', height: '100%',
data: [ 'ad1.jpg', 'ad2.jpg', 'ad3.jpg' ]
} ),
$.textArea( {
id: 'newsbar', top: '80%', left: '25%', width: '50%',
frame: { frameColor: 'black', backColor: 'grey' } // add a black frame and a grey background to the text layer
} ).text("Welcome to jSignage")
] );
DOM manipulation
jSignage supports different types of selectors, tree traversing, accessing raw XML elements, and other methods for uDOM manipulation.
Animation events
The visual appeal of digital signage applications can be greatly enhanced with jSignage due to the possibility to add different types of animation events: effects, transitions or custom animations.
Effects
jSignage effects can be used to improve the way a layer appears (in effect) or disappears (out effect) from the scene.
// add fade in and fade out effects to all the images in the document
$('image').fadeIn({ dur: '0.5s' }).fadeOut();
// add an SVG clock to the document with a fade in animation
$('svg').add(
$.animation ({ href: 'clock.svg', id : 'clk1' }).fadeIn({ dur: '3s' })
);
See also how to create new effects with jSignage.
Transitions
jSignage transitions are applied between consecutive items of a playlist or slideshow. A transition is a combination of an out-effect on the current slide and an in-effect on the next one.
// create a playlist of images with a cross-fade transition between them and add it to the document
$.playlist({
data: [ 'A.jpg', 'B.jpg', 'C.jpg', 'D.jpg' ],
defaultTransition : $.crossFade( )
}).addTo( 'svg' );
See also JSignage:Creating new transitions.
Custom animations
Custom animations are created with the following functions:
-
animateColor()- Animates the color of a linear gradient, a radial gradient or a shape.
-
animateMotion()- Creates a motion animation for a jSignage layer.
-
animateOpacity()- Animates the opacity of one of the colors of a linear gradient, a radial gradient, a shape, or a layer.
-
animateRotate()- Creates a rotation animation for a jSignage layer.
-
animateZoom()- Creates a zoom animation for a jSignage layer.
-
svgAnimation()- Add an SVG animation onto a specified target element.
Geometric shapes
The jSignage library provides a set of functions for drawing paths and basic geometric shapes: rectangles, circles, ellipses, lines, polylines and polygons.
- For example, to draw a rectangle on the screen:
$.rect({ x: 200, y: 100, width: 600, height: 400, fill:'blue' }).addTo('svg');
Color gradients
Gradients are created with linearGradient or radialGradient and referenced with .ref(). Similarly, referenceable animatable colors are created with solidColor.
For example, to draw a rectangle with a linear left to right gradient of blue to red:
$(function(){
var gr = $.linearGradient({ x1: 320, y1: 0, x2: 960, y2: 0, stops: [
{ offset:0, color: 'blue' },
{ offset:1, color: 'red' }
]}).addTo('svg');
$.rect({ x: 320, y: 180, width: 640, height: 360, fill: gr.ref() }).addTo('svg');
});
Localization
jSignage adds support for locale-dependent display of date, time and numbers using a subset of the Unicode Common Locale Data Repository data base.
Data feeds
Requesting and sending data
The jSignage framework supports the standard AJAX functionalities of jQuery for requesting or sending data over HTTP. The AJAX API is asynchronous, so a typical usage involves setting up a callback function which executes when the data is received.
The two most useful methods for accessing static or dynamic data on a server are:
-
$.get( url, callback ) -
$.post( url, data, callback )
For building client / server applications, the JSON-based methods are supported as well, such as $.getJSON( url, data, callback ).
Converting and parsing
The $.get() and $.post() methods usually return text content from a server in a certain format, like XML, JSON etc.; for this cases, the jSignage library includes multiple functions to simplify the parsing of text content into a JavaScript object - the most important are:
-
$.parseXML()for parsing an XML text description into a DOM object. -
$.parseJSON()for parsing a JSON text into a JavaScript object. -
$.parseRSS()for parsing an RSS feed into a JavaScript array of news items. -
$.parseICAL()for parsing an iCalendar file into a JavaScript array of event items.
Interactive Content
The jSignage library provides both high-level interactive layers (multi-page, carousel, pop-up, etc.) and low-level interactive event functions (click, keydown, textInput, etc.) to make it easy to build interactive applications in SVG.
Utilities
The jSignage library also includes several utility methods:
- DOM:
_createElement,getDocumentViewbox,setAttributes,triggerWithOffset - Time:
setTimeout,clearTimeout,setInterval,setIntervalSync,clearInterval,durInSeconds,getCurrentTime - Loggers:
debug,error,info,warn - Miscellaneous:
decodeURIQueryString,extend,randomChoice,shuffle
jSignage plugins
The following plugins were developed for jSignage library:
- jSignage Graph plugin for building charts and gauges layers;
- jSignage QRCode plugin for generating QR code layers;
- jSignage Astronomy plugin for different astronomy related calculations;
- jSignage Multiscreen plugin for different multiscreen related calculations;
- jSignage Social plugin for secure connection and data retrieval from different social networks (Facebook, Google, Instagram, Microsoft Online, Twitter, Yahoo).
- jSignage Custom Effects plugin implementing effects that are not provided "out of the box" by jSignage.
- jSignage UI plugin for different user-interface features.
Deprecated:
- jSignage Weather plugin for weather forecast. This was merged into jSignage Social library.
These add-on libraries must be included in the document after the jSignage.js library, for instance:
<script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js"/>
<script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.Graph.js"/>