JSignage

Introduction

If you are familiar with the jSignage library, you can jump directly to jSignage API page.

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 & 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 is built-in within the player firmware and Elementi software. It can also be downloaded from SpinetiX website for external usage. The jSignage library can be used and redistributed 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.

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 or in any HTML5 enabled browser.

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:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" dur="indefinite" height="100%" viewBox="0 0 1280 720" viewport-fill="black" width="100%">
<script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js" />
<script><![CDATA[

// Your jSignage / JavaScript code goes here ...

]]></script>
</svg>

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:

Open the SVG document and click on the XML Tree tab within the Edit panel.
Expand the second <script> element and double-click on its content (i.e. the light-green text area). This opens the "Edit CDATA" window.
Add / edit the code inside the "Edit CDATA" window.
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:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" dur="indefinite" height="100%" viewBox="0 0 1280 720" viewport-fill="black" width="100%">
<script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js" />
<script><![CDATA[

$(function(){

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

});

]]></script>
</svg>

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

History

2011-03-31: Started the development of the jSignage library.
2012-01-23: Version 0.9.0 (beta), included within the 2.2.4 release of HMP firmware and HMD software.
2012-09-06: Version 0.9.5 (beta), included within the 2.2.5 release.
2013-02-27: Version 0.9.6 (beta), included within the 2.2.6 release.
2013-04-18: Version 1.0.0, included within the 3.0.0 release of HMP firmware and Elementi software.
2013-07-01: Version 1.0.1, included within the 3.0.1 release.
2013-12-12: Version 1.0.2, included within the 3.0.2 release.
2014-03-27: Version 1.0.3, included within the 3.0.5 release.
2014-10-13: Version 1.1.0, included within the 3.1.0 release (jSignage.Graph & jSignage.QRCode add-ons are also included within this release).
2014-12-04: Version 1.1.1, included within the 3.1.1 release.
2015-08-07: Version 1.2.0, included within the 3.2.0 release (jSignage.Astronomy & jSignage.Multiscreen add-ons are also included within this release). The same jSignage version is used within Elementi 2015 and the 4.0.0 firmware release.
2016-02-05: Version 1.2.1, included within the 4.0.1 release.