forked from fredwu/jcarousel
/
index.html
499 lines (490 loc) · 21.6 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
<!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.4 (<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>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="#Configuration">Configuration</a></li>
<li><a href="#Compatibility">Compatibility</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_circular.html">Circular dynamic carousel</a></li>
<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="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>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>
or <code>"both"</code> as string. If set to <code>null</code>,
wrapping is turned off (default). You can also pass <code>"circular"</code>
as option to enable support for circular carousels. See the example
<a href="examples/special_circular.html">Circular carousel</a> on how
to implement it.</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>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>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="Compatibility"></a>
<h3>Compatibility</h3>
<p>jCarousel has been tested and works on the following browsers:</p>
<ul>
<li>Internet Explorer 6 (PC)</li>
<li>Internet Explorer 7 (PC)</li>
<li>FireFox 1.5.0.6 (PC/Mac/Linux)</li>
<li>Opera 9.01 (PC/Mac)</li>
<li>Safari 2.0.4 (Mac)</li>
<li>Safari 3.1.0 (PC)</li>
<li>Konqueror 3.4.0 (Linux)</li>
</ul>
<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>