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 you wish to keep your CSS styles and/or javascript together in the page header, or keep your CSS styles in a separate stylesheet file
- If you wish to have more control over the way the widget is configured, the structure of the page or the naming of the div the widget uses
- You already have events triggering via the document onLoad event
- You wish to make CSS adjustments beyond what is offered by the interface
- You wish to embed multiple reader widgets in a single page
- You would like to learn more about the functioning of the feed reader widget and discover more about its capabilities.
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:
- Add the CSS style block and the Script Loader in their entirety to the <head> element of your webpage or page template.
- Add the HTML DIV to the page at the point where you want the reader widget to appear on your page.
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.onloadevent, 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.