This README file is open source, available under the Creative Commons Attribution 3.0 Unported license <http://creativecommons.org/licenses/by/3.0/>. Attribution to the following people is required: Jay Kerschner.
======DOCUMENTATION: jQuery.rotator version 1.0======
Formatting note: Code examples are contained within <code>...</code> tags. URLs, variable names, and single HTML tags are contained in <> brackets.
===Introduction===
jQuery.rotator is a plugin for the popular JavaScript library jQuery <http://jquery.com/>. It is designed to make it easy to change the content of page, either whenever the page loads, or dynamically while the user is reading.
This page documents version 1.0 of the jQuery.rotator plugin; if you are using an older version, some features may not be available and you should upgrade as soon as possible. You can download the plugin and view previous versions of it at the project's page at SourceForge.net <http://sourceforge.net/projects/jquery-rotator/>. jQuery.rotator is available under the MIT License <http://en.wikipedia.org/wiki/MIT_License>, which is also used by the jQuery library itself.
This documentation assumes that the reader has a basic understanding of HTML, JavaScript, and jQuery.
===Downloading===
jQuery.rotator is downloaded and added to a page just like any other jQuery plugin, but we've written instructions here for anyone who may not have used a jQuery plugin before or who needs a refresher.
Before you can use jQuery.rotator, you must download it, upload it to your web server, and link it with the pages you need it to be used on. The latest veresion of jQuery.rotator can be downloaded at <http://sourceforge.net/projects/jquery-rotator/files/>. Open up the folder with the most recent release and you should see three files: jquery.rotator-x.x.js (the human-readable version of the code, primarily used when you want to read or modify the plugin), jquery.rotator-x.x.min.js (the minified version of the plugin, ideal for standard use), and README.txt (a copy of this documentation specific to the version of jQuery.rotator that is stored in the same folder). Download the minified code by clicking the file's name and, once it loads, saving the opened file (typically, this can be done through your browser's "file" menu.
Next, upload the folder to the server of the website you want to use it on, using whatever method you normally do for file uploads. It should typically be placed in the same (or similar) location to the jQuery library itself (if you downloaded it).
Finally, add the following to the page where you want to use it by writing the following in the document right after the place where the jQuery library itself has been included: <code><script src="/scripts/jquery.rotator-x.x.min.js" type="text/javascript"></script></code>. Modify the <src> to reflect where the plugin file is on the server and what version of the plugin you are using. The <type> may be omitted if you are using HTML5.
===HTML Code===
jQuery.rotator requires that part of your HTML code be formatted in a certain way. Specificially, you can only use it on unordered lists (<ul>s) of items. Each item in the list represents one item for the plugin to include in its set of things to rotate. In addition, it is a good idea to give the whole list (the <ul> tag) an <id> so that you can easily identify in with jQuery. Here is an example, which we'll use in most of the remaining examples in this documentation:
<code>
<ul id="items-to-rotate">
<li>The first item!</li>
<li>The second item!</li>
<li>The third item!</li>
</ul>;
</code>
Each item may consist of any valid HTML that can usually be included in lists, including normal content, images, links, or even, other lists.
WARNING: Note that if a user visiting the page has JavaScript turned off, or is using a browser which doesn't support JavaScript, all of the items in the list will be shown. Because of this, it may be good to use CSS to set the <display> of all but one item (that one to be shown even if JavaScript is disabled) to <none>. If you want to be even more certain that not all of the items will be shown, use JavaScript to add the HTML to the page, so that even non-CSS users don't see it. The number of users without JavaScript is, at this point, very small, and users without CSS is even smaller (mostly limited to users of some text-based browsers).
WARNING: When the plugin is run on an unordered list, any CSS applied to the list and it's items is discarded. CSS applied to tags with the list items is unaffected. In order to style the items once they are being rotated, then, you need to apply styles and classes within the items, not to the <li> tags, and to style the entire area where the content is held, you must instead style a parent of the entire list.
===Basic Rotation===
Now, let's make your page dynamic! The most basic (and the default) behavior of jQuery.rotator is to select a random item from your list and replace the entire list with just that one item. Which item is selected may change each time the page loads. This behavior uses a very simple call to the plugin's eponymous function, <code>$().rotator()</code>, and no special parameters are needed. To run it on the above example as soon as possible, use <code>$(document).ready(function(){$("#items-to-rotate").rotator();});</code>. Using <code>$(document).ready()</code> ensures that the list has already been created, and will usually cause the plugin to run before the user even sees anything.
This isn't typically a very useful case, because simple randomization such as this could be done on the server-side quicker using a language like PHP or Python. However, this basic functionality is included because it serves as a good default behavior for the plugin, and it is also usable if server-side languages aren't available.
Another very simple use of the plugin is to choose a specific item and only ever display that one. This can be done by setting the <mode> of the rotator to <static> and setting the <base_num> option to an integer representing the item to use (the items are 1-indexed, the first item is number 1, the second item is number 2, and so on). All options, including these two, are passed to the plugin as an object when you call it. To only ever show the second item in the example above, we'd use <code>$(document).ready(function(){$("#items-to-rotate").rotator({mode: "static", base_num: 2});});</code>. This second example is, perhaps, even more pointless than the first one because the item content could just be coded directly into the HTML rather than using the plugin. However, when testing the plugin or using only placeholder content, using <static> may be appropriate.
===Using the Date and Time===
This is where things can get interesting. jQuery.rotator allows you to rotate content based on the date or time of when it is run. This is great for "quote of the day" sections and other time-based content. Using the date and time requires that you set to options. First, <mode> must be set to <datetime>. Second, <switch_every> must be set to one of the following: <millisecond>, <second>, <minute>, <hour>, <day> (of month), <month>, or <year>. If <switch_every<> is not set, it defaults to <day>.
With our earlier example, we could use <code>$(document).ready(function(){$("#items-to-rotate").rotator({mode: "datetime", switch_every: "hour"});});</code> to rotate which one is shown every hour. The first hour of the day, it would show the first item. The second hour of the day, the second item. The third hour of the day, the third item. Once it has gone through all of the items this way, it restarts back at the beginning, so the fourth hour would use the first item again, and so on.
WARNING: Note that the rotation resets to the first item whenever the counter (such as the hour of the day) goes back to zero... this means that if you had, say, ten items in an hour-based, it would go through all of them at least twice (the first 20 hours of the day), and then use the first four again... but then it would restart at the first one again once it hit hour "25". In addition, if you had more than 24 items in the rotation, only the first 24 would ever be seen. This is a known bug which will hopefully be solved at some point in the future.
===Fading===
Finally, here's something that absolutely cannot be done with server-side technologies, and which is more representative of where we plan to take jQuery.rotator in the future: Fading from one item to the next on-screen. Setting this up is quite simple. There are two types of fades: "simplefades" and "crossfades". A simplefade fades out one item, and then fades in the next item. A crossfade fades one item out, and the next item in, at the same time. Just set the <mode> to either <simplefade> or <crossfade> to use one of these. The initial item will be random unless <base_num> is set.
By default, each fade starts 5 seconds after the previous one started, and each fade takes 1 second to complete. These can be changed easily. The <fade_interval> option sets (in milliseconds) how long since the start of the last fade the next fade should start. The <fade_time> option sets (also in milliseconds) how long the animation takes.
One final option is also available, <box_sizechange_mode>. Sometimes, the items being rotated take up a different amount of on-screen space. The area which the items occupy will, by default, slide during the animation sequence so that it matches the size of the new box. If you want the surrounding to just instantly change, set the value of this option to <instant>.
