Parsing functions

Introduction

This page describes global JavaScript functions that enable file parsing of the following formats: CSV, iCalendar, RSS feeds and XML.

New parsing functions were added within the firmware 3.0 release: parseRSS2, parseCSV2 and getScheduleAsJSON). It is recommended to use them as they are faster, more flexible and easier to use.

Note: The jSignage API also offers such parsing functions (plus an additional support for JSON format) - for more details, see the jSignage parsing functions page.

parseCSV

Node parseCSV(in DOMString data, in Document contextDoc, ...);

Parse the data string (CSV formatted) and return a Node representing the data or null in case of errors.

The optional arguments (...) can be used to specify the names of the columns. If missing, the column names are taken from the first line of the CSV file.

CSV file produced by Microsoft Excel will typically have the column names on the first line.

Examples:

parseCSV( data );
parseCSV( data, null, "title", "description", "price" );

parseCSV2

Array parseCSV2(in DOMString data, in DOMString separator, in Array columnNames, in boolean keepNSWSP, in boolean keepQuotes);

Parses a CSV file to an array of javascript objects.

separator value separator character. Default: ',' (comma).
columnNames Array with the names of the columns, i.e. the names of the properties in the returned array of objects. If undefined, the values on the first line of the CSV file are used instead.
keepNSWSP whether to keep the white spaces at the left and right of the values. Default: false.
keepQuotes whether to skip quotes processing and return them instead. Default: false.

Example:

 var rows = parseCSV2( data, ",", [ "title", "description", "price" ] );

Note: CSV file produced by Microsoft Excel will typically have the column names on the first line.

parseICAL

 iCalendar parseICAL(in DOMString data);

 interface iCalendar {
   Node getScheduleAsRSS( in Date startDate, in Date endDate, in Document contextDoc, in DOMString dateFormat );
   Array getScheduleAsJSON( in Date startDate, in Date endDate, in long maxCount );
 };

The parseICAL global function parses an iCal (RFC2445) data stream and returns an object of type iCalendar (to further access the contents of the calendar) or null if the data is not valid.

getScheduleAsRSS

The getScheduleAsRSS method constructs an XML tree representing the list of events extracted from the calendar. The representation follows the RSS document structure with one <item> tag per instance of an event (note that an event may have multiple instances because of recurrence rules).

The Summary information is mapped to the <title> tag.
The Description information is mapped to the <description> tag.
The start and end date/time for each instance are mapped respectively to the <startDate> and <endDate> tag.
The date is formatted according to RFC822 by default. This may be changed to a custom format with the optional dateFormat parameter, which, if present, should be an strftime format specification string.

getScheduleAsJSON

The getScheduleAsJSON method return an array representing the list of events extracted from the calendar. The array has on object element per instance of an event (note that an event may have multiple instances because of recurrence rules).

Parameters:

startDate A Date object with the start date and time of the period of interest
endDate A Date object with the enddate and time of the period of interest
maxCount Maximum number of events to return. Default: 100.

The instance objects have the following properties:

title Summary field from the event
description Description field from the event
startDate A Date object with the start date and time of the event instance
endDate A Date object with the end date and time of the event instance
enclosure URL field from the event
location Location field from the event

Example

To get a list of events for today, use something like this:

 var ical = parseICAL( ical_data );
 var now = new Date();
 var start = new Date( now.getFullYear(), now.getMonth(), now.getDate() );
 var end = new Date( now.getFullYear(), now.getMonth(), now.getDate()+1 );
 var schedule = ical.getScheduleAsJSON( start, end );
 
 for ( var i=0; i<schedule.length; i++ ) {
   var item = schedule[i];
   // ...
 }

parseRSS

Node parseRSS( in DOMString data, in Document contextDoc, in DOMString baseURI );

Works like parseXML, but uses an RSS/Atom parser that supports "RSS tag soup": non-conforming XML documents produced by many RSS applications. The parser detects the version of RSS or Atom used and returns a uniform clean XML tree with an <rss> tag at the root with a collection <item> tags underneath.

The baseURI parameter is optional and seldom needed.

The following elements of the RSS feed are recognized within the original RSS data: title, description, enclosure and pubDate.

parseRSS2

Array parseRSS2( in DOMString data, in DOMString baseURI, in DOMString channel, in boolean multilineTitles );

Parses and RSS feed with an RSS/Atom parser that supports "RSS tag soup": non-conforming XML documents produced by many RSS applications. The parser detects the version of RSS or Atom used and returns a uniform an array of objects, one for each RSS item.

Parameters:

data RSS feed content
baseURI Base URI for the RSS URIs (should be left blank)
channel When defined, only the items for that channel are returned. By default all items for all channels are returned.
multilineTitles When false, only the first line of text is returned in the title property. Default: false.

The return objects have the following properties:

channel Name of the channel
channelTitle Title field of the channel
channelDescription Description field of the channel
image Image field of the channel
item Name of the item
enclosure URI associated with the item (the enclosure or url field if present, or the src of an <img> tag in the description field)
title Title field of the item
description Description field of the item
pubDate pubDate field of the item

parseXML

Node parseXML(in DOMString data, in Document contextDoc);

The parseXML function parses the data string as an XML document and return a Node representing it. If the XML in the string is not well-formed, the return is a null value.

Example:

var doc = parseXML( '<top><child/></top>' );
alert( 'top level is: ' + doc.documentElement.localName );
alert( 'first child is: ' + doc.documentElement.firstElementChild.localName );