HMD news templates

This page is related to HMD Templates page. Also check the Data feeds page for more advanced usage of the news templates.

Introduction

These templates are used to display news from a single feed source specified by its URI or as inline (e.g. the news items are entered directly in HMD).
The source of the data could be one of the following: RSS, XML, Text, CSV or ICAL (iCalendar) to use with a predefined feed parser, but it could also be in another format (for instance HTML or multi-level XML files), in which case a custom parser will be needed. See Data feeds page for more details.
See also the "Special News templates" section from the HMD User Manual.
The templates are split in two categories: layout templates and format helpers.

Note: A set of HMD sample projects, demonstrating the usage of data feeds from various sources, was archived under Data Feeds project page, version from Oct 10th, 2011.

Layout templates

news.svg : Displays news in a user customisable format. It supports single or multiple news items per page.
- The files news_16_9.svg and news_4_3.svg are variants of this file, with pre-defined dimensions.
news_ticker.svg : Display news text in a scrolling banner (left/right or top/bottom).
news_crawler.svg : Display formatted news using scrolling (left/right or top/bottom).
- Can also be used as a ticker to display logo/media or multi-lines of content.
- Should be used with caution (e.g. only for simple projects) since it's very CPU consuming, especially in the case of HMP100.

Notes on XML data feeds

The built-in XML parser can only be used when the XML feed source is in simple, table-like format (e.g. table > rows > columns).
For XML feed sources in a different format or with multiple levels, a custom parser needs to be used.

Notes on ICS data feeds

Field mappings for ICS files - when using feed type "ICAL", the following mappings exist between the ICAL properties and the [SPX][xxx] label:
- "title" - corresponds to the event summary
- "description" - event description
- "startDate" - event start date (and time) in RFC822 format
- "endDate" - event end date (same details apply)
- "enclosure" - event URL
- "location" - event location

If the conditions from the iCal property group (Start date & End date) need to be re-evaluated after a certain period of time, make sure to reload the SVG document (e.g. the news template) as often as needed. For instance, if the "Start date = now" condition must be evaluated every minute, then:
1. On the news document set a fixed duration (e.g. 00:01:00 instead of media) and make it to repeat forever.
2. Inside the news document, set the "Feed Update Policy" to "document load". (This is to avoid unnecessarily checks for updates of the feed source)

Notes on CSV data feeds

The data is provided as a two-dimension table (like a spreadsheet) with each row being a record and each column being a field. The fields are separated by commas (,) and, preferably, enclosed by quotes ("). The special characters: comma, quote and new line, usually need to be escaped.
The first row of the CSV file must contain the column name, that will be used within [SPX][column_name] labels inside the news template.

Custom parser

Whenever the built-in data feed parsers are not sufficient, a custom parser is needed. This is a JavaScript file (with .js extension - "parser.js" for instance) that implements a function named custom_parser( response, records ).

response - this parameter receives the raw data feed that needs to be parsed (e.g., the server response to the HTTP GET request).
records - this parameter is a JavaScript array and will be populated with the information that needs to be returned to the news template.

function custom_parser( response, records ) {
   // your code goes here ... 
}

Using Custom parser

In order to use this custom parser inside your project, follow these steps:

Import the custom parser file into your project.
Open the news template that will use this custom parser.
On the "Properties" tab, enter the name of that file (e.g., parser.js) as value of the "Feed Type" property.
Save and verify that the data is correctly parsed and displayed.

Note: The "Feed Update Policy" options apply to the feed source, but do not apply to custom parsers in the same manner because the custom parser code is executed when the news template is opened or the data source is updated. If you need the custom parser to be executed more often, ensure that the news template is reopened (by setting a fixed duration).

Three examples of custom parsers are presented below, for more please see the technical documentation and the sample projects from Project:Data feeds page.

XML Parser example

Let's say that the source data is an XML file with the following structure:

<?xml version="1.0" encoding="UTF-8" ?>
<data>
   <record id="10" name="IR 2528" time="17:17">0:33</record>
   <record id="11" name="IR 1428" time="17:20">0:44</record>
</data>

Using the built-in XML parser would not return anything since the data in not in the expected format (and moreover, the built-in parser is not retrieving the values of the attributes). In this case, the custom parser would look like this:

function custom_parser( response, records ){
   var rssDocument = parseXML( response );
   if ( rssDocument==null ) return;
   for ( var row=rssDocument.documentElement.firstElementChild; row!=null; row=row.nextElementSibling ) {
      var r =  new Object();
      r.id = row.getAttribute('id');
      r.name = row.getAttribute('name');
      r.time = row.getAttribute('time');
      r.duration = row.textContent;
      records.push( r );
   }
}

Note: Inside the news template, the four text layers will have the following values: [SPX][id], [SPX][name], [SPX][time] and [SPX][duration].

Text parser example

Let's say that the source data is a text file where each line is having informations about the name, price and description of a product, separated by semicolon (;). Using the built-in TXT parser would return the entire line in one field, but we want to have the information split into three fields (to make the price red, for instance). In this case, the custom parser would look like this:

function custom_parser( response, records ) {
   for each ( var line in response.split( '\n' ) ) {
      var r = new Object();
      var npd = line.split( ';', 3 );
      r.name = npd[0];
      r.price = npd[1];
      r.description = npd[2];
      records.push( r );
   }
}

Note: Inside the news template, the three text layers will have the following values: [SPX][name], [SPX][price] and [SPX][description].

CSV parser example

Let's say that the source data is a csv file and we want to limit the number of items to be displayed, based on a certain condition; the custom parser would look like this:

function custom_parser( response, records ) {
  var rssDocument = parseCSV( response );
  if ( rssDocument == null ) return;
  for ( var row=rssDocument.documentElement.firstElementChild; row!=null; row=row.nextElementSibling ) {
    var r = new Object();
    for ( var col=row.firstElementChild; col!=null; col=col.nextElementSibling ){
      r[col.localName] = col.textContent;
    }
    if ( some_condition ){
      records.push( r );
    }
  }
}

Note: Inside the news template, the text layers will contain [SPX][column_name] texts, where column_name matches the values from the first row of the csv file.

See also parseCSV2 function.

Other notes

By default, all the feed items are returned and displayed - if you want to limit the number of displayed items, use a custom parser.
The news templates are used to display items from a single feed source specified by its URI or as inline (e.g. the news items are entered directly in HMD).
- To display items from multiple sources, either write your own JavaScript code (without using the news templates at all) or use a playlist of news templates (one for each feed source).
If there are no items for a data feed and the news template is included into a playlist, nothing will be displayed for a certain period of time (playlist's default slide duration). To "skip" that feed within the playlist, open the news template file in an external text editor, find function rss_callback( status ) and inside it, change this line:
```
svg.setAttribute( "dur", rss==null ? 0 : Math.ceil(rss.length/num_row/num_col)*item_dur );
```
to be like this:
```
svg.setAttribute( "dur", rss==null || rss.length==0 ? svg.getCurrentTime()+0.001 : Math.ceil(rss.length/num_row/num_col)*item_dur );
```

Feed update policy

Each news template allows changing of the feed update policy by setting the value of the "Feed Update Policy" property, as following:

document load
- The feed source data is checked for updates only when the news template is opened.
- This is useful if the feed source is inline, not expected to be changed or if the news template will be reopened after a certain amount of time (for instance, it's part of a playlist, it has a fixed duration + set to repeat etc.).
at end
- The feed source data is checked for updates after all the items have been shown once and if it's the case, the source will be updated before looping.
- This is the most commonly preferred setting.
next item
- The feed source is checked for updates after each item is shown. If the source has changed, the content will be reloaded and be displayed from the beginning again.
- This is useful if each item is displayed for a longer period of time and "at end" option might not be sufficiently fast.

These settings do not override the default Caching mechanism of the player! If the data feed is currently being cached, the HMP will use the version from its cache without checking the server for updates, regardless of the update policy value.

No caching

In case you need to force the player not to use the caching system for the data source, then follow these steps:

Open the SVG including the "news" SVG file.
For the "news" layer, change the duration from media to a fixed duration (i.e. 600s) and make sure it is to repeat forever.
Open the "news" layer and set the Feed Update Policy to "document load".
Open the "news" SVG file from your project (not the template itself!) in an external text editor.
Find the call to the getURL method within the JavaScript code and remove the last parameter (flags). See more details below.
Save the SVG file and reopen your project.

At step #5:

 // replace the existing line:
getURL( uri, rss_callback, policy=="document load" ? GETURL_CACHE_CONTENT : (GETURL_CACHE_CONTENT|GETURL_TRACK_CHANGES) );

//with this one (without the flags):
getURL( uri, rss_callback);

Since firmware 3.0.1, you can force the caching to to be extremely low, but still present (in case the device do not have access to the Internet for instance). In this case add the GETURL_ALWAYS_CHECK flag, instead of removing all flags:

//replace the getURL() with this one (with all the  flags):
getURL( uri, rss_callback, policy=="document load" ? 
                           (GETURL_CACHE_CONTENT|GETURL_ALWAYS_CHECK) : 
                           (GETURL_CACHE_CONTENT|GETURL_ALWAYS_CHECK|GETURL_TRACK_CHANGES) 
      );

Format helpers

date_time.svg : Display a date/time of each news item according to the "Date source" property (e.g. "now", "pubDate", "startDate", "endDate") in a formatted manner (see PHP Date format options).
- It accepts the following format modifiers: 'Y' 'y' 'F' 'm' 'M' 'n' 'd' 'D' 'j' 'l' for date and 'a' 'A' 'g' 'G' 'h' 'H' 'i' 's' for time.
- To use AM / PM for time, change the format to "D, j M Y h:i:s A" for example.
- For a dynamic display of the date or the time (e.g. the date is updated at midnight) use the clocks templates.
bouncing_text.svg: Text too large to be displayed will ‘bounce’ left to right or top to bottom.
fit_text.svg: Text size will adapt to the area available.
switch.svg: Display different media depending on the item content. (A global variable can also be used with this template.)

How to use the format helpers

The format helpers are a set of file which can be added as a multimedia layer in the news.svg and news_crawler.svg file to simplify the construction of the layout.

To use the bouncing text or the fit text helper do as follow:

Drag and drop it on your document like any multimedia file.
Open it.
Change the Text to [SPX][title] or [SPX][description] to display respectively the title or the description of your news.
Press Apply or Save to see the result.

Composing a live news document in 5 steps

Copy the news template SVG file from My Templates/News into your project
- Open in the browsing panel a new exploring tab of your current project.
- Open an additional exploring tab located in My Templates/News.
- Drag and drop the template file you have chosen from the news tab into your current project tab.
Open the newly created SVG file. Select your news source using the RSS Feed Source entry. Type the URL of the RSS news to use an external news feed.
Customize the display of your news source:
- Press the editing button
- Move, resize existing text/media box in the preview panel
- Edit the text box content. The [SPX][title] and [SPX][description] will be replaced by the content of the RSS news.
- Add news text or media box using the Layer tab.
Customize the settings of your news source using the Properties tab.
- The Feed Type let you select the type of your input data.
- The Feed Update Policy let you control when the feeds should be updated.
- Additional settings can be found depending on the templates.
Save the final document.

Troubleshooting

See also Data feeds - troubleshooting section.

URIs in news templates must contain only valid URI characters (as defined by RFC 3986). Other characters must be escaped. For example, the URI "http://www.acme.corp/rss/monday|01041^^3F" should be correctly written as "http://www.acme.corp/rss/monday%7C01041%5E%5E3F".