JSignage:JSignage API

From SpinetiX Support Wiki

Download jSignage.js

Version 1.1.1 (2014-12-04)

Introduction

jSignage API 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 & event handling, DOM traversal & manipulation, Ajax calls, data feed parsing etc., much more simpler than using standard JavaScript code.

The easy-to-use and intuitive jSignage API includes a port of the popular jQuery on the SVG Tiny 1.2 uDOM, thus making jSignage compatible with HTML5 browsers, as well as embedded and mobile SVG players.

The jSignage library is contained within a single file, called jSignage.js, which can be downloaded from SpinetiX website.

• The current version of the jSignage library is 1.1.1 - this is the version included within the 3.1.1 release of firmware and software. Make sure to always use the latest version in your project.
• Starting with the 2.2.4 release, this library has been included within the HMP firmware and Elementi / HMD software.
• You can use and redistribute the jSignage library in compliance with the terms of the GPLv2 license.

Getting started

Getting started with jSignage can be easy or challenging, depending on your experience with SVG, JavaScript, jQuery, CSS, and programming concepts in general.

Loading the library

To start using jSignage, the first step is to include the jSignage library within your SVG document using a <script> element pointing to jSignage.js.

The jSignage library is automatically added into virtually any new SVG document (e.g., layout, playlist etc.) created within Elementi.

If you prefer using a text editor instead, then create new an SVG document with the following code:

• The first <script> element imports the jSignage library code into the JavaScript context of the document.
• The second <script> element contains your jSignage / JavaScript code.

Always load the jSignage library from SpinetiX public URL:http://download.spinetix.com/spxjslibs/jSignage.js !

When using this "special" URL, HMP and Elementi load jSignage from their built-in library, without actually needing Internet access to download it from SpinetiX server. Furthermore, this triggers an optimization whereby the jSignage library is compiled and interpreted only once and the resulting jSignage object ($) is shared among all documents using the library. In effect this means zero time loading of the library (because it boils down to just incrementing the reference counter on the $ object), whereas having a copy of the js file inside the project will increase document opening time by up to 5s for each use.

The jSignage version depends on the firmware / software release version, therefore, make sure to have the HMP firmware & software up to date in order to use the latest jSignage version.

The jSignage object

Once the jSignage library has been loaded, the jSignage variable is added to the JavaScript global object and, thus, it can be directly referenced in the subsequent JavaScript code. The jSignage variable is, in fact, a function that always returns a reference to itself (i.e. jSignage Object) when called without parameters (i.e. jSignage()). Furthermore, many jSignage member functions return the jSignage object itself, in order to allow multiple calls to be chained together.

Note: The jSignage variable can also be referenced by its syntactic sugar alias, $ (dollar sign). Similarly, instead of writing jSignage( parameters ), you can simply use $( parameters ).

Adding jSignage code

Any JavaScript code containing references to jSignage (for simplicity, this will further be referred to as jSignage code) must be added / loaded after the <script> element including the jSignage library. The code can be added directly within the SVG document inside a <script> element (as presented above) and / or it can be added into a separate JS file and loaded it with a <script> element's xlink:href attribute.

If you want to add / edit jSignage code within Elementi X, follow these steps:

1. Open the SVG document and click on the XML Tree tab within the Edit panel.
2. Expand the second <script> element and double-click on its content (i.e. the light-green text area). This opens the "Edit CDATA" window.
3. Add / edit the code inside the "Edit CDATA" window.
4. Click on the "OK" button to save your changes.

For instance, let's say we want to show one image over the entire screen. For that, we'll call the jSignage media() function along with the image address and then add the resulted media layer to the DOM using addTo() function. This gives us the following code:

$.media( { href: 'smile.jpg' } ).addTo( 'svg' );

Executing code on document ready

An SVG document cannot be manipulated safely until it is "ready" (i.e. all the elements inside the document are loaded). jSignage detects this state of readiness for you through its ready member function. To ensure that your code only runs once the entire Document Object Model (DOM) is ready for JavaScript code to execute, you need to include it inside a function that is passed as parameter to the ready function - like this:

jSignage( document ).ready( handler_function );

The expression above can be written in a shorter form as $( handler_function );.

In Elementi, all the jSignage code is included within an anonymous function wrapped inside a $() call. To do the same (this is strongly recommended), then change the second <script> element mentioned above like this:

$(function(){
 
    // Your jSignage / JavaScript code goes here ...
 
});

One full-screen media example

Putting together all the information above, we get the following code:

Other examples

Full-screen playlist of images

var list = [ 'smile.jpg', 'frown.jpg', 'grin.jpg' ];
$.playlist({ data: list, defaultDur: '10s', repeatCount: 'indefinite' }).addTo( 'svg' );

Dynamic layout

var rows = [
       { img: 'left.png', txt: 'Beach' },
       { img: 'right.png', txt: 'Swimming pool' },
       { img: 'front.png', txt: 'Reception' }
];
 
for ( i in rows ) {
 
    $.media({ href: rows[i].img, left: 100, top: 100*i, width: 100, height: 100 }).addTo( 'svg' );
 
    $.textArea({ left: 100, top: 100*i, width: 'auto', height: 100, font-size: 80 }).text( rows[i].txt ).addTo( 'svg' );
 
}

Tutorials

The best way to get up to speed with jSignage is to go through the our jSignage tutorials.

• You can run the tutorials inside Elementi / HMD or in any HTML5 enabled browser.

jSignage core

Layers

Note: See the full article on layers here: JSignage: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>({ id: 'id', ... }) 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).

For example to create a new video layer you would use:

// create a new video 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([
   $.playlist( { id: 'leftbar', left: '0%', width: '25%', height: '100%', data: [ 'ad1.jpg', ... ] } ),
   $.video( id: 'main', left: '25%', height: '80%', href: 'coke.avi' } ),
   $.textArea( { id: 'newsbar', top: '80%', left: '25%', width: '50%' } ).text("Welcome to jSignage")
]);

Layers types

The layers can be split into:

• Basic layer types such as Media layers (audio, video, image or animation), Text areas or Groups.

• Advanced layer types such as Playlists, Slideshows, Text bars, Crawlers (Text tickers, Media crawlers), Tables, Smart text areas (Fit text areas, Ping-pong text areas, Headline text area and Scrolling text areas).

• Interactive layer types such as Multi-page, Carousel, Pop-up, Push button, Progress bar and Progress wheel.

More types can be added by extending the jSignage library with new constructors - see Layer implementation in SVG for a technical article about how the layers are implemented in the library.

The visual appeal of signage applications can be greatly enhanced with the possibility to add frame decorations, custom graphics and custom color effects with jSignage.

Frame decorations

Note: See the full article on frame decorations here: JSignage:Frame decoration attributes.

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.

// this will add a black frame and a grey background to a text layer. 
$.textArea( { frame: { frameColor: 'black', backColor: 'grey' } } ).text('Welcome to jSignage').addTo('svg');

DOM manipulation

Note: See the jQuery port to the uDom page for more details on the functions available for DOM manipulation.

Animations

The visual appeal of signage applications can be greatly enhanced with jSignage due to the possibility to add different types of animations: effects, transitions or custom animations.

Effects

Note: See the full article on effects here: JSignage:Effects. See also JSignage:Creating new effects.

Effects can be used to improve the way a layer appears (in effect) or disappears (out effect) from the scene.

All effects share a common set of attributes to define their timing.

// 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' })
   );

Transitions

Note: See the full article on transitions here: JSignage:Transitions. See also JSignage:Creating new transitions

A transition is a combination of out & in effects applied between consecutive items of a playlist or slideshow.

All transitions share a common set of attributes and they are applied using the transition attribute.

// 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' );

Custom animations

jSignage provides support for the animation of the parameters of gradients and solid colors, and of the opacity, motion and transform of geometric shapes and layers. If supported by the player these are implemented with SMIL animations rather than with JavaScript timers.

Animations are created with animateColor, animateOpacity, animateMotion, animateZoom and svgAnimation.

Geometric shapes

Note: See the full article about shapes here: JSignage: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, animatable referenceable 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-dependant display of date, time and numbers using a subset of the Unicode Common Locale Data Repository data base.

The Localization API is based on two classes:

• $.DateTimeFormat for the formatting of date and time
• $.NumberFormat for the formatting of numbers and currencies

To use the API, create an object of either class by calling the constructor with a format selector and an optional locale tag. Without the locale argument, the default locale is used. The default locale can be changed by a call to $.setLocale(tag).

Each locale is identified by its unicode locale tag, a string composed of two or three parts: a language subtag and a region subtag, plus an optional script subtag. For example, US english, the default locale, is identified as en_US, mainland china as zh_Hans_CN and the mexican locale is es_MX. See Locale codes 3.0 for the list of all locale tags in firmware 3.0.

The format selector for date and time is either one of the predefined standard formats for the locale in the Format enum such as $.DateTimeFormat.Format.FULL_DATETIME or a pattern string using the unicode LDML date format pattern, e.g. EEEE, MMMM d, y will be expanded to Wednesday, July 10, 1996 for en_US.

Similarly the format selector for numbers and currencies is either one of the predifined formats or a pattern string using the unicode LDML number format pattern.

Example: formatting date, time and numbers

  $.setLocale( 'es_ES' );
 
  f = new $.DateTimeFormat( $.DateTimeFormat.Format.LONG_DATE );
  str = f.format( new Date() );   // -> "24 de abril de 2013"
 
  f = new $.DateTimeFormat( "dd/MM/yyyy" );
  str = f.format( new Date() );   // -> "24/04/2013"
 
  f = new $.DateTimeFormat( $.DateTimeFormat.Format.LONG_DATE, 'zh_Hans_CN'  );
  str = f.format( new Date() );   // -> "2013年4月24日"
 
  f = new $.NumberFormat( $.NumberFormat.Format.DECIMAL );
  str = f.format( Math.PI );    // -> "3.142"
 
  f = new $.NumberFormat( "#.#####" );
  str = f.format( Math.PI );    // -> "3.14159"

Data feeds

Requesting and sending data

The jSignage framework supports the standard AJAX functionnalities of jQuery for requesting data over HTTP. The AJAX API is asynchronous, so a typical use involves setting up a callback which executes once the data has been received. See JQuery port to the uDom.
The two most useful function are:

• $.get( url, callback )
• $.post( url, data, callback )

These are the primary ways of accessing static or dynamic data on the server as well as data feeds suchs as RSS feeds.

For building interactive client/server applications, the JSON methods are supported as well, such as $.getJSON( url, data, callback ).

Warning:

• When using AJAX methods in browsers, the security settings may prevent data from being loaded if it does not comes from the same server as the file being displayed. This is called Same origin policy. There are no issue with the HMPs, Elementi or HMD. A solution for cross-browser/player compatibility, is to use JSONP.

Converting and parsing

The $.get() and $.post() functions might return text content from a server. For this cases, the jSignage library includes multiple helper functions to simplify the parsing of this text content into a JavaScript object.

See parsers and helpers for the full documentation. The most important are:

• $.parseXML() Parses an XML text description into a DOM object.
• $.parseRSS() Parses and RSS feed into a javascript array of news items.
• $.parseICAL() Parses an iCalendar file into a javascript arrays of event items.
• $.parseJSON() Parses JSON text into javascript objects.
• $.shuffle() Randomize the order of a data set

Interactive Content

The jSignage library provides a basic set of interactive elements to make it easy to build interactive kiosk type applications in SVG.

jSignage add-ons

Currently, there are two jSignage add-ons: the jSignage Graph library (for building charts and gauges layers) and jSignage QR code library (for generating QR code layers).

Both libraries are requiring firmware 3.1.0 or greater, and must be included in the document after the jSignage.js library.

 <script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js"/>
 <script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.Graph.js"/>
 <script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.QRCode.js"/>