Skip to content
This repository
Newer
Older
100644 401 lines (347 sloc) 16.566 kb
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
1 <?xml version="1.0"?>
22fafb33 » rdworth
2012-05-25 Fixed relative urls of xslt
2 <?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
3 <entry name="tabs" namespace="fn" type="Widget" widgetnamespace="ui">
4 <longdesc>
5
6 <p>Tabs are generally used to break content into multiple sections that can be swapped to save space, much like an accordion.</p>
7
8 <p>By default a tab widget will swap between tabbed sections onClick, but the events can be changed to onHover through an option. Tab content can be loaded via Ajax by setting an href on a tab.</p>
9
10 <p><em>NOTE: Tabs created dynamically using .tabs( "add", ... ) are given an id of ui-tabs-NUM, where NUM is an auto-incrementing id. If you use this naming convention for your own elements, you may encounter problems.</em></p>
11
12 ==Events==
13
14 A series of events fire when interacting with a tabs interface:
15
16 * tabsselect, tabsload, tabsshow (in that order)
17 * tabsadd, tabsremove
18 * tabsenable, tabsdisable
19
20 Event binding example:
21
22 <pre><![CDATA[$('#example').bind('tabsselect', function(event, ui) {
23
24 // Objects available in the function context:
25 ui.tab // anchor element of the selected (clicked) tab
26 ui.panel // element, that contains the selected/clicked tab contents
27 ui.index // zero-based index of the selected (clicked) tab
28
29 });]]></pre>
30
31 Note that if a handler for the tabsselect event returns false, the clicked tab will not become selected (useful for example if switching to the next tab requires a form validation).
32
33 == Ajax mode ==
34
35 Tabs supports loading tab content via Ajax in an unobtrusive manner.
36
37 The HTML you need is slightly different from the one that is used for static tabs: A list of links pointing to existing resources (from where the content gets loaded) and no additional containers at all (unobtrusive!). The containers' markup is going to be created on the fly:
38
39 <pre><![CDATA[
40 <div id="example">
41 <ul>
42 <li><a href="ahah_1.html"><span>Content 1</span></a></li>
43 <li><a href="ahah_2.html"><span>Content 2</span></a></li>
44 <li><a href="ahah_3.html"><span>Content 3</span></a></li>
45 </ul>
46 </div>
47 ]]></pre>
48
49 Obviously this degrades gracefully - the links, e.g. the content, will still be accessible with JavaScript disabled.
50
51 Note that if you wish to reuse an existing container, you
52 could do so by matching a title attribute and the container's id:
53
54 <pre><![CDATA[
55 <li><a href="hello/world.html" title="Todo Overview"> ... </a></li>
56 ]]></pre>
57
58 and a container like:
59
60 <pre><![CDATA[
61 <div id="Todo_Overview"> ... </div>
62 ]]></pre>
63
64 (Note how white space is replaced with an underscore)
65
66 This is useful if you want a human readable hash in the URL instead of
67 a cryptic generated one.
68
69 ===Back button and bookmarking===
70
71 Tabs 2 already supported this functionality, although the history plugin needs a rewrite first (it doesn't support Safari 3 and is in general a little inflexible) before it can be build back into the tabs. It is planned and Klaus is working on it whenever he finds the time. Actual bugs in the UI Tabs plugin itself always have higher priority though.
72
73 ==How to...==
74
75 ===...retrieve the index of the currently selected tab===
76
77 <pre><![CDATA[var $tabs = $('#example').tabs();
78 var selected = $tabs.tabs('option', 'selected'); // => 0]]></pre>
79
80 ===...open links in the current tab instead of leaving the page===
81
82 "Hijax" links after tab content has been loaded:
83
84 <pre><![CDATA[$('#example').tabs({
85 load: function(event, ui) {
86 $(ui.panel).delegate('a', 'click', function(event) {
87 $(ui.panel).load(this.href);
88 event.preventDefault();
89 });
90 }
91 });]]></pre>
92
93 ===...select a tab from a text link instead of clicking a tab itself===
94
95 <pre><![CDATA[var $tabs = $('#example').tabs(); // first tab selected
96
97 $('#my-text-link').click(function() { // bind click event to link
98 $tabs.tabs('select', 2); // switch to third tab
99 return false;
100 });]]></pre>
101
102 ===...prevent switching to the tab on click depending on form validation===
103
104 Returning false in the tabs select handler prevents the clicked tab from becoming selected.
105
106 <pre><![CDATA[$('#example').tabs({
107 select: function(event, ui) {
108 var isValid = ... // form validation returning true or false
109 return isValid;
110 }
111 });]]></pre>
112
113 ===...immediately select a just added tab===
114
115 <pre><![CDATA[var $tabs = $('#example').tabs({
116 add: function(event, ui) {
117 $tabs.tabs('select', '#' + ui.panel.id);
118 }
119 });]]></pre>
120
121 ===...prevent a FOUC (Flash of Unstyled Content) before tabs are initialized===
122
123 Add the necessary classes to hide an inactive tab panel to the HTML right away - note that this will '''not''' degrade gracefully with JavaScript being disabled:
124
125 <pre><![CDATA[<div id="example" class="ui-tabs">
126 ...
127 <div id="a-tab-panel" class="ui-tabs-hide"> </div>
128 ...
129 </div>]]></pre>
130
131 ==Why does...==
132
133 ===...my slider, Google Map, sIFR etc. not work when placed in a hidden (inactive) tab?===
134
135 Any component that requires some dimensional computation for its initialization won't work in a hidden tab, because the tab panel itself is hidden via <code>display: none</code> so that any elements inside won't report their actual width and height (0 in most browsers).
136
137 There's an easy workaround. Use the <em>off-left technique</em> for hiding inactive tab panels. E.g. in your style sheet replace the rule for the class selector ".ui-tabs .ui-tabs-hide" with
138
139 <pre><![CDATA[.ui-tabs .ui-tabs-hide {
140 position: absolute;
141 left: -10000px;
142 }]]></pre>
143
144 For Google maps you can also resize the map once the tab is displayed like this:
145
146 <pre><![CDATA[$('#example').bind('tabsshow', function(event, ui) {
147 if (ui.panel.id == "map-tab") {
148 resizeMap();
149 }
150 });]]></pre>
151
152 resizeMap() will call Google Maps' checkResize() on the particular map.
153
154 </longdesc>
155 <created>1.0</created>
156 <options>
157 <option name="ajaxOptions" type="Options" default='null'>
158 <desc>Additional Ajax options to consider when loading tab content (see $.ajax).</desc>
159 </option>
160 <option name="cache" type="Boolean" default='false'>
161 <desc>Whether or not to cache remote tabs content, e.g. load only once or with every click. Cached content is being lazy loaded, e.g once and only once for the first click. Note that to prevent the actual Ajax requests from being cached by the browser you need to provide an extra cache: false flag to ajaxOptions.</desc>
162 </option>
163 <option name="collapsible" type="Boolean" default='false'>
164 <desc>Set to true to allow an already selected tab to become unselected again upon reselection.</desc>
165 </option>
166 <option name="cookie" type="Object" default='null'>
167 <desc>Store the latest selected tab in a cookie. The cookie is then used to determine the initially selected tab if the ''selected'' option is not defined. Requires [http://plugins.jquery.com/project/cookie cookie plugin], which can also be found in the development-bundle>external folder from the download builder. The object needs to have key/value pairs of the form the cookie plugin expects as options. Available options (example): &#123; expires: 7, path: '/', domain: 'jquery.com', secure: true &#125;. Since jQuery UI 1.7 it is also possible to define the cookie name being used via ''name'' property.</desc>
168 </option>
169 <option name="deselectable" type="Boolean" default='false'>
170 <desc>deprecated in jQuery UI 1.7, use collapsible.</desc>
171 </option>
ec5a1244 » jzaefferer
2012-05-25 Add or update disabled option for all widgets and interactions, along…
172 <option name="disabled" type="Boolean, Array&lt;Number>" default='false'>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
173 <desc>An array containing the position of the tabs (zero-based index) that should be disabled on initialization.</desc>
174 </option>
175 <option name="event" type="String" default='"click"'>
176 <desc>The type of event to be used for selecting a tab.</desc>
177 </option>
178 <option name="fx" type="Options, Array&lt;Options>" default='null'>
179 <desc>Enable animations for hiding and showing tab panels. The duration option can be a string representing one of the three predefined speeds ("slow", "normal", "fast") or the duration in milliseconds to run an animation (default is "normal").</desc>
180 </option>
181 <option name="idPrefix" type="String" default='"ui-tabs-"'>
182 <desc>If the remote tab, its anchor element that is, has no title attribute to generate an id from, an id/fragment identifier is created from this prefix and a unique id returned by $.data(el), for example "ui-tabs-54".</desc>
183 </option>
184 <option name="panelTemplate" type="String" default='"&lt;div&gt;&lt;/div&gt;"'>
185 <desc>HTML template from which a new tab panel is created in case of adding a tab with the add method or when creating a panel for a remote tab on the fly.</desc>
186 </option>
187 <option name="selected" type="Number" default='0'>
188 <desc>Zero-based index of the tab to be selected on initialization. To set all tabs to unselected pass -1 as value.</desc>
189 </option>
190 <option name="spinner" type="String" default='"&lt;em&gt;Loading&amp;#8230;&lt;/em&gt;"'>
191 <desc>The HTML content of this string is shown in a tab title while remote content is loading. Pass in empty string to deactivate that behavior. An span element must be present in the A tag of the title, for the spinner content to be visible.</desc>
192 </option>
193 <option name="tabTemplate" type="String" default='"&lt;li&gt;&lt;a href&#61;"#&#123;href&#125;"&gt;&lt;span&gt;#&#123;label&#125;&lt;/span&gt;&lt;/a&gt;&lt;/li&gt;"'>
194 <desc>HTML template from which a new tab is created and added. The placeholders #&#123;href&#125; and #&#123;label&#125; are replaced with the url and tab label that are passed as arguments to the add method.</desc>
195 </option>
196
197 </options>
198 <events>
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
199 <event name="create">
200 <desc>
201 This event is triggered when the tabs widget is created.
202 </desc>
203 <argument name="event" type="Event">
204 </argument>
205 <argument name="ui" type="Object">
206 </argument>
207 </event>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
208 <event name="select" type="tabsselect">
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
209 <desc>This event is triggered when clicking a tab.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
210 <argument name="event" type="Event">
211 <desc></desc>
212 </argument>
213 <argument name="ui" type="Object">
214 <desc></desc>
215 </argument>
216 </event>
217 <event name="load" type="tabsload">
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
218 <desc>This event is triggered after the content of a remote tab has been loaded.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
219 <argument name="event" type="Event">
220 <desc></desc>
221 </argument>
222 <argument name="ui" type="Object">
223 <desc></desc>
224 </argument>
225 </event>
226 <event name="show" type="tabsshow">
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
227 <desc>This event is triggered when a tab is shown.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
228 <argument name="event" type="Event">
229 <desc></desc>
230 </argument>
231 <argument name="ui" type="Object">
232 <desc></desc>
233 </argument>
234 </event>
235 <event name="add" type="tabsadd">
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
236 <desc>This event is triggered when a tab is added.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
237 <argument name="event" type="Event">
238 <desc></desc>
239 </argument>
240 <argument name="ui" type="Object">
241 <desc></desc>
242 </argument>
243 </event>
244 <event name="remove" type="tabsremove">
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
245 <desc>This event is triggered when a tab is removed.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
246 <argument name="event" type="Event">
247 <desc></desc>
248 </argument>
249 <argument name="ui" type="Object">
250 <desc></desc>
251 </argument>
252 </event>
253 <event name="enable" type="tabsenable">
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
254 <desc>This event is triggered when a tab is enabled.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
255 <argument name="event" type="Event">
256 <desc></desc>
257 </argument>
258 <argument name="ui" type="Object">
259 <desc></desc>
260 </argument>
261 </event>
262 <event name="disable" type="tabsdisable">
d76939b8 » jzaefferer
2012-05-25 Add create event to widgets and interactions, along with minor cleanups
263 <desc>This event is triggered when a tab is disabled.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
264 <argument name="event" type="Event">
265 <desc></desc>
266 </argument>
267 <argument name="ui" type="Object">
268 <desc></desc>
269 </argument>
270 </event>
271
272 </events>
273 <methods>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
274 <method name="abort">
275 <desc>Terminate all running tab ajax requests and animations.</desc>
276 </method>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
277 <method name="add">
278 <desc>String</desc>
279 <argument name="url" type="String">
280 <desc></desc>
281 </argument>
282 <argument name="label" type="String">
283 <desc></desc>
284 </argument>
285 <argument name="index" type="Number" optional="true">
286 <desc></desc>
287 </argument>
288 </method>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
289 <method name="disable">
290 <desc>
291 Disable the tabs widget.
292 </desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
293 </method>
294 <method name="disable">
295 <desc>Disable a tab. The selected tab cannot be disabled. To disable more than one tab at once use: <code>$('#example').tabs("option","disabled", [1, 2, 3]);</code> The second argument is the zero-based index of the tab to be disabled. Instead of an index, the href of the tab may be passed.</desc>
296 <argument name="index" type="Number, String">
297 <desc></desc>
298 </argument>
299 </method>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
300 <method name="enable">
301 <desc>
302 Enable the tabs widget.
303 </desc>
304 </method>
305 <method name="enable">
306 <desc>Enable a disabled tab. To enable more than one tab at once reset the disabled property like: <code>$('#example').tabs("option","disabled",[]);</code>. The second argument is the zero-based index of the tab to be enabled. Instead of an index, the href of the tab may be passed.</desc>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
307 <argument name="index" type="Number, String">
308 <desc></desc>
309 </argument>
310 </method>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
311 <method name="length">
312 <desc>Retrieve the number of tabs of the first matched tab pane.</desc>
313 </method>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
314 <method name="load">
315 <desc>Reload the content of an Ajax tab programmatically. This method always loads the tab content from the remote location, even if cache is set to true. The second argument is the zero-based index of the tab to be reloaded. </desc>
316 <argument name="index" type="Number">
317 <desc></desc>
318 </argument>
319 </method>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
320 <method name="option">
321 <desc>
322 Get or set any tabs widget option. If no value is specified, will act as a getter.
323 </desc>
324 <argument name="optionName" type="String">
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
325 </argument>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
326 <argument name="value" type="Object" optional="true">
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
327 </argument>
328 </method>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
329 <method name="option">
330 <desc>
331 Set multiple tabs widget options at once by providing an options object.
332 </desc>
333 <argument name="options" type="Object">
334 </argument>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
335 </method>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
336 <method name="remove">
337 <desc>Remove a tab. The second argument is the zero-based index of the tab to be removed. Instead of an index, the href of the tab may be passed.</desc>
338 <argument name="index" type="Number, String">
339 <desc></desc>
340 </argument>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
341 </method>
342 <method name="rotate">
343 <desc>Boolean</desc>
344 <argument name="ms" type="Number">
345 <desc></desc>
346 </argument>
347 <argument name="continuing" type="Boolean" optional="true">
348 <desc></desc>
349 </argument>
350 </method>
6b2fe038 » jzaefferer
2012-05-25 Add disable/enable/option/widget methods
351 <method name="select">
352 <desc>Select a tab, as if it were clicked. The second argument is the zero-based index of the tab to be selected or the id selector of the panel the tab is associated with (the tab's href fragment identifier, e.g. hash, points to the panel's id).</desc>
353 <argument name="index" type="Number, String">
354 <desc></desc>
355 </argument>
356 </method>
357 <method name="url">
358 <desc>String</desc>
359 <argument name="index" type="Number">
360 <desc></desc>
361 </argument>
362 <argument name="url" type="String">
363 <desc></desc>
364 </argument>
365 </method>
366 <method name="widget">
367 <desc>
368 Returns the widget
369 </desc>
370 </method>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
371 </methods>
372 <example>
373
374 <desc>A simple jQuery UI Tabs.</desc>
375 <code><![CDATA[$("#tabs").tabs();]]></code>
376 <html><![CDATA[
377 <div id="tabs">
378 <ul>
379 <li><a href="#fragment-1"><span>One</span></a></li>
380 <li><a href="#fragment-2"><span>Two</span></a></li>
381 <li><a href="#fragment-3"><span>Three</span></a></li>
382 </ul>
383 <div id="fragment-1">
384 <p>First tab is active by default:</p>
385 <pre><code>$('#example').tabs();</code></pre
386 </div>
387 <div id="fragment-2">
388 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
389 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
390 </div>
391 <div id="fragment-3">
392 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
393 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
394 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
395 </div>
396 </div>
397 ]]></html>
398
399 </example>
80ecaf46 » rdworth
2012-05-25 Fixed entries2html based on the one in api.jquery.com to put the scri…
400 <category slug="widgets"/>
f1b270b7 » rdworth
2012-05-25 Initial import from jquery-docs repo. New home :)
401 </entry>
Something went wrong with that request. Please try again.