NZ Herald Feed Reader Widget - Advanced Usage Documentation

Please note: this documentation assumes at least a basic working knowledge of Javascript, CSS and/or HTML, depending on the specifics of what you are trying to achieve.

While the source code generated by the customiser is suitable for directly copying and pasting in most cases, there are some circumstances in which this approach is not ideal; for example:

If any of the above apply to you, you may wish to consider using the advanced configuration techniques described below. If you're not sure, it is probably best to just copy and paste the generated code as-is.

Some background

The customiser system provides an easy way of customising the look of the reader widget. The color scheme, font and other styling selected by the user is reflected in the generated code, which brings together a combination of CSS styles, Javascript and HTML ready to be copy-and-pasted directly into your blog or website as one big block of code. However not all configurations are ideally suited to work well with all aspects of this approach - but there are alternative approaches available.

Advanced Mode

Activating the Advanced Mode checkbox will include markers in the generated code, delineating its three sections - the Script Loader; the CSS style block; and the HTML DIV. For a quick start:

Each of these individual sections may be adjusted according to your needs. If you are familiar with CSS, the style block may be tinkered with; if you have specialised needs you may alter the Script Loader. The HTML DIV simply serves as a target for the reader widget to occupy; when initialised, the widget will look for the element with an ID of "readerDiv" (or whatever id is given in the arguments - see below for details) and use it as a container.

Script Loader

The Script Loader block is made up of two parts. The first part consists of two empty <script> tags with "src" attributes which load the necessary Javascript source code from the NZ Herald servers - these lines should not be changed. The next part is a <script> block with three lines - the first two to create and configure the feed reader ("ReaderWidget") object and its data provider ("JsonFeeder"), and the other to tell the browser to activate the ReaderWidget once the page has finished loading.

Widget Setup

The first line of this sub-block is tailored specifically to the feed you selected in the customiser screen, for example:

var feedsource = new JsonFeeder("http://www.nzherald.co.nz/json/rss/", 
	{"feedLink":"http://www.nzherald.co.nz/", "name":"NZ Herald Up To The Minute"});

In most cases this should be left as is.

The structure of the second line is thus:

var feedreader = new ReaderWidget("<Target DIV id>", <Feed provider>, <Number of rows to display>);

The target DIV id is the id of the DIV that the ReaderWidget will search for and attempt to occupy. If you wish to target the reader to a DIV other than the default, then you may give this DIV's id here. The feed provider refers to the JsonFeeder declared as "feedsource" in the previous line - you are unlikely to need to change this. The number of rows to display may be adjusted in the customiser interface, or by altering the parameter shown here.

The third line instructs the browser to wait for the page to finish loading, and then to initialise the widget:

window.onload = function () {feedreader.run();}

It does this by creating a function which invokes the

run()
method on the feedreader, and setting this function as the event handler for the
window.onload
event, so that it will be executed after the page load.

Case Studies

If you wish to use multiple widgets in one page, you will need to create a JsonFeeder and a ReaderWidget for each one. You may wish to use the customiser to automatically generate a few of them, and then copy-and-paste the relevant lines out of the generated code for each. You will need to ensure that you create a div for each one and target them correctly, but the style block and script loader part will only be needed once.

If you wish to use an alternate means of handling the document load event, then remove the third line mentioned above and use your preferred mechanism instead.

© Copyright 2014, APN New Zealand Limited

Assembled by: (static) on red akl_a5 at 22 Sep 2014 01:47:33 Processing Time: 105ms