2 * jQuery makeCollapsible
5 * - CC BY 3.0 <http://creativecommons.org/licenses/by/3.0>
6 * - GPL2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
8 * @class jQuery.plugin.makeCollapsible
10 ( function ( $, mw
) {
13 * Handler for a click on a collapsible toggler.
16 * @param {jQuery} $collapsible
17 * @param {string} action The action this function will take ('expand' or 'collapse').
18 * @param {jQuery|null} [$defaultToggle]
19 * @param {Object|undefined} [options]
21 function toggleElement( $collapsible
, action
, $defaultToggle
, options
) {
22 var $collapsibleContent
, $containers
, hookCallback
;
23 options
= options
|| {};
25 // Validate parameters
27 // $collapsible must be an instance of jQuery
28 if ( !$collapsible
.jquery
) {
31 if ( action
!== 'expand' && action
!== 'collapse' ) {
32 // action must be string with 'expand' or 'collapse'
35 if ( $defaultToggle
=== undefined ) {
36 $defaultToggle
= null;
38 if ( $defaultToggle
!== null && !$defaultToggle
.jquery
) {
39 // is optional (may be undefined), but if defined it must be an instance of jQuery.
40 // If it's not, abort right away.
41 // After this $defaultToggle is either null or a valid jQuery instance.
45 // Trigger a custom event to allow callers to hook to the collapsing/expanding,
46 // allowing the module to be testable, and making it possible to
47 // e.g. implement persistence via cookies
48 $collapsible
.trigger( action
=== 'expand' ? 'beforeExpand.mw-collapsible' : 'beforeCollapse.mw-collapsible' );
49 hookCallback = function () {
50 $collapsible
.trigger( action
=== 'expand' ? 'afterExpand.mw-collapsible' : 'afterCollapse.mw-collapsible' );
53 // Handle different kinds of elements
55 if ( !options
.plainMode
&& $collapsible
.is( 'table' ) ) {
57 // If there is a caption, hide all rows; otherwise, only hide body rows
58 if ( $collapsible
.find( '> caption' ).length
) {
59 $containers
= $collapsible
.find( '> * > tr' );
61 $containers
= $collapsible
.find( '> tbody > tr' );
63 if ( $defaultToggle
) {
64 // Exclude table row containing togglelink
65 $containers
= $containers
.not( $defaultToggle
.closest( 'tr' ) );
68 if ( action
=== 'collapse' ) {
69 // Hide all table rows of this table
70 // Slide doesn't work with tables, but fade does as of jQuery 1.1.3
71 // http://stackoverflow.com/questions/467336#920480
72 if ( options
.instantHide
) {
76 $containers
.stop( true, true ).fadeOut().promise().done( hookCallback
);
79 $containers
.stop( true, true ).fadeIn().promise().done( hookCallback
);
82 } else if ( !options
.plainMode
&& ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) ) {
84 $containers
= $collapsible
.find( '> li' );
85 if ( $defaultToggle
) {
86 // Exclude list-item containing togglelink
87 $containers
= $containers
.not( $defaultToggle
.parent() );
90 if ( action
=== 'collapse' ) {
91 if ( options
.instantHide
) {
95 $containers
.stop( true, true ).slideUp().promise().done( hookCallback
);
98 $containers
.stop( true, true ).slideDown().promise().done( hookCallback
);
102 // Everything else: <div>, <p> etc.
103 $collapsibleContent
= $collapsible
.find( '> .mw-collapsible-content' );
105 // If a collapsible-content is defined, act on it
106 if ( !options
.plainMode
&& $collapsibleContent
.length
) {
107 if ( action
=== 'collapse' ) {
108 if ( options
.instantHide
) {
109 $collapsibleContent
.hide();
112 $collapsibleContent
.slideUp().promise().done( hookCallback
);
115 $collapsibleContent
.slideDown().promise().done( hookCallback
);
118 // Otherwise assume this is a customcollapse with a remote toggle
119 // .. and there is no collapsible-content because the entire element should be toggled
121 if ( action
=== 'collapse' ) {
122 if ( options
.instantHide
) {
126 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
127 $collapsible
.fadeOut().promise().done( hookCallback
);
129 $collapsible
.slideUp().promise().done( hookCallback
);
133 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
134 $collapsible
.fadeIn().promise().done( hookCallback
);
136 $collapsible
.slideDown().promise().done( hookCallback
);
144 * Handle clicking/keypressing on the collapsible element toggle and other
145 * situations where a collapsible element is toggled (e.g. the initial
146 * toggle for collapsed ones).
149 * @param {jQuery} $toggle the clickable toggle itself
150 * @param {jQuery} $collapsible the collapsible element
151 * @param {jQuery.Event|null} e either the event or null if unavailable
152 * @param {Object|undefined} options
154 function togglingHandler( $toggle
, $collapsible
, e
, options
) {
155 var wasCollapsed
, $textContainer
, collapseText
, expandText
;
157 if ( options
=== undefined ) {
163 e
.type
=== 'click' &&
164 options
.linksPassthru
&&
165 $.nodeName( e
.target
, 'a' ) &&
166 $( e
.target
).attr( 'href' ) !== '#'
168 // Don't fire if a link with href !== '#' was clicked, if requested (for premade togglers by default)
170 } else if ( e
.type
=== 'keypress' && e
.which
!== 13 && e
.which
!== 32 ) {
171 // Only handle keypresses on the "Enter" or "Space" keys
179 // This allows the element to be hidden on initial toggle without fiddling with the class
180 if ( options
.wasCollapsed
!== undefined ) {
181 wasCollapsed
= options
.wasCollapsed
;
183 wasCollapsed
= $collapsible
.hasClass( 'mw-collapsed' );
186 // Toggle the state of the collapsible element (that is, expand or collapse)
187 $collapsible
.toggleClass( 'mw-collapsed', !wasCollapsed
);
189 // Toggle the mw-collapsible-toggle classes, if requested (for default and premade togglers by default)
190 if ( options
.toggleClasses
) {
192 .toggleClass( 'mw-collapsible-toggle-collapsed', !wasCollapsed
)
193 .toggleClass( 'mw-collapsible-toggle-expanded', wasCollapsed
);
196 // Toggle the text ("Show"/"Hide"), if requested (for default togglers by default)
197 if ( options
.toggleText
) {
198 collapseText
= options
.toggleText
.collapseText
;
199 expandText
= options
.toggleText
.expandText
;
201 $textContainer
= $toggle
.find( '> a' );
202 if ( !$textContainer
.length
) {
203 $textContainer
= $toggle
;
205 $textContainer
.text( wasCollapsed
? collapseText
: expandText
);
208 // And finally toggle the element state itself
209 toggleElement( $collapsible
, wasCollapsed
? 'expand' : 'collapse', $toggle
, options
);
213 * Enable collapsible-functionality on all elements in the collection.
215 * - Will prevent binding twice to the same element.
216 * - Initial state is expanded by default, this can be overridden by adding class
217 * "mw-collapsed" to the "mw-collapsible" element.
218 * - Elements made collapsible have jQuery data "mw-made-collapsible" set to true.
219 * - The inner content is wrapped in a "div.mw-collapsible-content" (except for tables and lists).
221 * @param {Object} [options]
222 * @param {string} [options.collapseText] Text used for the toggler, when clicking it would
223 * collapse the element. Default: the 'data-collapsetext' attribute of the
224 * collapsible element or the content of 'collapsible-collapse' message.
225 * @param {string} [options.expandText] Text used for the toggler, when clicking it would
226 * expand the element. Default: the 'data-expandtext' attribute of the
227 * collapsible element or the content of 'collapsible-expand' message.
228 * @param {boolean} [options.collapsed] Whether to collapse immediately. By default
229 * collapse only if the elements has the 'mw-collapsible' class.
230 * @param {jQuery} [options.$customTogglers] Elements to be used as togglers
231 * for this collapsible element. By default, if the collapsible element
232 * has an id attribute like 'mw-customcollapsible-XXX', elements with a
233 * *class* of 'mw-customtoggle-XXX' are made togglers for it.
234 * @param {boolean} [options.plainMode=false] Whether to use a "plain mode" when making the
235 * element collapsible - that is, hide entire tables and lists (instead
236 * of hiding only all rows but first of tables, and hiding each list
237 * item separately for lists) and don't wrap other elements in
238 * div.mw-collapsible-content. May only be used with custom togglers.
242 $.fn
.makeCollapsible = function ( options
) {
243 if ( options
=== undefined ) {
247 return this.each( function () {
248 var $collapsible
, collapseText
, expandText
, $caption
, $toggle
, actionHandler
, buildDefaultToggleLink
,
249 premadeToggleHandler
, $toggleLink
, $firstItem
, collapsibleId
, $customTogglers
, firstval
;
251 // Ensure class "mw-collapsible" is present in case .makeCollapsible()
252 // is called on element(s) that don't have it yet.
253 $collapsible
= $( this ).addClass( 'mw-collapsible' );
255 // Return if it has been enabled already.
256 if ( $collapsible
.data( 'mw-made-collapsible' ) ) {
259 $collapsible
.data( 'mw-made-collapsible', true );
262 // Use custom text or default?
263 collapseText
= options
.collapseText
|| $collapsible
.attr( 'data-collapsetext' ) || mw
.msg( 'collapsible-collapse' );
264 expandText
= options
.expandText
|| $collapsible
.attr( 'data-expandtext' ) || mw
.msg( 'collapsible-expand' );
266 // Default click/keypress handler and toggle link to use when none is present
267 actionHandler = function ( e
, opts
) {
270 toggleText
: { collapseText
: collapseText
, expandText
: expandText
}
272 opts
= $.extend( defaultOpts
, options
, opts
);
273 togglingHandler( $( this ), $collapsible
, e
, opts
);
275 // Default toggle link. Only build it when needed to avoid jQuery memory leaks (event data).
276 buildDefaultToggleLink = function () {
277 return $( '<a href="#"></a>' )
278 .text( collapseText
)
279 .wrap( '<span class="mw-collapsible-toggle"></span>' )
281 .prepend( '<span class="mw-collapsible-bracket">[</span>' )
282 .append( '<span class="mw-collapsible-bracket">]</span>' )
283 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
);
286 // Default handler for clicking on premade toggles
287 premadeToggleHandler = function ( e
, opts
) {
288 var defaultOpts
= { toggleClasses
: true, linksPassthru
: true };
289 opts
= $.extend( defaultOpts
, options
, opts
);
290 togglingHandler( $( this ), $collapsible
, e
, opts
);
293 // Check if this element has a custom position for the toggle link
294 // (ie. outside the container or deeper inside the tree)
295 if ( options
.$customTogglers
) {
296 $customTogglers
= $( options
.$customTogglers
);
298 collapsibleId
= $collapsible
.attr( 'id' ) || '';
299 if ( collapsibleId
.indexOf( 'mw-customcollapsible-' ) === 0 ) {
300 $customTogglers
= $( '.' + collapsibleId
.replace( 'mw-customcollapsible', 'mw-customtoggle' ) )
301 .addClass( 'mw-customtoggle' );
305 // Add event handlers to custom togglers or create our own ones
306 if ( $customTogglers
&& $customTogglers
.length
) {
307 actionHandler = function ( e
, opts
) {
308 var defaultOpts
= {};
309 opts
= $.extend( defaultOpts
, options
, opts
);
310 togglingHandler( $( this ), $collapsible
, e
, opts
);
313 $toggleLink
= $customTogglers
314 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
315 .prop( 'tabIndex', 0 );
318 // If this is not a custom case, do the default: wrap the
319 // contents and add the toggle link. Different elements are
320 // treated differently.
321 if ( $collapsible
.is( 'table' ) ) {
323 // If the table has a caption, collapse to the caption
324 // as opposed to the first row
325 $caption
= $collapsible
.find( '> caption' );
326 if ( $caption
.length
) {
327 $toggle
= $caption
.find( '> .mw-collapsible-toggle' );
329 // If there is no toggle link, add it to the end of the caption
330 if ( !$toggle
.length
) {
331 $toggleLink
= buildDefaultToggleLink().appendTo( $caption
);
333 actionHandler
= premadeToggleHandler
;
334 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
335 .prop( 'tabIndex', 0 );
338 // The toggle-link will be in one of the cells (td or th) of the first row
339 $firstItem
= $collapsible
.find( 'tr:first th, tr:first td' );
340 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
342 // If theres no toggle link, add it to the last cell
343 if ( !$toggle
.length
) {
344 $toggleLink
= buildDefaultToggleLink().prependTo( $firstItem
.eq( -1 ) );
346 actionHandler
= premadeToggleHandler
;
347 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
348 .prop( 'tabIndex', 0 );
352 } else if ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) {
353 // The toggle-link will be in the first list-item
354 $firstItem
= $collapsible
.find( 'li:first' );
355 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
357 // If theres no toggle link, add it
358 if ( !$toggle
.length
) {
359 // Make sure the numeral order doesn't get messed up, force the first (soon to be second) item
360 // to be "1". Except if the value-attribute is already used.
361 // If no value was set WebKit returns "", Mozilla returns '-1', others return 0, null or undefined.
362 firstval
= $firstItem
.prop( 'value' );
363 if ( firstval
=== undefined || !firstval
|| firstval
=== '-1' || firstval
=== -1 ) {
364 $firstItem
.prop( 'value', '1' );
366 $toggleLink
= buildDefaultToggleLink();
367 $toggleLink
.wrap( '<li class="mw-collapsible-toggle-li"></li>' ).parent().prependTo( $collapsible
);
369 actionHandler
= premadeToggleHandler
;
370 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
371 .prop( 'tabIndex', 0 );
374 } else { // <div>, <p> etc.
376 // The toggle-link will be the first child of the element
377 $toggle
= $collapsible
.find( '> .mw-collapsible-toggle' );
379 // If a direct child .content-wrapper does not exists, create it
380 if ( !$collapsible
.find( '> .mw-collapsible-content' ).length
) {
381 $collapsible
.wrapInner( '<div class="mw-collapsible-content"></div>' );
384 // If theres no toggle link, add it
385 if ( !$toggle
.length
) {
386 $toggleLink
= buildDefaultToggleLink().prependTo( $collapsible
);
388 actionHandler
= premadeToggleHandler
;
389 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
390 .prop( 'tabIndex', 0 );
396 if ( options
.collapsed
|| $collapsible
.hasClass( 'mw-collapsed' ) ) {
397 // One toggler can hook to multiple elements, and one element can have
398 // multiple togglers. This is the sanest way to handle that.
399 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
406 * @mixins jQuery.plugin.makeCollapsible
409 }( jQuery
, mediaWiki
) );