JSignage layers

Description

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 (the active interval).

A typical document is built of many layers, each having its own Z-order and overall transparency level.

• In SVG documents, the Z-order is determined by the order at which element appears in the document and cannot be changed. Note that this is different than HTML documents, where the CSS z-index property sets the stack order of specific elements.
• A layer can be opaque like a video layer, but most layers, such as text areas, are at least partially transparent, letting the background or other layers below it to be showed through.

Each layer has an "active interval": the interval of time during which it is active, controlled by the optional begin and dur attributes. The beginning and end of this time interval are the trigger points for in and out effects. By default a new layer starts at 0s and lasts forever.

Effects can be used to modify the way the layer appears and disappears from the scene.

Layer constructor

New layers are created by invoking the layer constructor for the desired layer type:

$.<layerType>({ id: 'id', ... });

where <layerType> can be media, textArea, playlist, carousel etc.

To replace an existing layer entirely, usually a placeholder element in a template, use the same constructor on the layer to be replaced.

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

Layer types

Basic layer types

The basic layer types are:

• Audio only layers, constructed with $.audio() contain only audio and are not visible.
• Video layers, constructed with $.video() contain video and optionally audio.
• Image layers, constructed with $.image() show static content only (bitmap or vector graphics).
• Animation layers, constructed with $.animation() contain SVG or SMIL documents.
• Media layers, constructed with $.media() combine all of the above and are the preferred way to handle media in an SVG document as they automatically choose the right type of layer for the given URI.
• Text areas, constructed with $.textArea() contain formatted text inside a rectangular area.

  To edit the text inside a text area, use the .text(), .tspan() and .tbreak() methods.

• Groups, constructed with $.g() create a multi-layer layout.

  Use the .add() method to start adding sublayers inside a group layer, or call .addTo() on a sublayer to make it join a group.

Advanced layer types

The advanced layer types are:

• Playlists, constructed with $.playlist()
• Slideshows, constructed with $.slideshow()
  • Text bars, constructed with $.textBar()
• Crawlers, constructed with $.crawler()
  • Text tickers, constructed with $.textTicker()
  • Media crawlers, constructed with $.mediaCrawler().
• Smart text areas extend the text areas to ensure that the entire text is visible regardless of its length.
  • Headline text areas, constructed with $.headlineTextArea()
  • Fit text areas, constructed with $.fitTextArea()
  • Ping-pong text areas, constructed with $.pingPongTextArea()
  • Scrolling text areas, constructed with $.scrollingTextArea()
• Tables, constructed with $.table()

Interactive layer types

Layers for building interactive content:

• Multi-page, constructed with $.multiPage()
• Carousel, constructed with $.carousel()
• Pop-up, constructed with $.popup()
• Push button, constructed with $.pushButton()
• Progress bar, constructed with $.progressBar()
• Progress wheel, constructed with $.progressWheel()

More types can be added by extending the jSignage library with new constructors.

 

See the full article about how to create interactive content with jSignage.

Common attributes

These attributes are common to all layers in jSignage:

• audioLevel

  Global audio level for the layer between 0 and 1. If not specified, the layer has an audio level of 1.

• begin

  Begin time of the layer, which may be specified as either:

  • A time delay relative to the begin time of the parent layer, e.g. 2.5 or '2500ms'.
  • 'now' to make the layer begin when the .add() method is called.
  • 'now+offset' to make the layer begin with a time offset relative to the time of the .add() call, e.g. 'now+1s'.
  • 'indefinite' to make the layer begin only when .begin() or .show() is called on it.

  Note that when a layer is added with a fixed offset after its parent has begun, this will likely cause the layer to be shown only in part or not at all.

  The default value is 0 when the parent is not in the rendering tree and 'now' otherwise.

• bottom

  Absolute or relative position of the bottom of the layer with regards to the bottom of its parent layer. The default value is 'auto'.

• dur

  Duration. Specify a duration for the active period of the layer. If not specified or if specified as 'media', the intrinsic duration of the layer is used, e.g. the clip duration for a video file.

• frame

  Optional frame and decoration attributes. Default: null.

• height

  Absolute or relative height of the layer. The default value is 'auto'.

• id (strongly recommended)

  Unique string to identify this layers and allow it to be later selected using the $('#id') construct.

• left

  Absolute or relative position of the left side of the layer with regards to the left side of its parent layer. The default value is 'auto'.

• max

  Maximum duration. Specify a maximum duration for the active period of the layer.

• min

  Minimum duration. Specify a minimum duration for the active period of the layer.

• opacity

  Global opacity level for the layer between 0 and 1. If not specified, the layer as an opacity level of 1. Setting an opacity level of 0 disables the layers.

• repeatCount

  Numer of repeat. The default is no repeat. 'indefinite' may be used to loop indefinitely.

• repeatDur

  Repeat duration. Specify that the active interval will repeat during this time. The default is no repeat. 'indefinite' may be used to loop indefinitely.

• right

  Absolute or relative position of the right side of the layer with regards to the right side of its parent layer. The default value is 'auto'.

• top

  Absolute or relative position of the top of the layer with regards to the top of its parent layer. The default value is 'auto'.

• transform

  Rotate and / or flip the content of the layer. The default is no transformation. It is specified as a string which contains one or more of the following basic transforms:

  • flipHorizontal for a horizontal flip;
  • flipVertical for a vertical flip;
  • rotateLeft for a 90° rotation to the left;
  • rotateRight for a 90° rotation to the right.

  For a combination of transforms (separated by spaces), each transform is applied in turn. To apply other transformations, see the complex transformations example.

• viewBox

  Establish a new coordinate space inside the layer area. Syntax: 'x y width height' or 'none'. Default: 'none'.

  By default a layer inherit the coordinate scape of its parent but shifts it so that (0,0) is the top left corner of the layer area. Using the option enables to redefine this coordinate space in order to change its origin or introduce a scaling transform. It is typically use when creating a $.g() layer to draw geometric shapes inside.

• width

  Absolute or relative width of the layer. The default value is 'auto'.

Layer functions

• .add(sublayer)

  Add a sublayer to the selected layer. sublayer can be an element, a jSignage object or an array containing elements or jSignage objects.

  The sublayer begin time (specified by its begin attribute) can be relative to either the begin time of the parent layer or the time of the call itself. Note that the active interval of the parent restricts the active interval of any sublayer.

• .addTo(parent)

  Add the selected layer to a parent (a jSignage object or an element). sublayer.addTo(parent) is equivalent to parent.add(sublayer).

• .begin() or .begin(beginTime)

  Start the layer immediately or after beginTime seconds (if provided and positive).

  If an in-effect has been installed, it will be triggered. If the layer is already active at the moment of call, the layer is restarted (without triggering the out-effects).

  For interactive layers, the begin attribute of the layer is typically set to 'indefinite' so that the layer does not start until the call to .begin().

• .beginEvent(handler)

  Install an event handler (function) to be called when the layer begins.

• .end() or .end(endTime)

  End the layer immediately or after endTime seconds (if provided and positive).

  In the first case, the out-effects are not applied; to avoid this, the endTime parameter should be equal to the duration of the out-effect.

• .endEvent(handler)

  Install an event handler (function) to be called when the layer ends.

  The event handler will not be called if .removeAfter() is set (since its callback function is called instead) or if the layer has the repeatDur attribute set to "indefinite".

• .endsWith(jSignageObject) or .endsWith(jSignageObject, offsetTime)

  Set the layer to end when the jSignageObject ends or after offsetTime seconds after that.

  This is usually used to end an indefinite parent layer (like a group) when a certain child layer is ending (like a video). See also the Conditional ending page.

• .hide()

  Make the layer invisible after applying the out-effects (if any), having the same effect as calling .end(longestOutEffectDuration).

  If the layer is already hidden / not visible, this has no effect.

• .pause()

  Pause a media layer. It does not have any effect on static layers or advanced layers (like playlist, slideshow etc.).

• .removeAfter() or .removeAfter(timeAfterEnd) or .removeAfter(timeAfterEnd, callback)

  After the layer ends, the automatic removal of the layer is triggered, either immediately or after timeAfterEnd seconds (if provided and positive) and, if the second parameter is provided, the callback function is called.

  It is recommended to use this function after .end() or .hide() to remove all dynamically added layers and avoid memory leaks.

  To have the layer visible, yet in a frozen state, for timeAfterEnd seconds, used this function in combination with .setFillFreeze().

  .removeAfter( ) will prevent the handler installed with .endEvent( handler ) from being called; In this case .removeAfter(0, handler) should be used instead.

• .resume()

  Resume a paused layer. It does not have any effect on static layers or advanced layers (like playlist, slideshow etc.).

• .setFillFreeze() or .setFillFreeze(freeze)

  Force the layer to remain visible (frozen on the last frame) after it ends when freeze is undefined or evaluates as true, as opposed to the normal behavior where a layer is made invisible after it ends. This is usually used when the layer duration is smaller that the parent duration and you don't want the layer to disappear when it ends. Note that out-effects are still applied at the end time and the layer might be invisible on its last frame due to that.
  This function should be used before adding the layer to the DOM tree.

• .setInitialVisibility() or .setInitialVisibility(freeze)

  Force the layer to be visible (frozen on the first frame) before it begins, if freeze is undefined or evaluates to true, as opposed to the normal behavior where a layer is made invisible before it begins. This is usually used when the layer is set to begin after its parent, but you want the layer to be visible from the start. Note that in-effects are applied at the layer begin time, thus the layer might be invisible on its first frame due to this.
  This function should be used before adding the layer to the DOM tree.

• .setVisible( isVisible )

  Set the layer visibility according to the isVisible parameter. In fact, this function calls .show() if isVisible evaluates to true or .hide() otherwise.

• .show()

  Make the layer visible after applying the in-effects (if any), having the same effect as calling .begin(0). If the layer is already visible, this has no effect.

  For interactive layers,, the begin attribute of the layer should be set to 'indefinite' so that it is initially hidden.

  Note that subsequent calls to .show() for the same layer will not reapply the in-effect in most cases. The solution in this case, is to recreate the layer entirely.

Examples

Video layer

For example to create a new video layer of size 1280x720 you would use:

$(function(){ 
    $.media({ id: 'movie1', width: 1280, height: 720, href: 'clip.avi' }).addTo( 'svg' );
});

• The $(function(){ ... }); insure that the media is inserted into the document only once all the document content has been loaded.
• The $.media({ ... }) creates the video layer with the specified attributes.
• The addTo( 'svg' ) add the created video in the document as a child of the <svg> element.

Layer order

To add a background image and a video in front of it. The video is in the center of the screen:

$(function(){  
  $('svg').add([ 
    $.image({ href: 'images/1.jpg', id: 'back'}), 
    $.video({ href: 'video/1.avi', id: 'media1', repeatCount: 'indefinite', width: '50%', height: '50%', top: '25%', left: '25%'  }) 
  ]);
});

• The $.image() is added first to the svg element so that it is located behind the $.video()

Multizone layout

You can also easily build multizone layouts:

$(function(){  
   $('svg').add([
        $.image({ href: 'images/1.jpg', id: 'back'}),
        $.media({ href: 'video/1.avi', id: 'vid1', repeatCount: 'indefinite', width: '75%', height: '75%', top: '5%', left: '5%' }),
        $.image({ href: 'images/top.jpg', id: 'img1', width: '20%', height: '20%', top: '5%', right: '0%' }),
        $.image({ href: 'images/bottom.jpg', id: 'img3', width: '20%', height: '20%', bottom: '20%', right: '0%' }),
        $.textArea({ id: 'txt1', width: '90%', height: '15%', top: '82.5%', left: '5%', fontSize: '60px'}).text("Welcome")
   ]);
});

• A background image using the file 'back.jpg'
• A video playing in loop
• Two images aligned on the right of the viewing area
• A text area at the bottom of the viewing area, with the text 'Welcome'

Timings

You can also build automatic layouts with timing information. The example below will split the screen in 4 images and make sure they appear one by one every 2 seconds.

$(function(){  
   for (var i=0; i<4; i++ )
    $('svg').add( $.image({ href: 'images/img'+i+'.jpg', 
                            width: '50%', height: '50%', 
                            top: ((i%2)*50)+'%', 
                            left: (Math.floor(i/2)*50)+'%', 
                            begin: i*2 
                        }) );
});

Complex transformations

Only four predefined transformations (flipHorizontal, flipVertical, rotateLeft, and rotateRight) can be used for the transform attribute when creating a layer. After the layer is added to the SVG DOM, it is possible to also apply "raw" transformations like: matrix, translate, scale, rotate, skewX, skewY, but note that these should be appended to the existing layer transformations, even when the transform attribute is not specified, because other layer attributes might generate transformations (for instance positioning a layer is described internally as a translate transformation).

$.image({ id: 'img3', href: 'resto.png', top: 100, left: 300, width: '30%', height: '30%'
          , frame: { frameColor: 'red', frameSize: 1}
          , transform: 'flipHorizontal rotateRight'
        }).addTo('svg');

// get the applied transformations
var val = $('#img3').attr('transform');

// apply new transformations
$('#img3').attr('transform', val + ' scale(2) rotate(30) skewY(45)');

Note:

For HMP350, HMP300, or older, it's recommended to apply complex transformations on semi-static content (images, text), and avoid them on dynamic content (videos, SVG animations).