Scrolling Divs Documentation

This portion of the documentation contains basic instructions for setting up dyn-web's Scrolling Divs JavaScript. It covers how to set up the divs, styles, scroll controls and/or scrollbar, and how to initialize the code. Part Two of the documentation provides information about more advanced features of the code as well as accessibility features.

The best starting point when implementing the code is to choose an example document from the download file that most closely resembles your desired implementation. Follow the pattern set there and read below for details and clarification.

Instructions for Setting Up Scrolling Divs JavaScript

The following list outlines the steps for implementing the code. Details on each step are available below.

1. Script Tag

Place a script tag for the external JavaScript file in the head of your document:

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

2. Scroll Area Divs

Scroll areas are set up using nested div tags: a container and content. Assign each a unique id. A typical scroll area is set up as follows:

<div id="wn">
    <div id="lyr1">
    [Content to scroll goes here]
    </div>
</div>

Part Two of the documentation provides information for setting up content for horizontal scrolling. Mutliple scroll areas can be set up by including additional sets of nested divs, each with unique ids. This also is discussed in Part Two of the documentation.

The code supports the ability to swap content in the scroll area by including additional hidden content divs within the container div. An example demonstrates this feature. More information is provided in Part Two of the documentation. ^

3. Div Style Specifications

The container div (wn in this example) can be positioned absolute or relative. Width, height, and overflow hidden are required specifications. Here are some typical style specifications for the container div:

div#wn { 
    position:relative;
    width:280px; height:200px; 
    overflow:hidden;
}

The scrolling content div is positioned absolute in the code. The code calculates the dimensions of the content div. Exercise care if you apply styles directly to this element (lyr1 in the HTML shown above) or to elements contained within it as some settings (for example, height or float) may interfere with the code's ability to obtain dimensions. ^

4. Scroll Controls and/or Scrollbar

The code includes a buildScrollControls function which inserts the components of the scroll controls for you. Include a div where you would like the controls in your markup and assign it a unique id.

For example, to provide left/right arrows for horizontal mouseover scrolling, include the following where you want them in your document:

<div id="scrollLinks"></div>

Include the id as the first argument to the buildScrollControls function, and 'h' as the second argument, to instruct the code that the scroll direction is horizontal:

wndo.buildScrollControls('scrollLinks', 'h');

The call to buildScrollControls is placed in the initialization routine as shown below.

Here is an example of how you might specify styles for left/right images for horizontal scrolling:

div#scrollLinks {
    position:relative;
    width:180px;
}
div#scrollLinks .left {
    background-image:url('/images/left.gif');
    background-repeat:no-repeat;
    width:11px; height:11px; /* width and height of your image */
    position:absolute; left:30px;
}
div#scrollLinks .right {
    background-image:url('/images/right.gif');
    background-repeat:no-repeat;
    width:11px; height:11px; /* width and height of your image */
    position:absolute; right:30px;
}

Notice that the images are placed in the background in the style sheet rather than in the markup. You can use images of your choice and size and position them to suit your layout. ^

buildScrollControls Arguments

The buildScrollControls function can just as easily be used to set up controls for vertical scrolling, mousedown scrolling, and a scrollbar. Its arguments are:

/** buildScrollControls arguments:
  *   id of div to contain scroll control components
  *   scroll axis ('h' for horizontal, 'v' for vertical)
  *   event type for scroll images or links: 'mouseover' or 'mousedown'
  *   include track and dragBar? true or false
  */

If you want to include a scrollbar (track and drag bar) in your document in the following div:

<div id="scrollbar"></div>

Include the following call to buildScrollControls:

// arguments: id, axis ('v' or 'h'), event type for arrows, 
// include track and dragBar? true or false
wndo.buildScrollControls('scrollbar', 'v', 'mouseover', true);

See below for the placement of this function call in the initialization routine.

An example in the download file demonstrates with the following style specifications for a scrollbar:

div#scrollbar {
    position:absolute;
    width:11px; height:170px;
}
div#scrollbar .up {
    background-image:url('/images/btn-up.gif');
    background-repeat: no-repeat;
    width:11px; height:11px; /* width and height of your image */
    position:absolute; top:0;
}
div#scrollbar .down {
    background-image:url('/images/btn-dn.gif');
    background-repeat: no-repeat;
    width:11px; height:11px;
    position:absolute; bottom:0;
}
div#scrollbar .track {
    position:absolute; /* track must be positioned */
    left:0; top:12px; /* top based on height of image */
    width:11px; 
    height:146px;
    background-color:#336; /* can use background-image if you like */
}
div#scrollbar .dragBar {
    position:absolute; /* dragBar must be positioned */
    background-color:#ceced6; /* can use background-image if you like */
    width:9px; 
    height:20px; 
    top:1px; left:1px; /* optional, small gap between track and dragBar */
}

Generally, you will want to adjust the height of the scrollbar and track according to the height of your scroll area and set the position of the track based on the size of your scroll control images.

Override dragBar Autosize. Examples give the dragBar a background color in the style sheet. By default, the dragBar will be resized by the code according to the relative dimensions of the content and container. However, you can use an image and specify a fixed size for the dragBar if you like. Then you would add !important to the style specification for height or width of the dragBar to override resize. An example vertical scrollbar with dragBar height fixed:

div#scrollbar .dragBar {
    position:absolute; 
    background-image: url('/images/bar.png');
    background-repeat: no-repeat;
    width:9px; 
    height:20px !important; /* include !important to override resize */
}

Auto-hide. If you are setting up scroll areas in situations where scrolling may not always be required, by default the code will hide the controls when they are not needed. You can override this by using !important in css for visibility of controls div:

div#scrollbar {
    position:absolute;
    width:11px; height:170px;
    visibility:visible !important; /* override auto-hide */
}

^

Initializing the Code

The code checks whether the browser supports the necessary features and then assigns a function to be called onload. A link element for the style sheet is dynamically generated[1] so that the contents will be accessible for those without the necessary JavaScript support. You can link in the style sheet containing the scroll specifications in the usual manner if you prefer.

if ( dw_scrollObj.isSupported() ) {
    dw_Util.writeStyleSheet('css/scroll.css');
    dw_Event.add( window, 'load', init_dw_Scroll);
}

The init_dw_Scroll function is called onload. The following initializes a scroll area with a vertical scrollbar:

function init_dw_Scroll() {
    // Initialize scroll area
    // arguments: id of scroll area div, id of content div
    var wndo = new dw_scrollObj('wn', 'lyr1');
    
    // Initialize scrollbar and up/down or left/right controls
    // args: id, axis ('v' or 'h'), event type for arrows, 
    // include track and dragBar? true or false
    wndo.buildScrollControls('scrollbar', 'v', 'mouseover', true);
}

The function called onload creates instances of the scroll and scrollbar objects, builds the divs, and sets up event handling for the controls and scrollbar. This function is generally included in a script segment in the head of example documents, but can be placed in an external file for use throughout your site if you prefer.

Back to top or on to Part Two of the documentation.


  1. The function used here, dw_Util.writeStyleSheet uses document.write. Another function is available (dw_Util.addLinkCSS) which uses DOM methods to generate the link element for the style sheet. ^