JSignage

From SpinetiX Support Wiki

Jump to: navigation, search
JSignage.png

Introduction

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.

Working with jSignage is easy and intuitive, being very similar to the popular jQuery library; in fact, jSignage includes a port of jQuery to the SVG Tiny 1.2 uDOM in what concerns DOM manipulation, interactive events, and AJAX calls, 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.

The jSignage library can be used and redistributed in compliance with the terms of the GPLv2 license - the latest version can be downloaded from SpinetiX website for external usage; older library versions can be provided on demand.

Getting started

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

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

One important thing to know is that jSignage is a JavaScript library and all its power is accessed via JavaScript, so having a strong grasp of JavaScript's built-in constructs and syntax is essential for understanding, structuring, and debugging your code. Therefore, if you're new to JavaScript, we recommend checking out the JavaScript basics tutorial on the Mozilla Developer Network (MDN).

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 Note:
The jSignage variable can also be referenced by its syntactic sugar alias $ (dollar sign), meaning that writing $( parameters ) or jSignage( parameters ) is the same thing.

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: 

<?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. Added jSignage.Graph & jSignage.QRCode plugins.
  • 2014-12-04: Version 1.1.1, included within the 3.1.1 release.
  • 2015-08-07: Version 1.2.0, included within the 4.0.0 / 3.2.0 release. Added jSignage.Astronomy & jSignage.Multiscreen plugins.
  • 2016-02-05: Version 1.2.1, included within the 4.0.1 / 3.2.1 release. Added jSignage.Weather.js plugin.
  • 2016-05-04: Version 1.2.2, included within the 4.0.2 / 3.2.2 release.
  • 2016-09-15: Version 1.3.0, included within the 4.1.0 / 3.3.0 release. Added jSignage.Social.js plugin.
  • 2016-02-05: Version 1.3.2, included within the 4.0.1 / 3.3.1 release.
  • 2017-04-06: Version 1.4.0, included within the 4.2.0 / 3.4.0 release.
  • 2017-12-07: Version 1.4.1, included within the 4.2.3 / 3.4.2 release.
  • 2018-06-01: Version 1.5.0, included within the 4.3.0 / 3.4.3 release.
  • 2018-11-21: Version 1.5.1, included within the 4.4.0 / 3.4.5 release.
  • 2019-06-11: Version 1.5.2, included within the 4.4.2 / 3.4.6 release.
  • 2020-10-05: Version 1.6.0, included within the release 4.6.1.
  • 2021-03-11: Version 1.6.1, included within the release 4.7.1.
  • 2022-11-10: Version 1.7.0, included within the release 4.7.5.
  • 2023-03-09: Version 1.7.1, included within the release 4.7.6.
Retrieved from "https://support.spinetix.com/w/index.php?title=JSignage&oldid=18112"
This page was last modified on 24 March 2023, at 11:03.