JSignage utilities methods

This page describes some jSignage API utility methods. See also Parsers.

DOM

jSignage._createElement()

Creates an SVG element (using document.createElementNS DOM method) and adds the specified attributes on the newly created element.

$._createElement( name, attributes );

Returns: SVG Element

Note:

This function returns a DOM object and is different from the $.createElement() method which returns a jSignage Object.

Parameters:

• name

  Type: String.

  The name of the SVG element.

• attributes

  Type: Plain Object.

  The attributes to be set onto the element.

Example:

var elem = $._createElement( 'animate', { attributeName: 'opacity', from: 0, to: 1, dur: 10, begin: 0 } );

jSignage.getDocumentViewbox()

Gets the document viewBox as an SVGRect object containing x, y, width, and height numeric properties.

$.getDocumentViewbox();

Returns: Plain Object

jSignage.setAttributes()

Sets the specified attributes on an SVG element.

$.setAttributes( element , attributes );

Returns: Undefined

Parameters:

• element

  Type: SVG Element.

  The SVG element to set attributes to.

• attributes

  Type: Plain Object.

  The attributes to be set onto the element.

jSignage.triggerWithOffset()

Produces a well-formed SVG time point to use for the begin or end attribute of an SVG animation element.

$.triggerWithOffset( trigger, offset );

Returns: Number or String

Parameters:

• trigger

  Type: Array.

  The time-point to be used as base.

• offset

  Type: Number.

  A number of seconds to be used as offset from the trigger time-point.

Example:

animateElement.setAttribute( 'begin', $.triggerWithOffset( trigger, offset ) );

Time

jSignage.setTimeout()

Executes one time the callback function after the duration specified by ms. Returns a handler to the timer in case it needs to be canceled before the execution.

$.setTimeout( callback, ms );

Returns: Timer Object

Parameters:

• callback

  Type: Callback.

  The function to be executed after the duration specified by ms.

• ms

  Type: Number. Default: 0.

  The number of milliseconds (thousandths of a second) that the callback function call should be delayed by.

jSignage.clearTimeout()

Cancels a timer created with the setTimeout function.

$.clearTimeout( timer );

Returns: Undefined

Parameters:

• timer

  Type: Timer Object.

  A handler to a timer created with setTimeout function.

jSignage.setInterval()

Executes repeatedly the callback function with a fixed time delay between each call. Returns a handle to the timer in case it needs to be canceled.

$.setInterval( callback, ms );

Returns: Timer Object

Parameters:

• callback

  Type: Callback.

  The function to be executed repeatedly.

• ms

  Type: Number.

  A positive number of milliseconds (thousandths of a second) to wait between calls to the callback function.

jSignage.setIntervalSync()

Added in firmware 3.0.6 release.

Executes repeatedly the callback function with a fixed time delay between each call, just like setInterval function, except that the first call is done after a delay that is most probably shorter that the one provided as parameter, in order to synchronize together multiple timers having the same delay. Returns a handle to the timer in case it needs to be canceled.

$.setIntervalSync( callback, ms );

Returns: Timer Object

Parameters:

• callback

  Type: Callback.

  The function to be executed repeatedly.

• ms

  Type: Number.

  A positive number of milliseconds (thousandths of a second) to wait between calls to the callback function.

jSignage.clearInterval()

Cancels a timer created by setInterval function.

$.clearInterval( timer );

Returns: Undefined

Parameters:

• timer

  Type: Timer Object.

  A handler to a timer created with setInterval function.

jSignage.durInSeconds()

Parses a time value and returns its value in seconds or, in case of undefined or malformed, the provided default value.

$.durInSeconds( time [, defaultTime] );

Returns: Number

Parameters:

• time

  Type: Number or String.

  A time value, with or without the unit suffix (e.g., h, min, ms) to be parsed.

• defaultTime

  Type: Number. Default: 0;

  The default time value to be used in case the time parsing fails.

Example:

var dur = $.durInSeconds( args && args.dur, 1 );

jSignage.getCurrentTime()

Gets the current document time in seconds.

$.getCurrentTime();

Returns: Number

Loggers

jSignage.debug()

Adds a log entry at debug level with the provided string text. Added in jSignage version 1.3.0.

$.debug( text );

jSignage.error()

Throws a JavaScript error with the provided string text.

$.error( text );

jSignage.info()

Adds a log entry at info level with the provided string text. Added in jSignage version 1.3.0.

$.info( text );

jSignage.warn()

Adds a log entry at warning level with the provided string text. Added in jSignage version 1.3.0.

$.warn( text );

Miscellaneous

jSignage.decodeURIQueryString()

Parses a URI and returns an object with the query strings pairs.

$.decodeURIQueryString( queryString [, qs_only] );

Returns: Plain Object

Parameters:

• queryString

  Type: String.

  A query string, usually a URI, containing key=value pairs separated by & sign.

• qs_only

  Type: Boolean. Optional.

  If missing or set to false, only the query string part is processed, meaning that then the characters before the question mark (?) and after the hash (#) signs, including the delimiters, are removed.

Example:

const uri = document.documentURI 
        || window.location && window.location.href 
        || document.location && document.location.href;
var jsonParams = $.extend( $.parseJSON($('#jsonParams').text()), $.decodeURIQueryString( uri ) );

jSignage.extend()

Port of the jQuery extend method for merging the contents of two or more objects together into the first object.

$.extend(  target [, object1 ] [, objectN ] );
$.extend( [deep,] target, object1 [, objectN ] )

Returns: Plain Object

If only one argument is supplied, the jSignage object itself is assumed to be the target. By doing this, you can add new functions to the jSignage namespace. This can be useful for plugin authors wishing to add new methods to jSignage.

$.extend( object1 );

Returns: jSignage Object

jSignage.guessCannedSlidesDur()

Computes the total duration of a playlist/slideshow.

$.guessCannedSlidesDur( canned [, defaultDur] );

Returns: Number or String

Parameters:

• canned

  Type: Plain Object or Array.

  The JSON-parsed description of the playlist's content.

• defaultDur

  Type: Boolean. Optional.

  Optional parameter, specifying the duration to be used as default.

jSignage.guessSlideDur()

Returns the layer's duration as a number of seconds, "media", or "indefinite".

$.guessSlideDur( ctor, args [, defaultDur] );

Returns: Number or String

Parameters:

• ctor

  Type: String.

  The constructor type of the layer.

• args

  Type: Plain Object.

  The JSON-parsed description of the layer's arguments.

• defaultDur

  Type: Boolean. Optional.

  Optional parameter, specifying the duration to be used as default.

jSignage.randomChoice()

Returns a randomly selected item of the provided array parameter.

$.randomChoice ( array );

jSignage.shuffle()

Returns an array containing items selected randomly from the input array.

$.shuffle( array [, limit] );

Returns: Array

Parameters:

• array

  Type: Array.

  The array to be used as source.

• limit

  Type: Number. Optional.

  Optional parameter to limit the number of items in the returned array.