News Feed Web Developer's Guide

An appetizer

Here's at a quick glance at what EasyByte's news feed scroll renderer can do for you. All these renderers were obtained using the same base code, customized using a specific configuration file you can access by clicking on the "See configuration" link.

See configuration See configuration See configuration See configuration

See configuration
See configuration
See configuration

... And there is more to it! Here's some nice examples whose configuration options will be explained in detail: [example 1], [example 2].

Installing the news feed

Here is how you add the scroll-based news feed renderer to your page.

1) Download newsfeed-scroll.zip. Unzip the downloaded archive in the same directory where your web page is located on your web server. A directory called newsfeed-scroll is created, containing the needed files.

2) Add style information, the main scrolling script and the headlines file to the <head> section of your web page:

<link rel="stylesheet" href="newsfeed-scroll/style-scroll-up.css" type="text/css" />
<script language="JavaScript" src="newsfeed-scroll/newsfeed-scroll.js" type="text/javascript"></script>
<script language="JavaScript" src="http://www.erfilter.com/international.js" type="text/javascript"></script>

3) Just place these two lines in your web page where you would like the news feed to be displayed. The first line configures the behaviour of the newsfeed, while the second one actually creates the news feed.

<script language="JavaScript" src="newsfeed-scroll/config-scroll-up.js" type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">createNewsfeedScroll()</script>

This very page you are now reading follows this guideline, so you can view its source to see how it has been done.

News feed configuration

The behaviour of the news feed renderer is controlled by 17 parameters. These parameters can be found in newsfeed-scroll.js. While you can customize them there, it is recommended that you create a configuration file which defines these parameters and use this file as described in section Installing the news feed, 3). This way, you will be able to use multiple news feeds in your page, with different configuration settings. Another benefit is that the configuration you define for your particular needs is kept separate from EasyByte's script, which is a plus if you want to upgrade to a newer version.

How much information is displayed

An article consists of a link to the headline, a link to the author or source, an access link for sites that require subscription, and the time the article has been harvested. Except for the headline, the other components can be configured to be displayed or not.

The news feed's job is to display groups of articles. How many articles are in group is user configurable. It is also possible to control whether or not the article will open in a new window when clicked on.

var nArticlesInGroup; Controlls how many articles are displayed at once, grouped together. Its values can be from 1 upto any reasonable number of articles that confortably fit on your page at any given moment.

var displaySource; If set to true, a link to the source of the article (for example CNN or BBC) will be displayed after the headline (the title of the article). If set to false the source of the article will not be displayed.

var displayTime; If set to true, the time when the news was harvested is also displayed. If set to false no time information is displayed.

var openLinkInNewWindow; If set to true, when the user clicks on a link within the news feed, that link will open in a new window. If set to false, the link will open in the same window.

Positioning and dimensions

Here are the numeric variables which controll the positioning and dimensions of the news feed.

var containerTop;
var containerLeft;
var newsfeedWidth;
var newsfeedHeight;

You place the news feed in a container, be it a table cell, a frame or the main page itself. Variables containerTop and containerLeft specify where, relatively to the top and the left of your container, the newsfeed will be placed. Variables newsfeedWidth and newsfeedHeight control the width and respectively the height of the news feed. You will want to ensure that the number of articles you have chosen fit nicely in the specified space.

The next picture shows how the news feed gets rendered in a table cell.

The colors

The colors of the news feed's items is defined in a stylesheet (css file).

The style classes that can be used are:

A.headline {}
A.source {}
A.access {}
SPAN.time {}
DIV.container{}
DIV.group{}

Here's what these style definitions correspond to:

To avoid conflicts and to allow for multiple news feeds in a page with different color sets, to each of these class names a prefix may be added. For example, we may have two stylesheets, one defining A-headline, A-source etc. while the other defines B-headline, B-source etc.

To select which set of formatting classes is to be used for a particular news feed, the configuration variable stylePrefix is used, for example:

// var stylePrefix = "";
var stylePrefix = "A-";

Scrolling modes

There are three scrolling modes:

Choosing the scroll mode is done by setting the variable scrollType. Its possible values are:

var scrollType; Can be one of: NO_SCROLL, SCROLL_UP, SCROLL_LEFT

One has a finer grained control over what happens with the previous group when the current group of articles makes its entering by setting the boolean variable:

var continousScroll; If set to false, the old group is erased. If set to true, the old group is scrolled until it dissapears.

The disscution here suggests that there can be configured a type of news feed renderer not presented in the Appetizer. Such a news feed can be seen here.

Timing

You can control the speed of the scroll and the pause between article groups with the numeric variables: var scrollTime; var pauseLength; The values are expressed in milliseconds. The variable scrollTime represents the time taken for a group to reach its final position. After than, the variable pauseLength controlls how much it's waited before the next article group begins its scroll.

Separators

A separator string representing a fragment of HTML code that gets written between the elements of an article. Below is a picture describing the elements of an article and the positioning of the separators. A separator gets written only if the element is precedes needs to be written (for example, the sourceSeparator is written only if displaySource is set to true). As an exception, the headlineSeparator does not get written for the first article in a group.

For the news feed which scrolls up, the set of separators is as simple as:

var headlineSeparator="<br><br><br>";
var sourceSeparator="<br>";
var accessSeparator=" ";
var timeSeparator="<br>";

However, one must not limit himself to line breaks and spaces: any valid HTML fragment can be used. For example, the configuration below gives the result that can be seen here.

var headlineSeparator="<br><hr><br>";
var sourceSeparator="<br><img src="stars.png">&nbsp;";
var accessSeparator=" ";
var timeSeparator="[not displayed]";

News feeds with different subjects

It is possible to have more than one news feed on one page, each having its own subject area. For example, one might want to display in the same page a news feed on Linux and another one on Java. Here is how it's done.