Feed widgets in Elementi 3.x

This page is about the data feed widgets included into Elementi 3.x Library. For other versions, see the Data-driven widgets page.

Introduction

The feed widgets have been designed to ease up the creation of content that display data extracted from common types of data feeds (e.g., RSS, CSV, ICAL, Text, XML, JSON etc.) from local / external data sources.

The list of files within a directory can also be used as data feed source. See Directory listing parser section below.
Other text formats are supported through custom JavaScript parsers.

More information about feed parsing in general can be found inside the "Data Feeds" PDF documentation. Also check the Tutorial on customizing data feed widgets pages for more advanced usage of the data feed widgets.

Widgets

In Elementi 3.x, the feed widgets are included into the "Feeds" collection within Elementi Library. The files are named by combining four basic types of data format with seven data layout types - this combination is reflected in the feed widget name.

Data layout	Data format				Notes
Data layout	Spreadsheets	Medias	Calendars	RSS	Notes
Text Bar	CSV Text Bar		ICS Text Bar	RSS Text Bar	Display one or more lines of text at the time. If the text is longer than the available space, line will be shifted up, one by one. The number of lines and the transition can be configured by the user.
Text Ticker	CSV Text Ticker			RSS Text Ticker	Display text using an horizontal ticker. Speed and direction can be configured by the user.
Text Roll	CSV Text Roll			RSS Text Roll	Display text using a vertical text roll. Number of lines, speed can be configured by the user.
Playlist		File Playlist		RSS Playlist	Display images or video in sequential order. The transition can be configured by the user.
Crawler		File Crawler		RSS Crawler	Display images or video using an horizontal or vertical crawler. Direction, speed and spacing can be configured by the user.
Slideshow	CSV Slideshow		ICS Slideshow	RSS Slideshow	Display image, video or text using an user defined layout. This is a more generic version of the playlist where the layout can be fully customized. The transition can be configured by the user.
Table	CSV Table		ICS Table	RSS Table	Display image, video or text using a user defined layout. This is a more generic version of the Slideshow where multiple items can be displayed on the same slide.

Notes:

The widget options are limited for Elementi S and Elementi M users and only the predefined data format can be used.
Elementi X users have full control on the feeds configuration (including changing of the predefined data format to any of the available parsers) and a lot more options. Furthermore, they can customize these widgets to add more functionalities, like adding caching instructions to the feed widgets (by default, the feed widgets from Elementi do not cache the data feed source).

Working with data feed widgets

When working with data feed widgets, the following major steps can be identified:

Configure the data source (location, limit, formatting, filtering, sorting etc.).
Configure the parser and formats used (advanced settings).
Configure the data layout used to display the resulted data.

These steps are further detailed below.

Data source

Opening Feeds dialog

All feed widgets let the user configure the source of the data and test the feed if needed.

To configure the data source, press the source icon next to the data source properties.
The content of the feeds dialog depends on the Elementi license.

Simplified configuration

Simplified Feeds dialog

Elementi S and Elementi M users

The simple Data source properties let the user configure:

The address of the feed (URI or shared variable name)
The number of item to be displayed
The refresh frequency (added in 3.1.0)
Enter a number, optionally followed by s (implicit), m or h (to specify seconds, minutes or hours) to activate a timer that will try to periodically refresh the feed data, which is useful especially when the feed widget is running in a loop.

Enter the keyword never or 0 to prevent the above feature.

The simplified data source dialog do not let the user configure the type of the feeds.

Full configuration

Feeds dialog

For Elementi X users, the "Data source" configuration dialog contains much more options as detailed below:

Type
Select the type of data source. It can be one of the following:
- URI: The data source is a remote resource retrieved from an HTTP(S) server (using a GET request).
- Shared variable: The data source is a shared variable (its value is used as data), thus the data will be updated each time the shared variable is modified.
- Inline data: the data source is an element (typically a text) present within the current document.

URI / Variable name / Selector
Enter the URI, Variable name or Selector controlling where the data is 'located'.
- When using inline data, CSS3 selector syntax is used to identify where the data to be displayed is located in the current document. For instance using title will use the content of the first <title> element if the document as the data source.

Refresh (added in 3.1.0)
Enter a number, optionally followed by s (implicit), m or h (to specify seconds, minutes or hours) to activate a timer that will try to periodically refresh the feed data, which is useful especially when the feed widget is running in a loop.

Enter the keyword never or 0 to prevent the above feature.

Parser
Select the main parser for the data (it needs to match the type of data present within the data source). The selected parser controls the content of the "Parser ___" tab. It can be one of the following: RSS, XML, JSON, CSV, RegExp, ICS, Script, Directory listing or Query String

Format
Add additional parsing rules to be applied on the fields returned by the main parser. It is possible to add as many formatting rules as needed and the formatting parser can be (and usually is) different than the main parser.
- To add a new formatting rule, select or enter the target field in the first box, the type of parser in the second and press the "Add" button. This will create a new tab called "'field_name' Parser". To remove the parsing rule, press on the red icon on its tab.

Sort
Specify a sorting rule to be applied to the data. Only one field can be specified for the sorting.
- To specify a sorting rule, enable this option, select or enter the target field in the first box, the type of sorting in the second and the direction in the third.

Filter
Starting with Elementi 3.1.0, this option has been replaced by the format filters: Num. Filter, Date Filter and String Filter
Specify a filtering rule to be applied to the data. The rows for which the condition evaluates to true are kept, the others are removed. Only one column can be specified for the filtering.
- To specify a filtering rule, enable this option, select or enter the target field in the first box, the type of comparison in the second box and the value to compare against in the third box. Note that for fields representing dates, the value should be the number of milliseconds since 1 January 1970 00:00:00 UTC (as returned by getTime() date function or by EpochConverter site).

Limit
Enable this option to specify the maximum number of rows (items) to be kept (starting from the first row in the data set).

Testing feeds

Testing feed dialog

All Elementi users

Once the URI of the feeds has been entered, pressing the Test... button will display a new dialog. The dialog is composed of at least 2 tabs, but may contains more depending on the parser and formatting used on the input.

The first tab shows the raw data
The next tab shows the result of the parsing, the data being displayed as a table. The column names can be to display the feeds. For instance to display the content of the column called title, use [[title]] when editing the layout.

Fallback

All Elementi users

Feeds fallback dialog

The "Fallback" tab allows defining, for each field / entry of the result set, the following two values:

Default
The default value is used when the data for that field is missing from the result set. For instance, you can specify a default image to be used in case the feed does not provide an enclosure field.

Note that this in not used if the feed cannot be retrieved or there are no results to be displayed.
Placeholder for edition
This value has no influence other than "cosmetic" and is used when switching a feed widget into edit mode (i.e. one click on the Preview panel), instead of the actual field placeholder (i.e. [[field]]).

Note that clicking one more time on the field layer will display the field placeholder, so you can edit that layer.

Parser and format

RSS parser

Feeds RSS parser dialog

Input data is an RSS feed. See parseRSS2() and $.parseRSS() for more.

All formatting present in the RSS feed are discarded.
Only four fields of the RSS item element are recognized: title, description, enclosure and pubDate.

Configurable properties:

Channel
If the RSS feeds contains multiple channel, specify which channel to be used. If not set, the first channel is used.

XML parser

XML parser dialog

Input data is an XML file. Any XML document structure is supported. See $.parseXML() for more details.

Configurable properties:

Selector
Selector for the data rows. CSS 3 selectors syntax is used to identify the data rows. For instance, you can use:
- row to select all the elements of the XML file named <row>;
- table > tr to select all <tr> elements inside a <table>;
- Cube > Cube > Cube to select the third level Cube element from ECB daily exchange rate XML data. (see example #2)

Specify output
Allows to create different output columns based on the XML structure.

When not used, every child element found under the data rows is mapped to a column in the output data. (see example #1)
When enabled, you can specify a custom mapping (see example #2). The following fields are provided:
- Name -> enter the name of the new column; (this name will be used for the data layout special notation, i.e. [[column_name]])
- Type -> select between String, Number, Date and XML; (the type is useful for sorting)
- Selector -> enter the selector (same syntax as above) that retrieves the child element.
- Attribute -> enter the child element attribute that gives the output data value.
Example: See the configuration shown in the image on the right.

Example #1

The XML code bellow is automatically mapped into 2 columns: title and content. There's no need to specify the output in this case.

<document>
  <row>
    <title>Lorem ipsum</title>
    <content>Lorem ipsum dolor sit amet</content>
  </row>
  <row>
    <title>Lorem ipsum</title>
    <content>Lorem ipsum dolor sit amet</content>
  </row>
</document>

Example #2

To parse the ECB daily exchange rate XML and retrieve the currency data, do as shown in the image on the right:

Set the selector to Cube > Cube > Cube, which selects the third level Cube element containing the data.
Specify a "currency" output column that takes the value from the "currency" attribute of the selected element.
Specify a "rate" output column that takes the value from the "rate" attribute of the selected element.

A sample XML content is shown bellow:

<Envelope>
<Cube>
  <Cube time="2013-04-23">
    <Cube currency="USD" rate="1.2990"/>
    <Cube currency="CHF" rate="1.2219"/>
  </Cube>
</Cube>
</Envelope>

JSON parser

Feeds JSON parser dialog

Note that the selector are not working in the 3.0.0 firmware, you need at least 3.0.1

Input data is a JSON description of a JavaScript object or array.

Configurable properties:

Selector
Selector for the data rows. Use JavaScript syntax to identify the location of the rows. For instance use main.rows to select an array called rows inside the main object. To retrieve one element of an array use the following notations: main.1.rows.
Specify output
If checked, the user can create a custom mapping between the json input and the output.

The JSON dialog screenshot shows the configuration needed to parse the Open Weather Map result for the city of Lausanne

CSV parser

Feeds CVS parser dialog

Input data is an CSV file. Make sure that the file is encoded using UTF-8 for proper formatting of the output. See parseCSV2() and $.parseCSV() for more.

Configurable properties:

Separator
Specify the column separator. The following separators are supported: ",", ";", "|" and tab.

CSV fields are not quoted
When checked, the input data is assumed to be not quoted. When not check, automatic quote detection is done.

Specify column headers
If the data file does not have column headers, they can be specified here. It is also possible to specify the format of the data (date or number instead of the default string).

Text (RegExp) parser

Input data is a text file that can be split into multiple lines of data. The text parser uses regular expressions (RegExp) to map the input text to rows and columns of data. If nothing is changed on the "Parser RegExp" tab, then each line of the input text file is put into a new row having a single column called title.

For a sample project using the RegExp parser, see List Of Movies Project.

Parser RegExp configuration

Configurable options:

Split
Specify a string or a regular expression to be used as separator for splitting the input data into rows. The separator itself is not included in the final data.

Default value (when enabled): [\r\n]+
This is a regular expression that splits the original text using the end-of-line characters, thus each line from the text file becomes a row in the results set.
Examples:
- Use "\s+" to split the text input so that every word is on a new row.
- Use ";" to split the text input into rows after each semicolon character.

Match
Specify a regular expression to be used by the match function to generate the output data. Only the text matched will be used in the output data.

If the regular expression is empty, then the entire content is put on a single row of output data.

The RegExp engine tries to use the match expression multiple times and, in case of success, each match creates a new row of data.

If the "Specify output" option is not enabled, then the results are put in a single column named "title".

If the regular expression contains match groups (i.e. round brackets pairs), then each match group can be assigned to a new column under the "Specify output" option.

Default value: (.*)
This is a regular expression that will map each input line to a new row (because in JavaScript, ".*" matches all the characters except the new-line (\n) character).
Examples:
- Use ".{10}" to have each match of 10 characters (excepting the new-line character) assigned to a row of data.
- Use "[\s\S]{50}" to have each match of 50 characters (including the new-line character) assigned to a row of data.
- Use "(\S*)\s(.*)" to have each line of the input text assigned to a new row of data and to extract the first word and the rest in two columns configurable under the "Specify output" option (as shown in the image on the right) within each row.

Specify output
Allows to create different output columns based on the match groups (i.e. round brackets pairs) used within the regular expression (entered under "Match" option).
When enabled, you can specify inside the mapping table the following:
- Name -> enter the name of the new column; (this name will be used for the data layout special notation, i.e. [[column_name]])
- Type -> select between String, Number and Date; (the type is useful for sorting)
- Match # -> enter the index of the numbered capturing group starting from 1. (index 0 refers to the entire match)
Example: See the configuration shown in the image on the right.

ICS (iCalendar) parser

Feeds iCal parser dialog

Input data is an ICS (iCalendar) file. See the parseICAL() and JSignage:Parsers#iCalendar_parser pages for more details on the parsing functions and the ICS feeds page for different ways to generate ICS files.

Configurable options:

From
Specify the starting date/time for the data to be displayed. The following options are possible:
- Date
  Specify an absolute starting date and time for filtering the data. No events before this date will be included in the final data.
- Relative
  Specify a relative starting date an time for filtering the data. Possible values includes Now, Today, Tomorrow, etc. The filtering rule is executed at the opening of the file.
- Custom
  Specify a starting date using a custom date string.

To
Specify the ending date/time for the data to be displayed.
- Date
  Specify an absolute ending date and time for filtering the data. No events after this date will be included in the final data.
- Relative
  Specify a relative ending date an time for filtering the data. Possible values includes Now, Today, Tomorrow, etc. The filtering rule is executed at the opening of the file. When using Today for instance all events happening today will be added to the data.
- Duration
  Specify a duration relative to the starting time.
- Custom
  Specify a ending date using a custom date string.
- Indefinite
  Specify that all events after the starting date must be included in the output data.

Custom date string

The custom date string can be entered using any of the following formats:

offset relative_date
time
offset relative_date time
offset relative_time

offset
The offset applied to relative_date or relative_time as a signed integer (e.g., -12, -5, -1, +1, +2, +30 etc.) or the word this (instead of using 0).
relative_date
The relative date specified using one of the following keywords:
- day, days,
  Examples: "this day", "+1 day", "-5 days".
- month, months, month-dd, months-dd,
  Note: dd is a fixed day during that month.
  
  Examples: "this month", "this month-10" (means the 10th day of the current month), "+1 month-31" (means last day of next month);
- year, years, year-mm, years-mm, year-mm-dd, years-mm-dd,
  Note: mm is a fixed month and dd is a fixed day during that year.
  
  Examples: "-1 year" (means last year), "this year-12-1" (means December 1st of this year);
- monday, tuesday, wednesday, thursday, friday, saturday, sunday (i.e. the day of the week in lowercased English format)
  Examples: "this monday" (means Monday of the current week starting on Monday; thus, on Sunday, this actually means next Monday).
time
The fixed time during the specified date, if any, using hh, hh:mm, hh:mm:ss.

If not provided, then 00:00:00 is used for start date (From) and 23:59:59 is used for end date (To). If some or all time-notation elements are provided, they are replaced within the default ones.

Examples: "15" (defaults to 15:00:00 for start date, respectively 15:59:59 for end date), "07:30", "22:50:45".
relative_time (added into 3.1.0)
The relative date specified using one of the following keywords: "hour", "hours", "minute", "minutes", "second", "seconds".

Examples: "-3 hours", "+5 minutes", "+150 seconds".

Script parser

Feeds script parser dialog

The Script parser can be used whenever the build-in parsers detailed above do not fit the input data and / or additional transformations need to be performed.

Configurable properties:

URI
Specify the name of the JavaScript file containing the custom parser. If the JS file is not in the same place as the feed widget, include the path as well.

Default value: "custom.js".
Function
Specify the name of the function used to process the input data. This function must be implemented in the JS file specified above and must return a certain value as explained below. This function will be called once when applied as the main parser and once per data to process when applied as a formatting function.

Default value: "parse".

Return value

The value returned by the parsing function can be one of the following types:

String. ('foo')
The string value is assigned to the title column when used as the main parser or it will replace the input column value when formatting an existing column.
Object ({ col1: 'foo', col2: 'bar', col3: 5, ... })
Each value (e.g. 'foo', 'bar' etc.) is assigned to the column matching the key (e.g., col1, col2 etc.). If the columns don't exists in the result set, they are created.

Returning an empty object (i.e. { }) means that there's no change to perform.
Array ([ v1, v2, ... ])
Each value of the array generates a new row of data. The values (e.g., v1, v2 etc.) can be a String or an Object as described above.

Examples:
[ 'foo', 'bar' ]

[ {col1: 'foo', col2: 'bar', col3: 5 } , {col1: 'baz', col2: 'qux', col3: 15 } ]

Examples

Example 1 - check the input data to see if this is a fruit or a vegetable, and create a new column called type within the result set.

function parse( data ) {
  if ( data=="Bananas" || data=="Oranges" )
    return { type: "Fruits"};
  if ( data=="Carrots" || data=="Potatoes" )
    return { type: "Vegetable"};
  return { type: "I cannot eat this" };
}

Note: This kind of structure can be used to replace the switch template used in HMD.

Example 2 - split the input data lines (i.e. the new-line character) into multiple rows, each having 3 columns.

function parse( data ) {
  var result = [];
  var lines = data.split( '\n' );
  for (var i=0; i<lines.length; i+=3 )
    result.push( { l1: lines[i], l2: lines[i+1], l3: lines[i+2]	} );
  return result;
}

Example 3 - convert the input data from an UNIX / JavaScript timestamp into a date.

function dateFromUnixTimestamp( data ) {
    return new Date( data * 1000 );
}

function dateFromJSTimestamp( data ) {
    return new Date( parseFloat( data ) );
}

Note: Other custom parsing functions returning a date can be found within dateParser.js file.

Directory listing

Feeds directory listing dialog

Input data is a path to a collection of files included in the project or an URI to remote location located on a WebDAV enabled web server. The directory listing parser lists (using propFindURL function) the files and / or directories present on that location according to the specified filter. It can only be used as a main parser.

For each item of the result set, it generates the following output columns:

creationdate: Creation date of the file / folder.
filename: Name of the file / directory (without the path).
getcontentlength: Size of the file in bytes or "null" for directories.
getetag: Unique identifier for the file (can be used to check if the file has been modified) or "null" for directories.
getlastmodified: Last modification date for the file / folder.
href: Path to the file (can be used to display the media file).
resourcetype: Resource type - "collection" or "null" (for files).

Configurable properties:

Show hidden files
Enable this to list all files (including the ones starting with a dot).
Resource type
Specify the type of resources to be reported. Supported values are: "All", "Files", "Directories".
Filter
Specify the file extension filter to be applied on the result set. Either select one of the existing filters or enter a custom one. Multiple extensions can be used for the filter - simply separate them using semicolons.

For instance, a filter for listing both video and audio file can look like this: *.mp4;*.avi;*.wmv;*.mpg;*.mp3;*.wav;*.wma;*.m4a;*.aac

Note:

To test WebDAV servers requiring authentication within Elementi, first enter the server as a Publish Location and access at least once, so that Elementi can use the server credentials for subsequent calls to retrieve the content of a folder from that server.

Num. filter

Feeds numerical filter dialog

Added in Elementi 3.1.0.

This option is only available in Format, and can be used to filter the input data based on some numeric values.

Configurable properties:

Equals
The numerical value must match exactly the user input.
Not Equals
The numerical value must not match the user input.
In Range
The numerical value must be in the range specified by the user.

Date filter

Feeds date filter dialog

Added in Elementi 3.1.0.

This option is only available in Format, and can be used to filter the input data based on a date

Configurable properties:

From
Specify the starting date/time for the data to be displayed. The following options are possible:
- Date
  Specify an absolute starting date and time for filtering the data. No events before this date will be included in the final data.
- Relative
  Specify a relative starting date an time for filtering the data. Possible values includes Now, Today, Tomorrow, etc. The filtering rule is executed at the opening of the file.
- Custom
  Specify a starting date using a custom date string.

To
Specify the ending date/time for the data to be displayed.
- Date
  Specify an absolute ending date and time for filtering the data. No events after this date will be included in the final data.
- Relative
  Specify a relative ending date an time for filtering the data. Possible values includes Now, Today, Tomorrow, etc. The filtering rule is executed at the opening of the file. When using Today for instance all events happening today will be added to the data.
- Duration
  Specify a duration relative to the starting time.
- Custom
  Specify a ending date using a custom date string.
- Indefinite
  Specify that all events after the starting date must be included in the output data.

String filter

Feeds string filter dialog

Added in Elementi 3.1.0.

This option is only available in Format, and can be used to filter the input data based on some numeric values.

Configurable properties:

Equals
The string value must mach exactly the user input.
Not Equals
The string value must not mach the user input.
Matches
A regular expressions (RegExp) that must match the string value.

Data mapping

The mapping between the data retrieved from the data source and the layers composing the layout of the widget is done using a special notation having a double-pair of square brackets: [[label]], where "label" is the name of one of the columns displayed inside the "Feed Test" window (e.g., [[title]], [[description]], [[enclosure]], [[pubDate]] etc.).

When the feed widget is running, each instance of [[label]] is replaced by the content existing in the "label" column. Thus, using the special notation [[title]] will display the contents of the column called "title" (for instance, the title of an RSS feed item).
It is possible to format dates, times and numbers according to the selected locale, using a combined notation like [[label>format]], where the format is specified using the special date/time patterns or number patterns.

Data layout

Depending on the type of feed widget used, the layout for displaying the feed data is constructed using either:

A text layer (for Text Bar, Text Roll and Text Ticker feed widgets),
A media layer (for Crawler and Playlist feed widgets),
A combination of text & media layers (for Slideshow and Table feed widgets).

Text template

Controlling text layout

For Text Bar, Text Roll and Text Ticker feed widgets only text content can be displayed. The layout is configured using the "Text template" property available under the "Properties" view.

Click on the edit icon to open the "Edit text" dialog box (as shown on the right);
Enter the text content; both regular text and special notations (where the feed data from the corresponding column is inserted) can be used.
- Font changes can also be applied to the text content, however, in the case of special notations, any change must be applied to the entire string including the square brackets.
- Also, note that the font size is calculated automatically within the feed widget, thus any changes here will be ignored. See this tutorial for ideas about how to modify the feed widget to allow different font sizes.
Press the "OK" button to save the changes.
If required, change the other feed widget properties (such as number of lines to be displayed or transition to be applied).

Media template

Controlling media layout

For Crawler and Playlist feed widgets, only media files can be displayed (using the entire area available). The layout is configured using the "Media template" property available under the "Properties" view (as shown on the right).

Click on the layer properties button.
Set the URI using the special notation to point to the media to be displayed.
- By default, the URI is set to be [[enclosure]]. If the data feed contains the media location within another field (column), then the URI should be adapted accordingly.
- It is also possible to create a custom URI based on a special notation and a predefined text (for instance http://my_server/images/[[name]].png).
Change the other standard media layer properties (e.g., media fit, media align, formatting, effects etc.).
Press the "OK" button to save the changes.
If required, change the other feed widget properties (such as looping, transition, direction, speed etc.).

Text & media layers

Complex data feed layout

For Slideshow and Table feed widgets, the layout is configured using both text & media layers (using special notations as described above). These are available under the "Layers" view.

It is possible to add and remove layers and to modify their position within the Preview panel.
When clicking on the Preview panel, the document is automatically paused and the fallback values are used instead of the actual data. Further clicking on a layer will display the special notation used (e.g., [[title]], [[description]] etc.). If no fallback values are configured, the special notations used for the layers are shown directly.
Pressing the play button, will resume the playback and display the content of the data feed.

Troubleshooting

Message:

Crawler / Text bar / Text ticker is looping inside a schedule and thus will not be synchronized

Description:

The alert message is usually displayed when the widget is included into a multiscreen project or a schedule file and it is set to loop - in which case, it may cause synchronization problems. The solution is to disable the widget's looping property.
This message can also be received within regular projects, when dragging the project timeline or when any manipulation is done on the feed widget after 12 hours of playing time - in this case the alert message can safely be ignored.

Message:

The playlist is set to loop and its total duration cannot be determined; using the playlist within a schedule or a multiscreen project might cause problems.

Description:

Same as above; see more details on the playlist troubleshooting section .

Feed widgets in Elementi 3.x

From SpinetiX Support Wiki

Contents

Introduction

Widgets

Working with data feed widgets

Data source

Simplified configuration

Full configuration

Testing feeds

Fallback

Parser and format

RSS parser

XML parser

JSON parser

CSV parser

Text (RegExp) parser

ICS (iCalendar) parser

Custom date string

Script parser

Return value

Examples

Directory listing

Num. filter

Date filter

String filter

Data mapping

Data layout

Text template

Media template

Text & media layers

Troubleshooting