Caution

This script is no longer maintained and is beginning to lose compatibility with newer browsers.

Should you wish to adapt this script for further use, the source code has been released under the GNU General Public License v3.0 and may be modified and redistributed under the terms of this license.

Instructions

Back Forward

The instructions here will guide you through the process of installing a JavaScript Marquee on your home page. This is a "cut'n'paste" version of the marquee and I would suggest that you follow all of the steps in adding it to your page before making any modifications to the settings and/or messages. This will make success considerably more likely and will also make detecting errors much easier.

Things to bear in mind:

  • This Marquee is intended to be fail-safe which means that if it fails it should not leave anything on your page to disrupt navigation of your site. Of course this will not always be the case, there are always other contingencies. Welcome to the internet.
  • Consequently, you should not use this marquee to display essential information / navigation links as failure is always a possibility and you cannot rely on every visitor having a JavaScript enabled browser.
  • Information in the marquee messages will not normally be indexed by search engines.
  • As with all JavaScripts of this nature it is pretty rather than practical. Treat it as such.

I considered making this an embedded script but the size of it is rather intimidating and it would be easy to screw it up while doing normal updates on your webpage. So instead (if you don't already know) I'm going to teach you how to use external JavaScript files.

1. Creating an External JavaScript

Use 'Save Target As' to save this file into the same directory as your page:

marquee.js (12.7K)

Ensure that the name is exactly as above. Take special care to ensure the extension is .js and not .txt or .js.txt. There is an alternative version that is not white-space stripped if you'd like to see the internal workings of the marquee - marquee layout.js (Developer's layout version 14.6K). This will need to be renamed to marquee.js if you want it to run.

Now add the following (red) tag to the <head> of your page:

<head>
 <script type="text/javascript" src="marquee.js"></script>
</head>

There you go. One external JavaScript.

2. Spacer

The following image should be saved to the same directory as your page. It is used as the background for the marquee and to force correct table formatting in the marquee messages when viewed with Netscape. If the image is not found the text in the messages will be compressed into the narrowest possible column in that browser.


Right Click in the space above and select Save Picture as...
The image must be named spacer.gif

3. Positioning Your Marquee

Now you need to position the marquee itself. The following table and image will dictate the size, shape and position of your marquee. Centring the table will centre the marquee, placing it inside another table element will cause the marquee to appear inside that element, etc. The container table seems to help with correctly positioning the marquee in older browsers. You should avoid using the alignment attributes on the <td> of this table as the results can be unpredictable.

<table border="0" cellpadding="0" cellspacing="0">
<tr>
  <td><img name="mrqspacer" id="mrqspacer" src="spacer.gif" width="200" height="50" alt="" style="position:relative;"></td>
</tr>
</table>

Important: There is an issue in Netscape and Mozilla that can cause scrollbar pop-up during certain transition animations. Specifically, if the invisible part of a moving message extends beyond the right or bottom edges of the window the page will extend to accommodate it. If you need to place the marquee close to these edges then you should set the nsafe switch to true - this will evade all transitions that cause pop-up.

Important: There is another issue with Opera7 regarding the positioning of the marquee. If you have set the margins of your document using CSS it will cause the marquee to become slightly displaced when viewed in this browser. To prevent it there are two variables in the marquee's browser specific settings dispv and disph. These should be set to match the top and left margin widths respectively.

4. Scaling Your Marquee

To change the size and shape of the marquee you need to alter the width and height attributes on the mrqspacer image in the above table.

This image forms the static background for the marquee and can be changed to any image file simply by changing the src. This will only be visible if the bgcolor variable in Colour Settings is set to 'transparent'. If you use another image then name the file something other than spacer.gif and leave the spacer.gif intact.

5. Live Controls (Optional)

The following links provide visitors to your page with the opportunity to pause your marquee and flick through the messages at their leisure.

<a href="javascript: clientstep('back');" onmouseover="javascript: clientpause(true);" onmouseout="javascript: clientpause(false);">Back</a>

<a href="javascript: clientstep('forward');" onmouseover="javascript: clientpause(true);" onmouseout="javascript: clientpause(false);">Forward</a>

These are not required but if you have a lot of messages your visitors may become impatient waiting for them to come around again.

You can place the links anywhere, change them to images, anything you like, in fact, so long as the attributes are left intact.

6. Last Piece

Finally, this little smudge of code should appear just before the end of your document, before the </body> tag.

<script type="text/javascript"><!--
insertdivs();
//--></script>

This is where the elements of the marquee are invisibly created on your page.

7. Accessing the Marquee Settings

In order to access the marquee setting you should open the marquee.js file that you saved earlier. To do this start MS Notepad or your favourite text editor and open the js file. At the top of this file you will find a section marked 'Settings', here you will find all of the editable controls for the marquee. The following sections describe how to use these.

8. Filling Your Marquee

Now that all your code is in place, here's the hard part: filling in the messages.

In the top of the marquee.js file you'll see an array named msgarray. The elements of this array contain the messages that will scroll through the marquee. Each message begins and ends with a single quote _'_ and all are separated by commas. With this in mind you can replace the existing text with your messages.

var msgarray=new Array
(
 'Message One',
 'Message Two',
 'Message Three',
 'Message Four',
 'Message Five...'
);

You can have as many messages as you like but there must be at least two even if you make them identical.

Important: If you use an apostrophe in your message you will need to 'escape' it using a backslash like this: I\'m for I'm or Tony\'s for Tony's. If the JavaScript causes an error, the most likely cause will be an unescaped apostrophe in this array. You can use any HTML markup in the messages but inline styles can cause failure on the marquee in older browsers so you should use classes instead.

You should note that objects larger than the marquee will be clipped.

9. Adjusting Speed

There are six variables for controlling the speed of the marquee, three basic and three advanced:

pausetime = 2500
This is the length of time in milliseconds that the marquee will pause on each message.
msginc = 20
This is the number of increments for each full transition, thus lower = faster. The width / height of the marquee is divided by this value to determine how far messages should move during each step of animation.
interval = 50
This is the interval between animation steps in milliseconds, thus less is faster & smoother. However, on most systems values less than 40, while giving smoother animation, can cause skips on slow client systems.
ppat = new Array()
This is the pause pattern where you can list a pattern of pause times in milliseconds to be applied to the messages such as ppat = new Array(25000,0,0,0). Setting this will override the pausetime setting.
ipat = new Array()
This is the increment pattern that defines a list of increment values to be applied to each transition such as . ipat = new Array (20,1,40). This overrides the interval setting.
wraptime = true
Setting this to true will prevent resetting speed patterns allowing the two patterns defined above to complete their cycles regardless of the number of messages. If set to false then the patterns will be explicitly tied to message numbers and will reset when returning to the first message.

10. Direction Settings

There are two variables for controlling direction. The first, direction = 'up', is a global direction setting. The second, dpat = new Array(), is a pattern definition used in conjunction with certain direction settings.

The settings for direction are:

up, down, left or right
These are the basic directions and dictate the direction of motion for the transition. For instance, with contiguous transition and up direction the messages will move up where as with wipe transition the split between previous and next message will move up while the messages remain stationary.
Combo directions such as upleft or leftrightdown
Combo directions can be defined in any order and with or without spaces so long as the directions are in lower case and are spelled correctly. Combo directions allow for diagonal scrolling animation as in downright and for complex wipe transitions as in updownleftright. If a setting with opposing directions is used the transition will automatically switch to wipe or unwipe (selected randomly) regardless of the existing transition setting.
rand
This setting selects a random direction for each transition including diagonals and other combo directions. When a setting with opposing directions is chosen, such as updownleft, the transition will automatically switch to wipe or unwipe (selected randomly) regardless of the existing transition setting.
prand
As rand, but the directions are randomly selected from the direction pattern.
xrand
In this mode the directions listed in the direction pattern are blocked from random selection. In order for this to work the listed directions must be correctly formatted (all lower case and no spaces) and combo directions must be one of these: updown, upleft, upright, downleft, downright, leftright, leftrightdown, leftrightup, updownleft, updownright, updownleftright. This means that downup will not block the combo direction of up+down.
pattern
This setting instructs the marquee to use the directions listed in the direction pattern in that order for each message transition. One thing that might be confusing is the synching of these directions; the first direction in the pattern is the direction chosen for the transition between the first and second message, not the direction by which the respective message appears - that is: if the first direction in the pattern is up then the second message will appear using that direction.
dpattern
As pattern but every direction listed in the pattern is doubled so that up, left, right will become up, up, left, left, right, right. This is a useful shortcut for certain complex transition effects.
wpattern
Normally the direction pattern is reset when returning to the first message. This wrap-pattern setting instructs the marquee to repeatedly complete the direction pattern regardless of the number of messages used. This will allow you to use complex patterns using only two messages.

Direction pattern: The array dpat is used with the direction settings pattern, dpattern, wpattern, prand and xrand. This is a comma delineated list of directions and or combo directions, e.g. dpat = new Array('left','up','right','updown','leftright').

11. Transition Settings

The transition is the type of animation used to pass between messages. There are two variables for controlling transition. The first, transition = 'contig', is a global setting. The second, tpat = new Array(), is a pattern definition used in conjunction with certain transition settings.

contig
In contiguous transitions the next message appears to push out the previous. This is only available with basic and diagonal-combo direction settings. Other direction combos will cause the transition to switch to wipe or unwipe (selected randomly).
cover
The next massage moves in over the top of the previous. If the background of the next message is transparent this will cause the contents to be superimposed on the previous message. If this is not the desired effect then try coverwipe.
uncover
The previous message moves away to reveal the next message beneath it. If the background of the previous message is transparent this will cause the contents to be superimposed on the next message. If this is not the desired effect then try uncoverwipe.
wipe
The previous message remains stationary and is wiped away to reveal the next. If the background of the previous message is transparent and you are using a combo direction such as updownleftthen the contents will be superimposed on the next message during transition.
unwipe
As wipe but the next message is "wiped in" over the previous. The effect of this is essentially the opposite of wipe. The direction setting upleft will cause wipe to close on the top left corner, but with unwipe it will open out from the top left.
coverwipe
As cover but the previous message is wiped away during the animation allowing for transparent backgrounds without superimposition. This setting only works correctly with the basic directions up, down, left and right, otherwise it will act as cover.
uncoverwipe
As uncover but the next message is "wiped in" during the animation allowing for transparent backgrounds without superimposition. This setting only works correctly with the basic directions up, down, left and right, otherwise it will act as cover.
rand
This setting randomly selects the method for each transition. coverwipe and uncoverwipe are not included in the random selection.
prand
As rand, but the transitions are randomly selected from the transition pattern.
xrand
As rand, but any methods listed in the transition pattern are excluded from the random selection.
pattern
This setting instructs the marquee to use the transitions listed in the transition pattern in the given order for each message transition. One thing that might be confusing is the synching of these transitions; the first direction in the patterns is the direction chosen for the transition between the first and second message, not the direction by which the respective message appears - that is: if the first direction in the pattern is up then the second message will appear using that direction.
dpattern
As pattern but every transition method listed in the pattern is doubled so that contig, wipe, cover will become contig, contig, wipe, wipe, cover, cover. This is a useful shortcut for certain complex transition effects.
wpattern
Wrap pattern. Normally the transition pattern is reset when returning to the first message. This setting instructs the marquee to repeatedly complete the transition pattern regardless of the number of messages used. This will allow you to use complex patterns using only two messages.

Transition pattern: The array tpat = new Array() is used with the transition settings pattern, dpattern, wpattern, prand and xrand. This is a comma delineated list of transition methods, e.g. dpat = new Array('contig','contig','cover','wipe','uncover').

12. Colour Settings

There are two variables for controlling colour:

bgcolor = 'white'
This is a global control for the marquee's background colour. Valid settings are: any CSS defined colour word (white, black, cyan, yellow, etc); a hexadecimal colour value (#cccc99, #fff, #000, etc); an image URL relative to the page that the marquee appears on, such as myimage.jpg, /images/myimage.gif, ../icons/up.gif, etc. The image URL is distinguished from other setting types by the period (.). The final valid setting for bgcolor is pattern, this instructs the marquee to repeatedly apply the settings listed in cpat for each message in the given order (see below). Note that tiled images can cause the marquee to slow and skip as it re-renders the tiles while animating, it can also cause the pointer to flash the hourglass, so you should always use full sized images for backgrounds. Images are applied to the CSS style attribute of the invisible tables that contain the messages.
cpat = new Array()
This is a comma delimited list of valid bgcolor settings as described above, e.g. cpat = new Array('#cccc99','white','myimage.jpg'). It is only used when bgcolor is set to pattern. The defined pattern will be repeated over the entire message list.

13. Advanced Layout Settings

There are three advanced layout settings for the marquee:

mhalign = 'center'
This is a global setting for the horizontal positioning of the messages' contents. Valid settings are left, right, center and justify which will be applied to the align attribute of the table cells containing the messages.
mvalign = 'middle'
This is a global setting for the vertical positioning of the messages' contents. Valid settings are top, bottom, middle and baseline which will be applied to the valign attribute of the table cells containing the messages.
csspat = new Array()
This is a comma delimited list of CSS classes that will be applied to each message. The defined pattern will be repeated over the entire message list. The classes are applied to the table cells containing the messages to become TD.classname. The default class for all messages is mrqtd.

14. Browser Specific Settings

These are settings used to provide some control over browser specific quirks:

dispv = 5
This is an Opera7 specific setting. When positioning the marquee Opera disregards margin settings causing the marquee to become displaced up and to the left. If you set your margins using CSS then you will need to set dispv to match the margin or margin-top value. Default margins for Opera7 are 5px all around so if you do not use CSS margins you should leave this at 5. This setting is only applied when the marquee is viewed using Opera7.
disph = 5
This is the horizontal counterpart of dispv which should be set to match your CSS margin or margin-left.
nsafe = false
This is an optional switch for activating an automatic safety feature when the marquee is viewed in Netscape. It works by changing the transition setting of contig to wipe or unwipe (selected randomly) or by altering the direction used during cover and uncover transitions. When viewed using Netscape or Mozzila the relative position of the marquee on the web page can become an issue. If the marquee appears against the right and/or bottom edges of the page then certain transition animations can cause the scrollbars to temporarily pop-up. Specifically, any transition that causes a message to move left or down so that the invisible portion passes the left or bottom edges of the page will cause this problem, e.g. the combo of direction = 'downleft' and transition = 'uncover'. If you place your marquee in the problem areas you should set this switch to true.
mdump = false
In the event that an incompatible browser is used to view your page the normal result will be that the marquee fails-safe, meaning that nothing will happen and the marquee will remain blank. Setting mdump to true will instruct the browser to attempt to write all of the messages to the browser and then quit. This might be useful if there are essential navigation links or info in your messages. This will not work in browsers which do not support JavaScript. The messages will form a column with the first message at the top. By positioning the message writing function appropriately you can ensure that this will not upset your page layout.

15. Demos

I know the last few sections might be confusing so here are some examples:

Demo 1: Basic Directions (uncover transition)
A very simple example demonstrating the four basic directions with the uncover transition method.
Demo 2: Diagonal Directions (uncover transition)
Another Simple one.
Demo 3: Wipe Transitions
Shows wipe transition with the fifteen possible directions and combo directions.
Demo 4: Wipe vs. Unwipe Transitions
Comparing the effects of wipe and unwipe transitions.
Demo 5: Coverwipe & Uncoverwipe Transitions
Shows coverwipe and uncoverwipe transitions with transparent backgrounds with an alternative spacer image as a static background.
Demo 6: Heavy Traffic
A simple example of a complex pattern effect.

16. Last Word

That's it. If you have any problems don't hesitate to contact me.

17. Development

Specific Direction/Transition combo blocking.

Animated Live Control that would perform the defined transitions during client controlled message searching.

In-Message settings for simplicity [qv the <!--skip--> tag}.

Object oriented version of the Marquee that would allow for multiple marquees on the same page. I haven't done this yet, even to a limited degree as it has a tendency to bloat the size of the script to unacceptable levels. I might provide a limited version with fewer features that would offer the benefits without the scale.

18. Known Bugs

LATEST: v3+ - Message blinks at the end of transitions. This is a rendering problem that has cropped up with the increased complexity of the Marquee. So far it has proved difficult to define, let alone trap. It is influenced by the marquee's pause, interval, increment, direction and transition settings, and possibly by the client software, the operating system, the system speed, and perhaps even the number of other applications running while visiting the page. An unreliable fix has been applied by automatically reducing the msginc value by 0.1. This has so far prevented the blinking effect with msginc values less than 35. If you are experiencing this problem then try adjusting your msginc value slightly up or down.

To fix bugs in all previous versions upgrade to v3.

19. Latest Updates

Incremental upgrades of the last version can be made simply by replacing the external js file.

Remember to copy your messages before replacing the external js file!

September 2003 - v3.0 - Too many improvements to go into. This is a recommended upgrade from all previous versions:

  1. Replace the external js file.
  2. Optionally replace the positioning table and live controls for improved xhtml compatibility.
  3. Remove the onResize="..." and onLoad="..." attributes from the <body> tag of your page.
  4. You will need to run through all of the Settings sections above to convert your settings to the new system. Direction and Transition settings althoz, altver and alt have been superceded by the pattern system - simply define dpat as 'left','right' or 'up','down', or tpat as 'cover','uncover' to get the same effect.

August 2003 - v2.3 - Now Opera7 compatible. Animation geometry improved. Several minor bugs fixed. To upgrade from v2.1: replace the external js file.

May 2003 - v2.1 - New features: faster initialisation - the marquee will now start as soon as it has enough layout information rather than waiting for images to load. Pattern tying now active - you can now define the direction and transition for particular messages using the dpat , tpat and setting tiepat = true. This update also fixes the rendering bug that allowed messages to appear out of place until the page had finished loading images. To upgrade from v2.0:

  1. Replace the external js file remembering to copy your messages first.
  2. Remove the onLoad="..." attribute from the <BODY> tag of your page.

September 2002 - v2.0.3 (beta) - New features added: direction selection, transition selection, pattern definition and random settings on both. To upgrade from v1.2/3/4:

  1. replace the external js file;
  2. make sure you have the spacer.gif next to it;
  3. remove any CSS style sheet reference to .marquee and .message;
  4. then add the live controls to your page (optional).

June 2002 - v1.4 - The Marquee is now Netscape 6 (M5) compatible and remains compatible with Netscape 4 and both Internet Explorer 5 and 6. There is a small workaround used in formatting the marquee messages in Netscape that should be noted carefully if you intend to do anything 'interesting' with this script (it is an HTML effect rather than a JS one). To upgrade to version 1.4 you need only to replace the external JavaScript file [Remember to copy your messages first!] and make sure that the single-pixel transparent GIF file is saved alongside it. To upgrade from 1.2 you should also remove the embedded style sheet from the head of your page (or all references to the 'marquee' and 'message' classes).

May 2002 - v1.3 - Altered the method used to lay the messages upon triggering the script in order to prevent the unsightly 'page extension' error. Also incorporated the embedded style sheet into the JavaScript just to make things a little easier. To update from v1.2 just replace the external .js file [Remember to copy your messages first!] then remove the embedded style sheet from the head of your page (or all references to the 'marquee' and 'message' classes).

[ Back to Projects ]