| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
- <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us">
- <head>
- <title>jCarousel - Riding carousels with jQuery</title>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <link href="style.css" rel="stylesheet" type="text/css">
- </head>
- <body>
- <div id="wrap">
- <h1>jCarousel</h1>
- <h2>Riding carousels with jQuery</h2>
- <p><strong>Author:</strong> <a href="http://sorgalla.com">Jan Sorgalla</a><br />
- <strong>Version:</strong> 0.2.8 (<a href="changelog.html">Changelog</a>)<br />
- <strong>Download:</strong> <a href="http://sorgalla.com/projects/download.php?jcarousel">jcarousel.tar.gz</a> or <a href="http://sorgalla.com/projects/download-zip.php?jcarousel">jcarousel.zip</a><br />
- <strong>Source Code:</strong> <a href="http://github.com/jsor/jcarousel">http://github.com/jsor/jcarousel</a><br/>
- <strong>Bugtracker:</strong> <a href="http://github.com/jsor/jcarousel/issues">http://github.com/jsor/jcarousel/issues</a><br/>
- <strong>Licence:</strong> Dual licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT</a>
- and <a href="http://www.opensource.org/licenses/gpl-license.php">GPL</a> licenses.</p>
- <a name="Contents"></a>
- <h3>Contents</h3>
- <ol>
- <li><a href="#Introduction">Introduction</a></li>
- <li><a href="#Examples">Examples</a></li>
- <li><a href="#Getting-Started">Getting started</a></li>
- <li><a href="#Dynamic-Content-Loading">Dynamic content loading</a></li>
- <li><a href="#Accessing-The-Jcarousel-Instance">Accessing the jCarousel instance</a></li>
- <li><a href="#Defining-The-Number-Of-Visible-Items">Defining the number of visible items</a></li>
- <li><a href="#Configuration">Configuration</a></li>
- <li><a href="#Credits">Credits</a></li>
- </ol>
- <a name="Introduction"></a>
- <h3>Introduction</h3>
- <p>jCarousel is a <a href="http://jquery.com">jQuery</a> plugin for controlling
- a list of items in horizontal or vertical order. The items, which can be static
- HTML content or loaded with (or without) AJAX, can be scrolled back and forth
- (with or without animation).</p>
- <a name="Examples"></a>
- <h3>Examples</h3>
- <p>The following examples illustrate the possibilities of jCarousel:</p>
- <noscript>
- <p style="color:red">You need JavaScript enabled to see the carousel</p>
- </noscript>
- <ul>
- <li><strong>Static Examples</strong>
- <ul>
- <li><a href="examples/static_simple.html">Simple carousel</a></li>
- <li><a href="examples/static_vertical.html">Vertical carousel</a></li>
- <li><a href="examples/static_circular.html">Circular carousel</a></li>
- <li><a href="examples/static_auto.html">Carousel with autoscrolling</a></li>
- <li><a href="examples/static_callbacks.html">Carousel illustrating the
- callback functions</a></li>
- <li><a href="examples/static_controls.html">Carousel with external controls</a></li>
- <li><a href="examples/static_start.html">Carousel with custom start position</a></li>
- <li><a href="examples/static_multiple.html">Multiple carousels on one page</a></li>
- </ul>
- </li>
- <li><strong>Dynamic Examples</strong>
- <ul>
- <li><a href="examples/dynamic_javascript.html">Carousel with dynamic content
- loading via JavaScript</a></li>
- <li><a href="examples/dynamic_ajax.html">Carousel with dynamic content
- loading via Ajax</a></li>
- <li><a href="examples/dynamic_ajax_php.html">Carousel with dynamic content
- loading via Ajax from a PHP script</a></li>
- <li><a href="examples/dynamic_flickr_feed.html">Carousel with dynamic
- content loading via Ajax from the Flickr photo stream</a></li>
- <li><a href="examples/dynamic_flickr_api.html">Carousel with dynamic content
- loading via Ajax from the Flickr API</a></li>
- </ul>
- </li>
- <li><strong>Special Examples</strong>
- <ul>
- <li><a href="examples/special_textscroller.html">Using jCarousel as a
- Textscroller</a></li>
- <li><a href="examples/special_flexible.html">Flexible carousel</a></li>
- <li><a href="examples/special_thickbox.html">jCarousel and Thickbox 3</a></li>
- <li><a href="examples/special_easing.html">Carousel with custom animation
- effect</a></li>
- </ul>
- </li>
- </ul>
- <a name="Getting-Started"></a>
- <h3>Getting started</h3>
- <p>To use the jCarousel component, include the <a href="http://jquery.com">jQuery</a>
- library, the jCarousel source file and a jCarousel skin stylesheet file inside the <code><head></code> tag
- of your HTML document:</p>
- <pre>
- <script type="text/javascript" src="/path/to/jquery-1.4.2.min.js"></script>
- <script type="text/javascript" src="/path/to/lib/jquery.jcarousel.min.js"></script>
- <link rel="stylesheet" type="text/css" href="/path/to/skin/skin.css" />
- </pre>
- <p>The download package contains some example skin packages. Feel free to build your own skins based on it.</p>
- <p>jCarousel expects a very basic HTML markup structure inside your HTML document:</p>
- <pre>
- <ul id="mycarousel" class="jcarousel-skin-<em>name</em>">
- <!-- The content goes in here -->
- </ul>
- </pre>
- <p>jCarousel automatically wraps the required HTML markup around the list. The
- class attribute applies the jCarousel skin <em>"name"</em> to the
- carousel.</p>
- <p> To setup jCarousel, add the following code inside the <code><head></code>
- tag of your HTML document:</p>
- <pre>
- <script type="text/javascript">
- jQuery(document).ready(function() {
- jQuery('#mycarousel').jcarousel({
- // Configuration goes here
- });
- });
- </script>
- </pre>
- <p> jCarousel accepts a lot of configuration options, see chapter "<a href="#Configuration">Configuration</a>"
- for further informations.</p>
- <p>After jCarousel has been initialised, the fully created markup in
- the DOM is:</p>
- <pre>
- <div class="jcarousel-skin-<em>name</em>">
- <div class="jcarousel-container">
- <div class="jcarousel-clip">
- <ul class="jcarousel-list">
- <li class="jcarousel-item-1">First item</li>
- <li class="jcarousel-item-2">Second item</li>
- </ul>
- </div>
- <div disabled="disabled" class="jcarousel-prev jcarousel-prev-disabled"></div>
- <div class="jcarousel-next"></div>
- </div>
- </div>
- </pre>
- <p>As you can see, there are some elements added which have assigned classes
- (in addition to the classes you may have already assigned manually). Feel
- free to design your carousel with the classes you can see above.</p>
- <h4>Note:</h4>
- <ul>
- <li>The skin class "jcarousel-skin-<em>name"</em> has been moved
- from the <code><ul></code> to the top <code><div></code> element.</li>
- <li>The last 2 nested <code><div></code>'s under <code><div class="jcarousel-container"></code>
- are the next/prev buttons of the carousel. The first one illustrates a disabled button, the second an enabled one. The disabled
- button has the attribute
- <code>disabled</code> (which actually makes no sense for <code><div></code>
- elements, but you can also use <code><button></code> elements or
- whatever you want) as well as the additional class <code>jcarousel-prev-disabled</code>
- (or <code>jcarousel-next-disabled</code>).</li>
- <li>All <code><li></code> elements of the list have the class <code></code><code>jcarousel-item-<em>n</em></code>
- assigned where <code><em>n</em></code> represents the position in the list.</li>
- <li>Not shown here is, that all classes are followed by additional classes with a suffix
- dependent on the orientation of the carousel, ie. <code><ul class="jcarousel-list
- jcarousel-list-horizontal"></code> for a horizontal carousel.</li>
- </ul>
- <a name="Dynamic-Content-Loading"></a>
- <h3>Dynamic content loading</h3>
- <p>By passing the callback function <code>itemLoadCallback</code> as configuration
- option, you are able to dynamically create <code><li></code> items for the content.</p>
- <pre>
- <script type="text/javascript">
- jQuery(document).ready(function() {
- jQuery('#mycarousel').jcarousel({
- itemLoadCallback: itemLoadCallbackFunction
- });
- });
- </script></pre>
- <p><code>itemLoadCallbackFunction</code> is a JavaScript function that is called
- when the carousel requests a set of items to be loaded. Two parameters are
- passed: The instance of the requesting carousel and a flag which indicates
- the current state of the carousel ('init', 'prev' or 'next').</p>
- <pre>
- <script type="text/javascript">
- function itemLoadCallbackFunction(carousel, state)
- {
- for (var i = carousel.first; i <= carousel.last; i++) {
- // Check if the item already exists
- if (!carousel.has(i)) {
- // Add the item
- carousel.add(i, "I'm item #" + i);
- }
- }
- };
- </script></pre>
- <p>jCarousel contains a convenience method <code>add()</code> that can be
- passed the index of the item to create and the innerHTML string of the
- item to be
- created. If the item already exists, it just updates the innerHTML. You can
- access the index of the first and last visible element by the public variables <code>carousel.first</code> and <code>carousel.last</code>.
- </p>
- <a name="Accessing-The-Jcarousel-Instance"></a>
- <h3>Accessing the jCarousel instance</h3>
- <p>The instance of the carousel will be stored with the <code>data()</code> method of jQuery under the key <code>jcarousel</code> for a simple access.</p>
- <p>If you have created a carousel like:</p>
- <pre>
- jQuery(document).ready(function() {
- jQuery('#mycarousel').jcarousel();
- });</pre>
- <p>You can access the instance with:</p>
- <pre>
- var carousel = jQuery('#mycarousel').data('jcarousel');</pre>
- <p>You can also access methods of the instance directly, for example the <code>add()</code> method:
- <pre>
- var index = 1;
- var html = 'My content of item no. 1';
- jQuery('#mycarousel').jcarousel('add', index, html);</pre>
- <a name="Defining-The-Number-Of-Visible-Items"></a>
- <h3>Defining the number of visible items</h3>
- <p>Sometimes people are confused how to define the number of visible items because there is no option for this as they expect (Yes, there is an option <code>visible</code>, we discuss this later).</p>
- <p>You simply define the number of visible items by defining the width (or height) with the class <code>.jcarousel-clip</code> (or the more distinct <code>.jcarousel-clip-horizontal</code> and <code>.jcarousel-clip-vertical</code> classes) in your skin stylesheet.</p>
- <p>This offers a lot of flexibility, because you can define the width in pixel for a fixed carousel or in percent for a flexible carousel (<a href="examples/static_callbacks.html">This example</a> shows a carousel with a clip width in percent, resize the browser to see it in effect).</p>
- <p>So, why there is an option <code>visible</code>? If you set the option <code>visible</code>, jCarousel sets the width of the visible items to always make this number of items visible. Open <a href="examples/special_flexible.html">this example</a> and resize your browser window to see it in effect.</p>
- <a name="Configuration"></a>
- <h3>Configuration</h3>
- <p> jCarousel accepts a list of options to control the appearance and behaviour
- of the carousel. Here is the list of options you may set: </p>
- <table>
- <thead>
- <tr>
- <th>Property</th>
- <th>Type</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>vertical</td>
- <td>bool</td>
- <td>false</td>
- <td>Specifies wether the carousel appears in horizontal or vertical orientation.
- Changes the carousel from a left/right style to a up/down style carousel.</td>
- </tr>
- <tr>
- <td>rtl</td>
- <td>bool</td>
- <td>false</td>
- <td>Specifies wether the carousel appears in RTL (Right-To-Left) mode.</td>
- </tr>
- <tr>
- <td>start</td>
- <td>integer</td>
- <td>1</td>
- <td>The index of the item to start with.</td>
- </tr>
- <tr>
- <td>offset</td>
- <td>integer</td>
- <td>1</td>
- <td>The index of the first available item at initialisation.</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>size</td>
- <td>integer</td>
- <td><em>Number of existing <li> elements if size is not passed explicitly</em></td>
- <td>The number of total items.</td>
- </tr>
- <tr>
- <td>scroll</td>
- <td>integer</td>
- <td>3</td>
- <td>The number of items to scroll by.</td>
- </tr>
- <tr>
- <td>visible</td>
- <td>integer</td>
- <td>null</td>
- <td>If passed, the width/height of the items will be calculated and set
- depending on the width/height of the clipping, so that exactly that
- number of items will be visible.</td>
- </tr>
- <tr>
- <td>animation</td>
- <td>mixed</td>
- <td>"fast"</td>
- <td>The speed of the scroll animation as string in jQuery terms (<code>"slow"</code>
- or <code>"fast"</code>) or milliseconds as integer
- (See <a href="http://docs.jquery.com/effects/animate">jQuery Documentation</a>).
- If set to 0, animation is turned off.</td>
- </tr>
- <tr>
- <td>easing</td>
- <td>string</td>
- <td>null</td>
- <td>The name of the easing effect that you want to use (See <a href="http://docs.jquery.com/effects/animate">jQuery
- Documentation</a>).</td>
- </tr>
- <tr>
- <td>auto</td>
- <td>integer</td>
- <td>0</td>
- <td>Specifies how many seconds to periodically autoscroll the content.
- If set to <code>0</code> (default) then autoscrolling is turned off.
- </td>
- </tr>
- <tr>
- <td>wrap</td>
- <td>string</td>
- <td>null</td>
- <td>Specifies whether to wrap at the first/last item (or both) and jump
- back to the start/end. Options are <code>"first"</code>, <code>"last"</code>,
- <code>"both"</code> or <code>"circular"</code> as string. If set to <code>null</code>,
- wrapping is turned off (default).</td>
- </tr>
- <tr>
- <td>initCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called right after initialisation of the
- carousel. Two parameters are passed: The instance of the requesting
- carousel and the state of the carousel initialisation (init, reset or
- reload).</td>
- </tr>
- <tr>
- <td>setupCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called right after the carousel is completely setup.
- One parameter is passed: The instance of the requesting carousel.</td>
- </tr>
- <tr>
- <td>itemLoadCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called when the carousel requests a set
- of items to be loaded. Two parameters are passed: The instance of the
- requesting carousel and the state of the carousel action (prev, next
- or init). Alternatively, you can pass a hash of one or two functions
- which are triggered before and/or after animation:
- <pre>
- itemLoadCallback: {
- onBeforeAnimation: callback1,
- onAfterAnimation: callback2
- }</pre> </td>
- </tr>
- <tr>
- <td>itemFirstInCallback </td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called (after the scroll animation) when
- an item becomes the first one in the visible range of the carousel.
- Four parameters are passed: The instance of the requesting carousel
- and the <code><li></code> object itself, the index which indicates
- the position of the item in the list and the state of the carousel action
- (prev, next or init). Alternatively, you can pass a hash of one or two
- functions which are triggered before and/or after animation:
- <pre>
- itemFirstInCallback: {
- onBeforeAnimation: callback1,
- onAfterAnimation: callback2
- }</pre> </td>
- </tr>
- <tr>
- <td>itemFirstOutCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called (after the scroll animation) when
- an item isn't longer the first one in the visible range of the carousel.
- Four parameters are passed: The instance of the requesting carousel
- and the <code><li></code> object itself, the index which indicates
- the position of the item in the list and the state of the carousel action
- (prev, next or init). Alternatively, you can pass a hash of one or two
- functions which are triggered before and/or after animation:
- <pre>
- itemFirstOutCallback: {
- onBeforeAnimation: callback1,
- onAfterAnimation: callback2
- }</pre> </td>
- </tr>
- <tr>
- <td>itemLastInCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called (after the scroll animation) when
- an item becomes the last one in the visible range of the carousel. Four
- parameters are passed: The instance of the requesting carousel and the
- <code><li></code> object itself, the index which indicates the
- position of the item in the list and the state of the carousel action
- (prev, next or init). Alternatively, you can pass a hash of one or two
- functions which are triggered before and/or after animation:
- <pre>
- itemLastInCallback: {
- onBeforeAnimation: callback1,
- onAfterAnimation: callback2
- }</pre> </td>
- </tr>
- <tr>
- <td>itemLastOutCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called when an item isn't longer the last
- one in the visible range of the carousel. Four parameters are passed:
- The instance of the requesting carousel and the <code><li></code>
- object itself, the index which indicates the position of the item in
- the list and the state of the carousel action (prev, next or init).
- Alternatively, you can pass a hash of one or two functions which are
- triggered before and/or after animation:
- <pre>
- itemLastOutCallback: {
- onBeforeAnimation: callback1,
- onAfterAnimation: callback2
- }</pre> </td>
- </tr>
- <tr>
- <td>itemVisibleInCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called (after the scroll animation) when
- an item is in the visible range of the carousel. Four parameters are
- passed: The instance of the requesting carousel and the <code><li></code>
- object itself, the index which indicates the position of the item in
- the list and the state of the carousel action (prev, next or init).
- Alternatively, you can pass a hash of one or two functions which are
- triggered before and/or after animation:
- <pre>
- itemVisibleInCallback: {
- onBeforeAnimation: callback1,
- onAfterAnimation: callback2
- }</pre> </td>
- </tr>
- <tr>
- <td>itemVisibleOutCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called (after the scroll animation) when
- an item isn't longer in the visible range of the carousel. Four parameters
- are passed: The instance of the requesting carousel and the <code><li></code>
- object itself, the index which indicates the position of the item in
- the list and the state of the carousel action (prev, next or init).
- Alternatively, you can pass a hash of one or two functions which are
- triggered before and/or after animation:
- <pre>
- itemVisibleOutCallback: {
- onBeforeAnimation: callback1,
- onAfterAnimation: callback2
- }</pre> </td>
- </tr>
- <tr>
- <td>animationStepCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called after each animation step. This
- function is directly passed to jQuery's <code>.animate()</code> method
- as the <code>step</code> parameter. See the jQuery documentation for the
- parameters it will receive.</td>
- </tr>
- <tr>
- <td>buttonNextCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called when the state of the 'next' control
- is changing. The responsibility of this method is to enable or disable
- the 'next' control. Three parameters are passed: The instance of the
- requesting carousel, the control element and a flag indicating whether
- the button should be enabled or disabled.</td>
- </tr>
- <tr>
- <td>buttonPrevCallback</td>
- <td>function</td>
- <td>null</td>
- <td>JavaScript function that is called when the state of the 'previous'
- control is changing. The responsibility of this method is to enable
- or disable the 'previous' control. Three parameters are passed: The
- instance of the requesting carousel, the control element and a flag
- indicating whether the button should be enabled or disabled.</td>
- </tr>
- <tr>
- <td>buttonNextHTML</td>
- <td>string</td>
- <td><code><div></div></code></td>
- <td>The HTML markup for the auto-generated next button. If set to <code>null</code>,
- no next-button is created.</td>
- </tr>
- <tr>
- <td>buttonPrevHTML</td>
- <td>string</td>
- <td><code><div></div></code></td>
- <td>The HTML markup for the auto-generated prev button. If set to <code>null</code>,
- no prev-button is created.</td>
- </tr>
- <tr>
- <td>buttonNextEvent</td>
- <td>string</td>
- <td>"click"</td>
- <td>Specifies the event which triggers the next scroll.</td>
- </tr>
- <tr>
- <td>buttonPrevEvent</td>
- <td>string</td>
- <td>"click"</td>
- <td>Specifies the event which triggers the prev scroll.</td>
- </tr>
- <tr>
- <td>itemFallbackDimension</td>
- <td>integer</td>
- <td>null</td>
- <td>If, for some reason, jCarousel can not detect the width of an item, you can set a fallback dimension (width or height, depending on the orientation) here to ensure correct calculations.</td>
- </tr>
- </tbody>
- </table>
- <a name="Credits"></a>
- <h3>Credits</h3>
- <p>Thanks to <a href="http://ejohn.org">John Resig</a> for his fantastic <a href="http://jquery.com">jQuery</a>
- library. <br>
- jCarousel is inspired by the <a href="http://billwscott.com/carousel/">Carousel
- Component</a> written by <a href="http://looksgoodworkswell.com">Bill Scott</a>.</p>
- </div>
- </body>
- </html>
|