Scroll Box Add-on

Introduction

Use this add-on to create nice looking text scroll boxes, logo rolls and boxes with images that get replaced in regular intervals. Scrolling stops if you hover the mouse pointer over the scroll area.

This add-on uses CSS and JavaScript. It falls back to show initial content in case JavaScript is not available. All code is included, e.g. there are no external dependencies. The Scroll Box Add-on is inspired by the scrolling content script of dhtmlgoodies.com.

The twiki.org redesign of December 2010 added a logo roll to the homepage. This add-on was created based on that work.

Usage

There are two options to create scroll boxes:

• Using INCLUDE
• Using HTML & CSS

Using INCLUDE

Create scroll boxes in TWiki pages by including two named sections defined in the ScrollBoxAddOn topic, called "scroll_box_engine" and "scroll_box", respectively. Example:

%INCLUDE{ "%SYSTEMWEB%.ScrollBoxAddOn" section="scroll_box_engine" }%
%INCLUDE{ "%SYSTEMWEB%.ScrollBoxAddOn" section="scroll_box"
  name="must_be_unique"
  title="This is a test"
  content="TWiki keeps getting more and more useful."
  delay="100"
  vstep="1"
  width="400"
  height="30"
}%

The "scroll_box_engine" section defines the CSS and JavaScript. It must be included once per page.

The "scroll_box" section generates a scroll box. It can be included more than once to create multiple scroll boxes. This section expects the following include parameters:

• name: Name of the box. Must be unique per page. Use only alphanumeric characters and underscore!
• title: Title of the box.
• content: Content of the box. Can be of any form, such as TML, HTML, images. Make sure to escape double quotes with a backslash, such as <br clear=\"all\">.
• delay: Delay between scrolls, in milliseconds.
• vstep: Vertical step taken per scroll, in pixels.
• width: Box width, in pixels.
• height: Box height of scrollable area, in pixels.

Using HTML & CSS

You can define your own style and create your own scroll box. Example:

%INCLUDE{ "%SYSTEMWEB%.ScrollBoxAddOn" section="scroll_box_engine" }% <!-- once per page -->
<div id="myOwnBoxContainer">
 <div id="myOwnBoxContent">
  (put content here)
 </div><!-- id="myOwnBoxContent" -->
</div><!-- id="myOwnBoxContainer" -->
<script type="text/javascript">
 initScrollBox( 'myOwnBoxContainer', 100, 1, 200, 400 );
</script>

The first parameter of initScrollBox() is the ID of the div that contains the scroll box. The numeric parameters are delay, vstep, width and height, respectively.

Named sections

This section defines the "scroll_box_engine" and the "scroll_box" section. View the raw text of this topic to look under the hood.

Examples

Text scroll demo

This example shows a box that scrolls text in one pixel increments.

How it works: We place the text in a scrollable canvas that is 300 pixels wide. The text is justified left and right as specified in the style sheet of the scroll box content. We tell the scroll box to show a container 300 pixels wide and 150 pixels high. That is, we only see part of the canvas. We move the canvas up 1 pixel at a time and to wait 100 milliseconds between steps, e.g. we get the impression of smoothly scrolling text in the container.

%INCLUDE{
  "%SYSTEMWEB%.ScrollBoxAddOn"
  section="scroll_box"
  name="textExample"
  title="Lorem ipsum"
  content="<br /><!-- make space on top -->
    Lorem ipsum dolor sit amet, consectetur
    ...
    deserunt mollit anim id est laborum."
  delay="100"
  vstep="1"
  width="300"
  height="150"
}%

Logo roll demo

This example shows a logo roll that changes every 2 seconds.

How it works: We have a set of logos that all have the same height of 30 pixels:

We place the logos in a scrollable canvas that is 300 pixels wide. The logos wrap around; they are justified left and right as specified in the style sheet of the scroll box content. We tell the scroll box to step by 30 pixels at a time, e.g. we will cycle through the logos row by row because the icons are 30 pixels high.

Rendered logo roll: TWiki Users Around the Globe

Raw text: %INCLUDE{ "%SYSTEMWEB%.ScrollBoxAddOn" section="scroll_box" name="logoExample" title="TWiki Users Around the Globe" content="<img src='%ATTACHURLPATH%/com-cisco.png' alt='cisco' /> <img src='%ATTACHURLPATH%/com-hp.png' alt='hp' /> ... <img src='%ATTACHURLPATH%/com-cmu.png' alt='cmu' />" delay="2000" vstep="30" width="300" height="30" }%

Image swap demo

This example shows a box containing an image that get replaced every 3 seconds.

How it works: The images are 300 pixels wide and 225 pixels high. We place the images in a scrollable canvas that is 300 pixels wide, e.g. one image fits on each "line". In other words, the images are stacked on top of each other. We tell the scroll box to step by 225 pixels at a time, e.g. the same as the image height. This results in cycling through the images one by one.

Rendered image box: Beverly Hills

Raw text: %INCLUDE{ "%SYSTEMWEB%.ScrollBoxAddOn" section="scroll_box" name="imageExample" title="Beverly Hills" content="<img src='%ATTACHURLPATH%/Dsc08566.jpg' alt='Beverly Hills' /> <img src='%ATTACHURLPATH%/Dsc08581.jpg' alt='Rodeo Drive' /> <img src='%ATTACHURLPATH%/Dsc08580.jpg' alt='Expensive cars' /> <img src='%ATTACHURLPATH%/Dsc08567.jpg' alt='Beverly Hills City Hall' />" delay="3000" vstep="225" width="300" height="225" }%

Installation Instructions

Note: You do not need to install anything on the browser to use this add-on. The following instructions are for the administrator who installs the add-on on the server where TWiki is running.

• Download the ZIP file from the Add-on Home (see below)
• Unzip ScrollBoxAddOn.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/ScrollBoxAddOn.txt	Add-on topic
  pub/TWiki/ScrollBoxAddOn/*	Images used by the examples

• Test if the installation was successful:
  • See if above examples work

Add-On Info

• Set SHORTDESCRIPTION = Add scroll boxes and image rotation to TWiki pages

Add-on Author:	TWiki:Main.PeterThoeny
Copyright:	© 2010, TWiki:Main.PeterThoeny
License:	GPL (GNU General Public License)
Add-on Version:	2010-12-23 (V1.1)
Change History:
2010-12-23:	TWikibug:Item6623: Doc improvements; changing function initScrollContent to initScrollBox
2010-12-22:	TWikibug:Item6623: Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1 (TWiki 4.0)
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	5.005
Add-on Home:	http://TWiki.org/cgi-bin/view/Plugins/ScrollBoxAddOn
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/ScrollBoxAddOnDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/ScrollBoxAddOnAppraisal

Related Topic: TWikiAddOns