Help Guide

jQuery List Rotator (v1.2) - Help Guide

Overview
Usage
Adding Content
Plugin Parameters
Contact Info

1. Overview:

This is a jQuery list style banner rotator featuring multiple transition effects. The scrollable list allow for easy navigation of your images. The banner rotator is also fully re-sizable and configurable through the plugin's parameters and css file.

Features:

Multiple transitions available. Also can set a different transition per image.
Able to load unlimited number of images, each with customizable text description and hyperlink.
Customizable text description transitions available.
Different types of list navigation options available. Can use mouse move, directional buttons mouse over, directional buttons click, or item click.
Item list can be aligned left or right.
Show or hide components, including play button, thumbnail images, text description, etc.
Can set to automatically play on startup with customizable timer delay. Also can set different time delay per image.
Banner screen size and list are all resizable.
Text description can be set at different location, size, text color, and background color.
Scroll bar indicator shows current list position.
Can set text description and control panel to appear on mouseover.
Image random shuffle available.

back to top

2. Usage:

Installing the rotator requires the following steps.

Including the rotator's css file.
Including the javascript files.
Specifying the html tags of the rotator within your page.
Instantiating a javascript function call with any optional parameters.

Below describes these steps in more detail.

In step 1, to include the rotator's css file list-rotator.css, simply specify the following line of code within your <head> tag:

<link rel="stylesheet" type="text/css" href="list-rotator.css"/>

In step 2, you will need to include the jquery's library file jquery-1.7.1.min.js and the rotator's file jquery.list-rotator.min.js. Both files are located within the js directory. The code below shows the include in a html page:

<script type="text/javascript" src="js/jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="js/jquery.list-rotator.min.js"></script>

note: The js files with min in its file names are the compressed production version of the file. If you intend to modify the banner rotator's source code, you will need to look at the non-min development version of the file and it is recommended that you minify the modified file afterwards.

Additionally, if you plan on using any special transition easing other than the default "" or "linear", you must include the jquery.easing.1.3.min.js file in your page.

In step 3, to specify the tags of the rotator itself, refer to the example in the index.html file. In that file, you'll see a block of tag starting and ending with:

<div class="container">
   <div class="l-rotator">
      <!-- all the tags in between, see index.html for the complete code -->
   </div>
</div>

You can use this as a template and copy and paste it onto your own page, but will have to modify it accordingly with your own image/item information. Section 3 will describe this step in detail.

Finally in step 4, you will need to instantiate a javascript function call to get the rotator initialized. The example code looks like this below:

<script type="text/javascript">
$(document).ready(
   function() {
      $(".container").wtListRotator();
   }
);
</script>

This will instantiate the rotator using the default parameters. Section 4 will describe instantiation with custom parameters.

back to top

3. Adding Content:

In order to add or change content to the rotator, you will have to specify a set of tags for each item within the rotator's html tags. The list of items is represented as a <ul> tag and each item is represented by a <li> tag.

Below is an example of what the tags would look like for an item. You will have to repeat this for as many items as needed for your rotator within the <ul> tag.

<li effect="fade" delay="5000">
    <div class="thumb">
        <img src="images/thumbs/mythumb.jpg"/>
        <p>Lorem ipsum per augue platonem gubergren at, affert signiferumque in.</p>
    </div>
    <a href="images/myimage.jpg"></a>
    <a href="http://codecanyon.net" target="_blank"></a>                        
    <div style="top:10px; left:25px; width:300px; height:0; color:#000000; background-color:#FFFFFF;">
        Lorem ipsum eos et nonumy delenit, 
        ea nam petentium suavitate, in utinam torquatos cum. 
        Tritani facilisi at pro, tation quaeque usu at, 
        kasd ullum fuisset at nam. No sed decore.
    </div>                                       
</li>

The example above shows that each item entry begins with an opening and closing <li> tag. The <li> tag contain an optional attribute named effect in which an individual effect/transition type can be assigned for the item. Refer to the transitions table for a list of available transitions.

note: you can mix different effects except for the h.slide and v.slide effect.

Also, there is another optional attribute named delay for the <li> tag. This is for assigning an individual timer delay for rotation. The delay time is in milliseconds.

Inside the <li> tag, the first tag is a <div> tag with class named thumb. This <div> tag represents the visual components of the list item. The <img> tag represents the thumbnail image and the <p> tag represents the item's caption.

Next, after the <div> tag, there is an <a> tag for specifying the banner's image. The banner's image url can be assigned through the href value.

After the first <a> tag, there is a second optional <a> tag. This is for specifying the clickable link surrounding the banner when displayed. You can also specify the target for the link here also. If you do not want a link associated with a particular banner, you can omit this tag.

Finally, the last <div> tag represents the description use for the text box when the item is selected. You can specify html tags and text within this <div> tag. If you do not want a description assigned to a particular banner, you can leave the text empty.

This <div> tag also can contains 6 css style attributes (top, left, width, height, color, and background-color). You can specify the left and top position of the text box, the width and height, and the color and background color with these attributes.

If you want the text box's height to be determined automatically, just set a value of 0. Also, color defaults to white and background color defaults to black if they are not specified.

back to top

4. Plugin Parameters:

You can change some common attributes of the rotator through the parameters of the plugin. Below is an example of the attributes being specified with corresponding values.

note: if you want to leave a parameter with its default value, you can omit that parameter in the javascript call.

<script type="text/javascript">
$(document).ready(
   function() {
      $(".container").wtListRotator({
            screen_width:600,
            screen_height:300,
            item_width:250,
            item_height:75,
            item_display:4,
            list_align:"left",
            scroll_type:"mouse_move",
            auto_start:true,
            delay:5000,
            transition:"fade",
            transition_speed:800,
            easing:"",
            auto_center:true,
            display_playbutton:true,
            display_number:true,
            display_timer:true,
            display_arrow:true,
            display_thumbs:true,
            display_scrollbar:true,            
            mouseover_select:false,
            pause_mouseover:false,
            cpanel_mouseover:false,
            text_mouseover:false,
            text_effect:"fade",
            text_sync:true,
            cpanel_align:"TR",
            timer_align:"bottom",
            move_one:false,
            auto_adjust:true,
            shuffle:false,
            play_once:false,
            block_size:75,
            vert_size:50,
            horz_size:50,
            block_delay:35,
            vstripe_delay:90,
            hstripe_delay:180
      });
   }
);
</script>

The table below describes each attribute in more detail:

Parameters Table:

Attribute Name	Description	Default Value	Possible Values
screen_width	The width of the banner screen in pixel.	600	Any positive number.
screen_height	The height of the banner screen in pixel.	300	Any positive number.
item_width	The width a list item in pixel.	250	Any positive number.
item_height	The height a list item in pixel.	75	Any positive number.
item_display	The number of items display at a time.	4	Any positive number.
list_align	The alignment of the item list.	"left"	"left", "right"
scroll_type	The scrolling type use for navigating the list. note: If you specify "none", navigation of list is done through item click.	"mouse_move"	"mouse_move", "mouse_over", "mouse_click", "none"
auto_start	Specify if image rotation initially starts.	true	true, false.
delay	The global time delay for image rotation in milliseconds. If delay is set per item, it will take precedence over this global delay	5000	Any positive number.
transition	The global transition use for images. If transition is set per item, it will take precedence over this global transition.	"fade"	See the next table for more information on the available transitions.
transition_speed	The transition speed/duration use for image transition in milliseconds.	800	Any positive number.
easing	The easing used for image transition. note: To use easing other than "" (none) or "linear", you must include the additional easing file in your page, refer to Section 2 for information on including this file.	""	Please visit jQuery Easing Plugin for a list of all available easing.
auto_center	If images are automatically centered.	true	true, false.
display_playbutton	To specify if the play/pause button is visible.	true	true, false.
display_number	To specify if the current image number is visible.	true	true, false.
display_timer	To specify if the timer indicator bar is visible.	true	true, false.
display_arrow	To specify if the selected item's arrow is visible.	true	true, false.
display_thumbs	To specify if the thumbnail images are visible.	true	true, false.
display_scrollbar	To specify if the scroll bar indicator is visible.	true	true, false.
mouseover_select	To specify if banners are selected from mouseovering the thumbnails.	false	true, false.
pause_mouseover	To specify if rotation pauses on mouseover and resumes on mouseout.	false	true, false.
cpanel_mouseover	To specify if the control panel appears only on mouseover and hides on mouseout.	false	true, false.
text_mouseover	To specify if the text box appears only on mouseover and hides on mouseout.	false	true, false.
text_effect	The transition effect used for text box transition.	"fade"	"none", "fade", "up", "down", "left", "right".
text_sync	If true, text box appears after image transition is completed. If false, text box appears immediately without synching with image transition.	true	true, false.
cpanel_align	The alignment of the control panel.	"BR"	"TL", "TC", "TR", "BL", "BC", "BR"
timer_align	The alignment of the timer indicator.	"bottom"	"top", "bottom"
move_one	Used when scroll_type is "mouse_click" only. If true, list items move by one unit per click. If false, list items move by the number set in item_display.	false	true, false.
auto_adjust	To specify if items' position are automatically adjusted when image rotates.	true	true, false.
shuffle	To specify if items are displayed in random order.	false	true, false.
play_once	Specify if rotation plays only once through.	false	true, false.
block_size	The size of the blocks use for block transitions.	75	Any positive number.
vert_size	The size of the vertical stripes use for vertical stripe transitions.	50	Any positive number.
horz_size	The size of the horizontal stripes use for horizontal stripe transitions.	50	Any positive number.
block_delay	The delay until the next block transition occurs in sequence. (in milliseconds)	35	Any positive number.
vstripe_delay	The delay until the next vertical stripe transition occurs in sequence. (in milliseconds)	90	Any positive number.
hstripe_delay	The delay until the next horizontal stripe transition occurs in sequence. (in milliseconds)	180	Any positive number.

Transitions Table:

Transition Value	Description	Category
none	No transition	N/A
fade	Fade in transition
h.slide	Horizontal slide transition
v.slide	Vertical slide transition
random	Random transition (random only includes all the transitions listed below)
block.top	Blocks expand, starting from top.	Blocks
block.bottom	Blocks expand, starting from bottom.
block.left	Blocks expand, starting from left.
block.right	Blocks expand, starting from right.
diag.fade	Blocks fade in, starting diagonally.
diag.exp	Blocks expand, starting diagonally.
rev.diag.fade	Blocks fade in, reverse diagonally.
rev.diag.exp	Blocks expand, reverse diagonally.
block.fade	Blocks fade in at random speed.
block.exp	Blocks expand at random speed.
block.drop	Blocks fall at random speed.
block.top.zz	Blocks fade in, start from top and zig zag down.
block.bottom.zz	Blocks fade in, start from bottom and zig zag top.
block.left.zz	Blocks fade in, start from left and zig zag right.
block.right.zz	Blocks fade in, start from right and zig zag left.
spiral.in	Blocks fade in, spiraling in.
spiral.out	Blocks fade out, spiraling out.
vert.random.fade	Vertical stripe fade in at random.	Vertical Stripe
vert.tl	Vertical stripe transition starting top left.
vert.tr	Vertical stripe transition starting top right.
vert.bl	Vertical stripe transition starting bottom left.
vert.br	Vertical stripe transition starting bottom right.
fade.left	Vertical stripe transition fade starting from left.
fade.right	Vertical stripe transition fade starting from right.
alt.left	Alternating vertical stripe transition starting from left.
alt.right	Alternating vertical stripe transition starting from right.
blinds.left	Vertical blinds transition starting from left.
blinds.right	Vertical blinds transition starting from right.
horz.random.fade	Horizontal stripe fade in at random.	Horizontal Stripe
horz.tl	Horizontal stripe transition starting top left.
horz.tr	Horizontal stripe transition starting top right.
horz.bl	Horizontal stripe transition starting bottom left.
horz.br	Horizontal stripe transition starting bottom right.
fade.top	Horizontal stripe transition fade starting from top.
fade.bottom	Horizontal stripe transition fade starting from bottom.
alt.top	Alternating horizontal stripe transition starting from top.
alt.bottom	Alternating horizontal stripe transition starting from bottom.
blinds.top	Horizontal blinds transition starting from top.
blinds.bottom	Horizontal blinds transition starting from bottom.

back to top

Contact Information:

For help or questions regarding this file, please contact me using the email form on my profile page.

back to top