JSignage:Crawler

Description

A crawler presents content by scrolling layers through the screen.

The crawler works as well with any type of layer. If the layer is a text area than it works like a scrolling text ticker.

For horizontal crawler, the layers may have variable width like a text ticker, but their height will always be normalized to match the height of a line in the scroll area. For vertical crawler the width will always be normalized to match the width of the scroll area.

Note that the width and height attributes must be specified on the layer being added to a crawler and they must be absolute pixel values. The only exception is for a $.textArea layer where only the height is required for a horizontal crawler, respectively the width for a vertical crawler.

A new crawler is constructed with $.crawler ( { ... } ).

The crawler is part of the advanced layer type.

Specific attributes

All layers share a common set of attributes to define their screen layout and active time interval. Frame decoration may also be used with this layer.

Required:

• data:

  Array of data to show in the crawler.

• renderToSVG: function( index, item, width, height ){}

  Callback to build the layer for on item of data.

Optional:

• direction

  One of 'leftToRight', 'rightToLeft', 'topToBottom' or 'bottomToTop'. Default: 'rightToLeft'

• speed

  Crawling speed in percentage with 100% being one time the height of the layer per second ( or one time half of the width for vertical crawlers). Default: 100.

• smooth

  Round up the speed to the closest value guaranteed to produce a smooth crawl. Default: true.

• spacing

  Spacing between two items in percentage of the line size. Default: 20.

Specific functions

In addition to the list of functions common to all layers, the crawler also supports the .pushData() function.

• .pushData( value1, value2, ..., valueN )

renderToSVG Callback

The renderToSVG( index, item, width, height ) callback will be called once for each crawl item, just before the crawl item become visible.
The number of crawl item is equal to the value of data.length.

Callback parameters

• index

  Item number between 0 and data.length-1.

• item

  Set to data[item] and may be undefined if that item does not exist in the data object. The this object is also set to the same value.

• width

  Width in pixels of the crawler area.

• height

  Height in pixels of the crawler area.

Return value

The callback must return a valid jSignage layer object with both the width and height attribute specified as absolute pixel values.

See also

These layer types are specializations of the crawler:

• Text tickers
• Media crawlers

Examples

Text ticker with inline text

This example displays a ticker of text defined using the data attribute.

$(function(){
    $.crawler({
       data: [ 'Welcome !', 'Bienvenue !', 'Wilkommen !' ],
       renderToSVG: function() {
          return $.textArea({
                height: 32,
                lineIncrement: 24,
                fontSize: 24,
                fill: 'white',
             }).text( this );
        },
        speed: 200,
        repeatCount: 'indefinite'
    }). addTo('svg');
});

Note:

• To create text ticker is is better to use the built-in Text tickers.
• The width of the textArea is not defined, so that it adapts to the different length of text.
• In order to center the single line of text area, the lineIncrement, the fontSize and the height are defined explicitly.
• The crawler will scale the layer returned by the renderToSVG callback to fill the screen vertically (as the default rightToLeft direction is used)

Image Ticker

Displays 4 images and then stops.

$(function(){
    $.crawler({
       data: [ '1.jpg', '2.jpg', '3.jpg', '4.jpg' ],
       renderToSVG: function() {
           return $.media({
              width: 400,
              height: 300,
              href: this
           });
       },
       speed: 50,
       spacing: 5,
    }).addTo( 'svg' );
});

Note:

• To create a media crawler is is better to use the built-in Media crawlers.
• The width and height of the media needs to be set in order to define the aspect ratio of the images.

Displaying Stocks

Create a Crawler displaying stocks. This example retrieve the data from the yahoo web site.

var symbols = [ 'MSFT', 'AAPL', 'HWP.F', 'DELL', 'NOA3.F', 'DTE.DE' ];
 
var uri = "http://finance.yahoo.com/d/quotes.csv?f=snl1c1&e=.csv";
var s = "&s=";
for (var i in symbols ){
    uri += s + symbols[i];
    s = "+";
}
 
function displayStocks( ) {
    var g = $.g( { width: 210, height: 50 } );
    var symbol;
    var color;
    if ( this.Change>0 ) {
        color = 'green';
        symbol = 'up.svg';
    } else if ( this.Change<0 ) {
        color = 'red';
        symbol = 'down.svg';
    } else {
        color = 'black';
        symbol = 'right.svg';
    }
    $.textArea( { height: 50, width: 90, left: 0, 
                  lineIncrement: 25, fontSize: 20, 
                  textAlign: 'start', displayAlign: 'before' 
              } ).text(
                       $.tspan( this.Symbol )
                        .tbreak()
                        .tspan( this.LastTrade )                    
                ).addTo( g );

    $.media( { height: 30, width: 30, left: 90, top: 25, href: symbol } ).addTo( g );
    $.textArea( { height: 25, width: 90, left: 120, top: 25, 
                  lineIncrement: 25, fontSize: 20, 
                  textAlign: 'start', displayAlign: 'before' } )
            .text( $.tspan( this.Change, { fill: color} ) )
            .addTo( g );
    return g;
}
$.get( uri, function( csvData ) {
    var data = $.parseCSV( csvData, ',', [ "Symbol", "Name", "LastTrade", "Change" ] ); // see http://cliffngan.net/a/13 (s n l1 c)
    $.crawler({
        speed: 200,
        repeatCount: 'indefinite',
        data: data,
        renderToSVG: displayStocks,
        top: '75%', height: '20%'
    }).addTo('svg');
}, 'text' );

Note:

• The data is formated on two lines with an arrow depending on the Change to be positive or negative.
• Positive changes are shown in green, whereas negative one are shown in red.
• The script assumes that 3 arrows (up, down, left) are available in the same folder as the script.
• symbols is an array containing the list of symbols to be displayed by the crawler.
• The uri is build using the yahoo csv stock interface. The list of stocks is added to the base address.
• The $.get() is used to retrieve data.
• The $.parseCSV() is used to parse the input data, and map it into a JavaScript array.
• The crawler is used to crawl the different stocks information from right to left. The layout of each stock is contolled by the function displayStocks.
• The function displayStocks( ) displays one stock value. It uses:
  • textArea to display the name and the value of the stock

    The color of the tspan is modified depending on the sign of the change.

    The lineIncrement and displayAlign are used to control the alignment of the different line of text.

  • media to display an arrow indicating if the change is positive, negative or zero.
  • g to group the media and the text area into a single element to be returned. The group width and height are used by the crawler to scale the layout to fit the display area.