Tetra DHTML/JavaScript Scroller

with AJAX background updating and RSS feed integration using CaRP

© 2005 Gecko Tribe, LLC

Tetra Homepage


Installation

To install Tetra, upload tetra-js.php, tetra-make-xml.php and tetra-setup.php to any location inside your website directory. If you are going to use Tetra with CaRP to scroll RSS newsfeeds, you will also need to upload tetra-carp.php to your webserver. We recommend putting it inside the CaRP folder (ie. in the same directory as carp.php). That will make it easy to determine the path to tetra-carp.php, since the path will be the same as the path to CaRP.

Creating Scrollers

To create a scroller, load the copy of tetra-setup.php that you uploaded to your webserver in your web browser. For example, if your website is http://www.example.com/, your web directory is /home/example/public_html/, and you uploaded tetra-setup.php to the directory /home/example/public_html/tetra/, you would enter the URL "http://www.example.com/tetra/tetra-setup.php" in your web browser's address bar.

You will see a form with default values already entered. Change any of those values that you wish to change, ensuring that all fields and sections that are not marked "optional" are completed (they are by default), and click any of the three "Create Tetra Code" buttons that are found on the page.

Depending on the settings you enter, four or five bits of HTML, JavaScript, CSS, and perhaps PHP code will be displayed. Each will have instructions telling what to do with it. Follow those instructions to copy that code into the webpage where you want the scroller displayed, or into new files as noted, upload those files to your webserver, and your scroller will be completed.

Recommendation

Because some older web browsers do not support the "AJAX" technology that enables Tetra to update the contents of the scroller dynamically, we recommend including static data in the scroller, either by integrating with CaRP, or by entering static data in the bottom section of tetra-setup.php. This will ensure that all browsers will display some content, and most will scroll it, even if they don't receive new data from time to time.

Creating static XML files for scroller data

Tetra can read data from specially formatted XML files to update the contents of your scrollers from time to time. The data can all be stored in one XML file, or split between different files, each of which points to the next one. To create the XML files, load the copy of tetra-make-xml.php that you uploaded to your webserver in your web browser . For example, if your website is http://www.example.com/, your web directory is /home/example/public_html/, and you uploaded tetra-make-xml.php to the directory /home/example/public_html/tetra/, you would enter the URL "http://www.example.com/tetra/tetra-make-xml.php" in your web browser's address bar.

You will see a form with fields for a URL and scroller data. If you wish to scroll the data you will be entering in this file for a while, and then dynamically update the scroller with data from another file, enter the URL where the other file will be found in the URL field. Note that due to JavaScript security restrictions, all of the files must be hosted on the same server as the webpage where the scroller appears. For example, if the scroller is to be displayed on the page http://www.example.com/news/world.html, all of the XML data files must be hosted on www.example.com.

In the data fields, enter the HTML code and text that you want displayed in the scroller. The form will initially have fields for three scroller segments. If you wish to enter more data, complete those three segments first and click the "Generate XML" button. New fields will be added to the form ensuring that you always have three empty fields available.

When you have finished entering data, click the "Generate XML" button one last time, copy the contents of the field at the top of the resulting page, paste them into an empty file in a plain-text text editor such as Notepad, and save the file, giving it a name ending in ".xml". Upload this file to your webserver in the location pointed to by your Tetra settings or another Tetra XML file.

Technical Reference

XML File Format

Tetra's XML file format is extremely simple, and designed to minimize bandwidth usage. It has only three elements, none of which have any attributes. The root element is named "n". The file must begin (after the XML prologue line) and end with <n> and </n> tags.

The most important element is the "i" element (for "item"). Each "i" element contains the data for one scroller section. There must not be line breaks in the "i" element--ie. the data must begin on the same line as the <i> tag. Note that you may of course enter HTML <br> tags and other tags that will result in line breaks when the content is displayed. Any HTML in the "i" element must be escaped. In other words, "&" must be converted to "&amp;", "<" to "&lt;", and ">" to "&gt;". All of these requirements will be met automatically if you use tetra-make-xml.php to create your XML files.

The other element is the "url" element. It is optional. If present, it contains the URL of the next XML file to be loaded after the current file. The must not be line breaks in the URL element--ie. the URL must begin on the same line as the <url;> tag.

Arguments to TetraMakeConf

The JavaScript function TetraMakeConf takes twelve arguements. The proper values will be generated automatically by tetra-setup.php, but if you wish to edit the JavaScript by hand after creating a scroller, refer to this reference to determine the meaning of each.
  1. name: The name of the scroller. This must be the same as the name of the JavaScript variable that the scroller's configuration is saved in. This same name must also be used in the CSS IDs and class names for the scroller.
  2. url: The URL of the file or script from which to load data into the scroller.
  3. allowUrlChange: This determines whether the XML file or script can indicate a new URL to be used the next time the scroller is updated. Enter 0 to disallow changing of the URL (ie., continue loading the same XML file or script each time), and 1 to allow the URL to be changed dynamically.
  4. origItemCount: The number of scroller items statically coded into the webpage. When the "static" data is actually dynamically generated, as it is when integrating with CaRP, the script that generates the data must set this variable unless it is known in advance that it will always be the same.
  5. boxSize: The height or width in pixels of the entire scroller. If scrolling horizontally, enter the width, and if vertically, the height.
  6. itemSize: The height or width in pixels of each item in the scroller. Each item may fill the entire scroller, or the scroller may hold multiple items at once. It may even hold fractional numbers of items, for example, two and a half at a time.
  7. gap: The amount of space in pixels to leave between items as they scroll.
  8. direction: The direction to scroll the items. All letters in this value must be uppercase. Enter "R2L" for "right to left", "L2R" for "left to right", "B2T" for "bottom to top", or "T2B" for "top to bottom".
  9. itemDelay: The number of seconds to pause on each item.
  10. stepDelay: The amount of time, in thousandths of a second, to pause between each scrolling step. Note that differences in browsers and computers will determine how long it takes to complete each scrolling step--this setting only controls that amount of time between steps.
  11. stepSize: The number of pixels to move the items in each scrolling step. This must be a positive number, regardless of the direction of scrolling. The script will make the number negative if necessary based on the "direction" setting.
  12. refreshDelay: The number of seconds to wait after loading XML data before reloading or loading from the next URL. This should usually be set to something like 300 (five minutes) or higher, unless you have constantly updating data that your want delivered as soon as possible to your site's visitors.