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;
39 // Trigger a custom event to allow callers to hook to the collapsing/expanding,
40 // allowing the module to be testable, and making it possible to
41 // e.g. implement persistence via cookies
42 $collapsible
.trigger( action
=== 'expand' ? 'beforeExpand.mw-collapsible' : 'beforeCollapse.mw-collapsible' );
43 hookCallback = function () {
44 $collapsible
.trigger( action
=== 'expand' ? 'afterExpand.mw-collapsible' : 'afterCollapse.mw-collapsible' );
47 // Handle different kinds of elements
49 if ( !options
.plainMode
&& $collapsible
.is( 'table' ) ) {
51 // If there is a caption, hide all rows; otherwise, only hide body rows
52 if ( $collapsible
.find( '> caption' ).length
) {
53 $containers
= $collapsible
.find( '> * > tr' );
55 $containers
= $collapsible
.find( '> tbody > tr' );
57 if ( $defaultToggle
) {
58 // Exclude table row containing togglelink
59 $containers
= $containers
.not( $defaultToggle
.closest( 'tr' ) );
62 if ( action
=== 'collapse' ) {
63 // Hide all table rows of this table
64 // Slide doesn't work with tables, but fade does as of jQuery 1.1.3
65 // http://stackoverflow.com/questions/467336#920480
66 if ( options
.instantHide
) {
70 $containers
.stop( true, true ).fadeOut().promise().done( hookCallback
);
73 $containers
.stop( true, true ).fadeIn().promise().done( hookCallback
);
76 } else if ( !options
.plainMode
&& ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) ) {
78 $containers
= $collapsible
.find( '> li' );
79 if ( $defaultToggle
) {
80 // Exclude list-item containing togglelink
81 $containers
= $containers
.not( $defaultToggle
.parent() );
84 if ( action
=== 'collapse' ) {
85 if ( options
.instantHide
) {
89 $containers
.stop( true, true ).slideUp().promise().done( hookCallback
);
92 $containers
.stop( true, true ).slideDown().promise().done( hookCallback
);
96 // Everything else: <div>, <p> etc.
97 $collapsibleContent
= $collapsible
.find( '> .mw-collapsible-content' );
99 // If a collapsible-content is defined, act on it
100 if ( !options
.plainMode
&& $collapsibleContent
.length
) {
101 if ( action
=== 'collapse' ) {
102 if ( options
.instantHide
) {
103 $collapsibleContent
.hide();
106 $collapsibleContent
.slideUp().promise().done( hookCallback
);
109 $collapsibleContent
.slideDown().promise().done( hookCallback
);
112 // Otherwise assume this is a customcollapse with a remote toggle
113 // .. and there is no collapsible-content because the entire element should be toggled
115 if ( action
=== 'collapse' ) {
116 if ( options
.instantHide
) {
120 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
121 $collapsible
.fadeOut().promise().done( hookCallback
);
123 $collapsible
.slideUp().promise().done( hookCallback
);
127 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
128 $collapsible
.fadeIn().promise().done( hookCallback
);
130 $collapsible
.slideDown().promise().done( hookCallback
);
138 * Handle clicking/keypressing on the collapsible element toggle and other
139 * situations where a collapsible element is toggled (e.g. the initial
140 * toggle for collapsed ones).
143 * @param {jQuery} $toggle the clickable toggle itself
144 * @param {jQuery} $collapsible the collapsible element
145 * @param {jQuery.Event|null} e either the event or null if unavailable
146 * @param {Object|undefined} options
148 function togglingHandler( $toggle
, $collapsible
, e
, options
) {
149 var wasCollapsed
, $textContainer
, collapseText
, expandText
;
150 options
= options
|| {};
154 e
.type
=== 'click' &&
155 e
.target
.nodeName
.toLowerCase() === 'a' &&
156 $( e
.target
).attr( 'href' )
158 // Don't fire if a link was clicked (for premade togglers)
160 } else if ( e
.type
=== 'keypress' && e
.which
!== 13 && e
.which
!== 32 ) {
161 // Only handle keypresses on the "Enter" or "Space" keys
169 // This allows the element to be hidden on initial toggle without fiddling with the class
170 if ( options
.wasCollapsed
!== undefined ) {
171 wasCollapsed
= options
.wasCollapsed
;
173 wasCollapsed
= $collapsible
.hasClass( 'mw-collapsed' );
176 // Toggle the state of the collapsible element (that is, expand or collapse)
177 $collapsible
.toggleClass( 'mw-collapsed', !wasCollapsed
);
179 // Toggle the mw-collapsible-toggle classes, if requested (for default and premade togglers by default)
180 if ( options
.toggleClasses
) {
182 .toggleClass( 'mw-collapsible-toggle-collapsed', !wasCollapsed
)
183 .toggleClass( 'mw-collapsible-toggle-expanded', wasCollapsed
);
186 // Toggle the text ("Show"/"Hide") within elements tagged with mw-collapsible-text
187 if ( options
.toggleText
) {
188 collapseText
= options
.toggleText
.collapseText
;
189 expandText
= options
.toggleText
.expandText
;
191 $textContainer
= $collapsible
.find( '.mw-collapsible-text' );
192 if ( $textContainer
.length
) {
193 $textContainer
.text( wasCollapsed
? collapseText
: expandText
);
197 // And finally toggle the element state itself
198 toggleElement( $collapsible
, wasCollapsed
? 'expand' : 'collapse', $toggle
, options
);
202 * Enable collapsible-functionality on all elements in the collection.
204 * - Will prevent binding twice to the same element.
205 * - Initial state is expanded by default, this can be overridden by adding class
206 * "mw-collapsed" to the "mw-collapsible" element.
207 * - Elements made collapsible have jQuery data "mw-made-collapsible" set to true.
208 * - The inner content is wrapped in a "div.mw-collapsible-content" (except for tables and lists).
210 * @param {Object} [options]
211 * @param {string} [options.collapseText] Text used for the toggler, when clicking it would
212 * collapse the element. Default: the 'data-collapsetext' attribute of the
213 * collapsible element or the content of 'collapsible-collapse' message.
214 * @param {string} [options.expandText] Text used for the toggler, when clicking it would
215 * expand the element. Default: the 'data-expandtext' attribute of the
216 * collapsible element or the content of 'collapsible-expand' message.
217 * @param {boolean} [options.collapsed] Whether to collapse immediately. By default
218 * collapse only if the elements has the 'mw-collapsible' class.
219 * @param {jQuery} [options.$customTogglers] Elements to be used as togglers
220 * for this collapsible element. By default, if the collapsible element
221 * has an id attribute like 'mw-customcollapsible-XXX', elements with a
222 * *class* of 'mw-customtoggle-XXX' are made togglers for it.
223 * @param {boolean} [options.plainMode=false] Whether to use a "plain mode" when making the
224 * element collapsible - that is, hide entire tables and lists (instead
225 * of hiding only all rows but first of tables, and hiding each list
226 * item separately for lists) and don't wrap other elements in
227 * div.mw-collapsible-content. May only be used with custom togglers.
231 $.fn
.makeCollapsible = function ( options
) {
232 options
= options
|| {};
234 this.each( function () {
235 var $collapsible
, collapseText
, expandText
, $caption
, $toggle
, actionHandler
, buildDefaultToggleLink
,
236 $toggleLink
, $firstItem
, collapsibleId
, $customTogglers
, firstval
;
238 // Ensure class "mw-collapsible" is present in case .makeCollapsible()
239 // is called on element(s) that don't have it yet.
240 $collapsible
= $( this ).addClass( 'mw-collapsible' );
242 // Return if it has been enabled already.
243 if ( $collapsible
.data( 'mw-made-collapsible' ) ) {
246 $collapsible
.data( 'mw-made-collapsible', true );
249 // Use custom text or default?
250 collapseText
= options
.collapseText
|| $collapsible
.attr( 'data-collapsetext' ) || mw
.msg( 'collapsible-collapse' );
251 expandText
= options
.expandText
|| $collapsible
.attr( 'data-expandtext' ) || mw
.msg( 'collapsible-expand' );
253 // Default click/keypress handler and toggle link to use when none is present
254 actionHandler = function ( e
, opts
) {
257 toggleText
: { collapseText
: collapseText
, expandText
: expandText
}
259 opts
= $.extend( defaultOpts
, options
, opts
);
260 togglingHandler( $( this ), $collapsible
, e
, opts
);
263 // Default toggle link. Only build it when needed to avoid jQuery memory leaks (event data).
264 buildDefaultToggleLink = function () {
265 return $( '<span class="mw-collapsible-text"></span>' )
266 .text( collapseText
)
267 .wrap( '<span class="mw-collapsible-toggle"></span>' ).parent()
272 .prepend( '<span>[</span>' )
273 .append( '<span>]</span>' )
274 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
);
277 // Check if this element has a custom position for the toggle link
278 // (ie. outside the container or deeper inside the tree)
279 if ( options
.$customTogglers
) {
280 $customTogglers
= $( options
.$customTogglers
);
282 collapsibleId
= $collapsible
.attr( 'id' ) || '';
283 if ( collapsibleId
.indexOf( 'mw-customcollapsible-' ) === 0 ) {
284 $customTogglers
= $( '.' + collapsibleId
.replace( 'mw-customcollapsible', 'mw-customtoggle' ) )
285 .addClass( 'mw-customtoggle' );
289 // Add event handlers to custom togglers or create our own ones
290 if ( $customTogglers
&& $customTogglers
.length
) {
291 actionHandler = function ( e
, opts
) {
292 var defaultOpts
= {};
293 opts
= $.extend( defaultOpts
, options
, opts
);
294 togglingHandler( $( this ), $collapsible
, e
, opts
);
297 $toggleLink
= $customTogglers
298 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
299 .prop( 'tabIndex', 0 );
302 // If this is not a custom case, do the default: wrap the
303 // contents and add the toggle link. Different elements are
304 // treated differently.
306 if ( $collapsible
.is( 'table' ) ) {
308 // If the table has a caption, collapse to the caption
309 // as opposed to the first row
310 $caption
= $collapsible
.find( '> caption' );
311 if ( $caption
.length
) {
312 $toggle
= $caption
.find( '> .mw-collapsible-toggle' );
314 // If there is no toggle link, add it to the end of the caption
315 if ( !$toggle
.length
) {
316 $toggleLink
= buildDefaultToggleLink().appendTo( $caption
);
318 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
319 .prop( 'tabIndex', 0 );
322 // The toggle-link will be in one of the cells (td or th) of the first row
323 $firstItem
= $collapsible
.find( 'tr:first th, tr:first td' );
324 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
326 // If theres no toggle link, add it to the last cell
327 if ( !$toggle
.length
) {
328 $toggleLink
= buildDefaultToggleLink().prependTo( $firstItem
.eq( -1 ) );
330 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
331 .prop( 'tabIndex', 0 );
335 } else if ( $collapsible
.parent().is( 'li' ) &&
336 $collapsible
.parent().children( '.mw-collapsible' ).length
=== 1 &&
337 $collapsible
.find( '> .mw-collapsible-toggle' ).length
=== 0
339 // special case of one collapsible in <li> tag
340 $toggleLink
= buildDefaultToggleLink();
341 $collapsible
.before( $toggleLink
);
342 } else if ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) {
343 // The toggle-link will be in the first list-item
344 $firstItem
= $collapsible
.find( 'li:first' );
345 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
347 // If theres no toggle link, add it
348 if ( !$toggle
.length
) {
349 // Make sure the numeral order doesn't get messed up, force the first (soon to be second) item
350 // to be "1". Except if the value-attribute is already used.
351 // If no value was set WebKit returns "", Mozilla returns '-1', others return 0, null or undefined.
352 firstval
= $firstItem
.prop( 'value' );
353 if ( firstval
=== undefined || !firstval
|| firstval
=== '-1' || firstval
=== -1 ) {
354 $firstItem
.prop( 'value', '1' );
356 $toggleLink
= buildDefaultToggleLink();
357 $toggleLink
.wrap( '<li class="mw-collapsible-toggle-li"></li>' ).parent().prependTo( $collapsible
);
359 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
360 .prop( 'tabIndex', 0 );
363 } else { // <div>, <p> etc.
365 // The toggle-link will be the first child of the element
366 $toggle
= $collapsible
.find( '> .mw-collapsible-toggle' );
368 // If a direct child .content-wrapper does not exists, create it
369 if ( !$collapsible
.find( '> .mw-collapsible-content' ).length
) {
370 $collapsible
.wrapInner( '<div class="mw-collapsible-content"></div>' );
373 // If theres no toggle link, add it
374 if ( !$toggle
.length
) {
375 $toggleLink
= buildDefaultToggleLink().prependTo( $collapsible
);
377 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
378 .prop( 'tabIndex', 0 );
383 $( this ).data( 'mw-collapsible', {
384 collapse: function () {
385 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
387 expand: function () {
388 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: true } );
390 toggle: function () {
391 actionHandler
.call( $toggleLink
.get( 0 ), null, null );
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 } );
405 * Fired after collapsible content has been initialized
407 * This gives an option to modify the collapsible behavior.
409 * @event wikipage_collapsibleContent
411 * @param {jQuery} $content All the elements that have been made collapsible
413 mw
.hook( 'wikipage.collapsibleContent' ).fire( this );
420 * @mixins jQuery.plugin.makeCollapsible
423 }( jQuery
, mediaWiki
) );