JSignage:JSignage API

From SpinetiX Support Wiki

(Redirected from Jsignage)

Version 1.0.0

Introduction

jSignage API is a feature-rich JavaScript library dedicated to building professional digital signage applications with SpinetiX Hyper Media Player. 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 raw 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.
Note: See the jQuery port to the uDom page for more details on the DOM manipulation functions available.

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

Starting with the 2.2.4 release, this library is included in the HMP firmware and within the Elementi / HMD software.
You are free to use and redistribute the library in compliance with the terms of the GPLv2 license.

The current version of the jSignage library is 1.0.0 - this is the version included with the 3.0.0 release of firmware and software. Make sure to always use the latest version in your project.

Getting started

If you are new to jSignage, you can start with our jSignage tutorials page. You can run the tutorials inside Elementi / HMD or in any HTML5 enabled browser.

To start using the jSignage within your project, insert the following lines in your SVG file:

<script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js" />
<script><![CDATA[
    $(function(){
        //Your code goes here ...
    });
]]></script>

The first <script> element will import the jSignage library code into the JavaScript context of the document.
The second <script> element contains your code, which will be executed as soon as the rest of document has loaded.

Note: The recommended method to load the jSignage library is to specify the public URL for jSignage on SpinetiX website as above. Using this "special" URL triggers an optimisation whereby the player / Elementi / HMD will actually load a built-in jSignage library (thus there's no need for Internet access) which is compiled and interpreted only once and the resulting $ object is shared among all documents using the library. In effect this means that using the download.spinetix.com URL in you <script> element will result in 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.

If you are not using the latest release of firmware & software, you can manually download the latest version of jSignage library from the above URL and include it inside your project, nevertheless it's better / recommended to update the firmware & software instead.

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

Geometric graphics

Shapes are a set of helpers to draw SVG shapes using jSignage. The following shapes are available: rectangle, line, circle, ellipse, polyline, polygon and path.

All shapes support the Fill and stroke attributes.
Animations, effects and frame decorations can only be applied on the jSignage layer that contains the shape and not on the shape itself. Therefore, the typical solution is to add the shape into a jSignage layer and then apply the animation, effect or the frame decoration.
```
$.g().add($.<shape>).<effect>
```

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

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 javascript timers.

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

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.

Simple examples

Show one image full screen

<svg viewBox="0 0 1280 720" dur="indefinite" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
   <script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js" />
   <script><![CDATA[
     $.media({ href: 'smile.jpg' }).addTo( 'svg' );
   ]]></script>
</svg>

Full-screen playlist of images

<svg viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
   <script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js" />
   <script><![CDATA[
     var list = [ 'smile.jpg', 'frown.jpg', 'grin.jpg' ];
     $.playlist({ data: list, defaultDur: '10s', repeatCount: 'indefinite' }).addTo( 'svg' );
   ]]></script>
</svg>

Dynamic layout

<svg viewBox="0 0 1280 720" dur="indefinite" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
   <script xlink:href="http://download.spinetix.com/spxjslibs/jSignage.js" />
   <script><![CDATA[
     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' );
     }
   ]]></script>
 </svg>