Documentation

Page Topics:

This page provides documentation for dyn-web's Scrolling Div's Code. 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.

The download file contains basic example documents that are designed to make it easy for you to locate the code components required.

Instructions for Setting Up Scrolling Div Code

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

  1. Include script tags pointing to the external JavaScript files.
  2. Place nested div's in the document where you wish the scroll area(s) to appear.
  3. Adjust style specifications for the div's.
  4. Add scroll controls and/or scrollbar elements.
  5. Initialize the code.

Script Tags

Place script tags for the external JavaScript files in the head of your document:

<script src="js/dw_event.js" type="text/javascript"></script>
<script src="js/dw_scroll.js" type="text/javascript"></script>
<script src="js/dw_scrollbar.js" type="text/javascript"></script>
<script src="js/scroll_controls.js" type="text/javascript"></script>

Not all implementations require all four files. If you are working from an example document in the download file just use the ones included there. ^

Scroll Area Div's

Scroll areas are set up using nested div tags: a container and content. Each needs to be assigned a unique ID.

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

Part Two of the documentation includes further information needed for setting up the content for horizontal scrolling.

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. Further information is provided to licensed users of the code.

Mutliple scroll areas can be set up by including additional sets of nested divs, each with unique ID's. See below for more information on setting up multiple scroll areas. ^

Div Style Specifications

The container div (wn in this case) can be positioned absolute or relative. Width, height and overflow hidden are required specifications. Adjust width and height to suit.

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. ^

Scroll Controls

You can set up scroll links for mouseover, mousedown, or onclick scrolling in addition to scrollbars. For example, linked images for mouseover scrolling can be set up as follows: 

<div id="scrollLinks">
<a class="mouseover_up" href=""><img src="images/btn-up.gif" alt="" /></a>
<a class="mouseover_down" href=""><img src="images/btn-dn.gif" alt="" /></a>
</div>

Event handling is set up by the code so that there is no need for event handler attributes in your HTML. As shown above, classes are attached to the scroll controls' linked images. Classes such as mouseover_down or click_down_by_100 instruct the code as to what event handlers should be attached to those links.

Notice that the scroll control links demonstrated above are contained in a div with an ID. You can add an additional class to links to apply margins, or place the individual linked images in table cells or divs or any other elements that you like, applying classes and styles to suit your design, as long as a container element somewhere in the hierarchy has an ID that you can pass to the code:

wndo.setUpScrollControls('scrollLinks');

See below for the placement of this statement within the initialization routines. ^

Scrollbar

A scrollbar consists of the following elements: 

  <div id="track">
    <div id="dragBar"></div>
  </div>

Generally, the dragBar consists of a div with a background color specified in the style sheet. Unless you specify otherwise when initializing the scrollbar (see below), the dragBar will be resized by the code according to the relative dimensions of the content and container. However you can use an image of fixed size for the dragBar if you like. More information is provided to licensed users of the code.

Often when including both scroll controls and scrollbar you will put them in one containing element and control their position in the style sheet: 

<div id="scrollbar">
 <div id="up"> (scroll link here) </div>
  <div id="track">
    <div id="dragBar"></div>
  </div>
  <div id="down"> (scroll link here) </div>
</div>

Example style specifications for the above scrollbar elements: 

div#scrollbar { 
  position:relative;
  width:11px; height:200px; 
  font-size:1px;  /* for image vertical alignment issue */
  }
div#track { 
  position:absolute; left:0; top:12px;
  width:11px; height:176px;
  background: #336;
  }
div#dragBar {
  position:absolute; left:1px; top:1px;
  width:9px; height:20px;
  background-color:#ceced6;
  }  
div#up { position:absolute; left:0; top:0; }  
div#down { position:absolute; left:0; bottom:0; }

/* for safari, to prevent selection problem  */
div#scrollbar, div#track, div#dragBar, div#up, div#down {
    -moz-user-select: none;
    -khtml-user-select: none;
}

/* so no gap or misplacement due to image vertical alignment [1]*/
div#scrollbar img {
    display:block; 
    }

If you are using a table-based layout, the components could be placed in table cells, but the track and dragBar do need to be positioned. For example, the track could be a relative positioned div inside a table cell, the dragBar an absolute positioned div inside the track.

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.

Both horizontal and vertical scrollbars on a single scroll area are supported.

The scroll controls and scrollbar are not initially displayed (display:none in the style sheet) so that users with incapable browsers will not see them. At the beginning of page load, the code determines the browser's capabilities and appropriately handles display of controls and content. ^

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[2] so that the contents will be fully visible for those without the necessary JavaScript support.

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

Of course, you can choose to link in the style sheet containing the scroll specifications in the usual manner if you prefer. See more information in Part Two of the documentation.

The init_dw_Scroll function is called onload. The following demonstrates a typical setup although not every implementation will be exactly the same (view source of example documents in the download for specifics):

function init_dw_Scroll() {
    // Initialize scroll area
    // arguments: id of outer div, id of content div
    var wndo = new dw_scrollObj('wn', 'lyr1');
    
    // Initialize scrollbar
    // arguments: id of dragbar, id of track, 
    // axis ('v' for vertical scrolling, 'h' for horizontal)
    // horizontal offset of dragbar in track, vertical offset
    // size dragBar according to amount of content? (boolean)
    wndo.setUpScrollbar('dragBar', 'track', 'v', 1, 1, true);
    
    // Initialize scroll links
    // id of element within which to locate scroll controls
    wndo.setUpScrollControls('scrollbar');
}

The function called onload instantiates the scroll and scrollbar objects and sets up event handling for the controls and scrollbar. This 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.

Autohide. If you are setting up scroll areas in situations where scrolling may not always be required, it is possible to instruct the code to hide the controls when they are not needed. An example demonstrates. More information is provided to licensed users of the code. ^

Setting up Multiple Scroll Areas

The code easily supports multiple scrolling content areas in a document, as the examples demonstrate. Set up nested div's as described above for each scroll area, assigning a unique ID to each. Use these ID's for the style specifications for each scroll area. The elements containing the scroll controls and/or scrollbars also need unique ID's and style specifications set up as described above.

An example initializing the code for two vertical scroll areas is accomplished as follows:

function init_dw_Scroll() {
    var wndo1 = new dw_scrollObj('wn1', 'lyr1');
    var wndo2 = new dw_scrollObj('wn2', 'lyr2');

    wndo1.setUpScrollControls('scrollLinks1');
    wndo2.setUpScrollControls('scrollLinks2');
    
    wndo1.setUpScrollbar('dragBar1', 'track1', 'v', 1, 1);
    wndo2.setUpScrollbar('dragBar2', 'track2', 'v', 1, 1);
}

As the vertical example demonstrates with four scroll areas, a document can easily accommodate several.

An example is included in the download file provided to licensed users.

Accessibility Features of Scrolling Div's Code

The style sheet can be dynamically written or generated once it is determined that the browser is capable of supporting the code so content will be available when JavaScript is disabled or the user's browser is otherwise incapable of supporting the code.[3] See more information in Part Two of the documentation about enabling printing for your viewers.

Device independent scrolling is provided by the code. You can include glide onclick scroll controls so that when a user focuses on a scroll link and hits enter scrolling occurs.

Known Issues

Form Elements. When users tab among elements, such as form elements or links inside the scroll area, this can cause the scrolling content div to jump which will throw off the scroll calculations. There is no known solution for this problem. A page reload is required to restore the scroll area to functionality. For this reason, it is highly recommended that you do not display forms inside scroll areas.

Named Anchors. A similar related problem occurs when you attempt to point to named anchors inside the scrolling div's. The code provides a substitute: glide onclick scrolling to a specified ID. An example demonstrates.

Flash and DHTML Layers. If you wish to use Flash in conjunction with DHTML layers such as the scrolling components, you need to specify wmode transparent for the Flash object. See an Adobe Technote on the subject for more information. This is evidently a read only property and cannot be set dynamically. Also, there may be some browsers that do not support the wmode property. This is a limitation of Flash and not an issue that we would be able to assist you with.

Large Images. If your scrolling content areas containing large images and if you don't include width and height attributes in those images, the initial calculations for the content div may not accurately reflect the size of the content. This may be due to some browsers calling onload before all images have completed loading or if you are using some version of DOM ready to initialize the code rather than onload. The easiest solution, although not always practical, is to specify width and height attributes for images to be included in the scrolling content areas.

You may be disappointed with the performance when scroll areas contain large images. The motion may be less than smooth and images may tend to "break up" during scrolling movement. This problem tends to be more pronounced with mouseover scrolling and can often be minimized with relatively fast glide onclick scrolling.

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

  1. When using a strict doctype, triggering standards mode, you either need to display images block (the preferred approach) or set the font-size one pixel or the alignment will be off in some browsers due to the vertical alignment of images. ^
  2. 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. ^
  3. Although the content in scroll areas would generally be available for browsers not supporting JavaScript, that is not the case for the online examples, which are retrieved using Ajax and other JavaScript techniques. ^