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
) {
12 * Handler for a click on a collapsible toggler.
15 * @param {jQuery} $collapsible
16 * @param {string} action The action this function will take ('expand' or 'collapse').
17 * @param {jQuery|null} [$defaultToggle]
18 * @param {Object|undefined} [options]
20 function toggleElement( $collapsible
, action
, $defaultToggle
, options
) {
21 var $collapsibleContent
, $containers
, hookCallback
;
22 options
= options
|| {};
24 // Validate parameters
26 // $collapsible must be an instance of jQuery
27 if ( !$collapsible
.jquery
) {
30 if ( action
!== 'expand' && action
!== 'collapse' ) {
31 // action must be string with 'expand' or 'collapse'
34 if ( $defaultToggle
=== undefined ) {
35 $defaultToggle
= null;
38 // Trigger a custom event to allow callers to hook to the collapsing/expanding,
39 // allowing the module to be testable, and making it possible to
40 // e.g. implement persistence via cookies
41 $collapsible
.trigger( action
=== 'expand' ? 'beforeExpand.mw-collapsible' : 'beforeCollapse.mw-collapsible' );
42 hookCallback = function () {
43 $collapsible
.trigger( action
=== 'expand' ? 'afterExpand.mw-collapsible' : 'afterCollapse.mw-collapsible' );
46 // Handle different kinds of elements
48 if ( !options
.plainMode
&& $collapsible
.is( 'table' ) ) {
50 // If there is a caption, hide all rows; otherwise, only hide body rows
51 if ( $collapsible
.find( '> caption' ).length
) {
52 $containers
= $collapsible
.find( '> * > tr' );
54 $containers
= $collapsible
.find( '> tbody > tr' );
56 if ( $defaultToggle
) {
57 // Exclude table row containing togglelink
58 $containers
= $containers
.not( $defaultToggle
.closest( 'tr' ) );
61 if ( action
=== 'collapse' ) {
62 // Hide all table rows of this table
63 // Slide doesn't work with tables, but fade does as of jQuery 1.1.3
64 // http://stackoverflow.com/questions/467336#920480
65 if ( options
.instantHide
) {
69 $containers
.stop( true, true ).fadeOut().promise().done( hookCallback
);
72 $containers
.stop( true, true ).fadeIn().promise().done( hookCallback
);
75 } else if ( !options
.plainMode
&& ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) ) {
77 $containers
= $collapsible
.find( '> li' );
78 if ( $defaultToggle
) {
79 // Exclude list-item containing togglelink
80 $containers
= $containers
.not( $defaultToggle
.parent() );
83 if ( action
=== 'collapse' ) {
84 if ( options
.instantHide
) {
88 $containers
.stop( true, true ).slideUp().promise().done( hookCallback
);
91 $containers
.stop( true, true ).slideDown().promise().done( hookCallback
);
95 // Everything else: <div>, <p> etc.
96 $collapsibleContent
= $collapsible
.find( '> .mw-collapsible-content' );
98 // If a collapsible-content is defined, act on it
99 if ( !options
.plainMode
&& $collapsibleContent
.length
) {
100 if ( action
=== 'collapse' ) {
101 if ( options
.instantHide
) {
102 $collapsibleContent
.hide();
105 $collapsibleContent
.slideUp().promise().done( hookCallback
);
108 $collapsibleContent
.slideDown().promise().done( hookCallback
);
111 // Otherwise assume this is a customcollapse with a remote toggle
112 // .. and there is no collapsible-content because the entire element should be toggled
114 if ( action
=== 'collapse' ) {
115 if ( options
.instantHide
) {
119 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
120 $collapsible
.fadeOut().promise().done( hookCallback
);
122 $collapsible
.slideUp().promise().done( hookCallback
);
126 if ( $collapsible
.is( 'tr' ) || $collapsible
.is( 'td' ) || $collapsible
.is( 'th' ) ) {
127 $collapsible
.fadeIn().promise().done( hookCallback
);
129 $collapsible
.slideDown().promise().done( hookCallback
);
137 * Handle clicking/keypressing on the collapsible element toggle and other
138 * situations where a collapsible element is toggled (e.g. the initial
139 * toggle for collapsed ones).
142 * @param {jQuery} $toggle the clickable toggle itself
143 * @param {jQuery} $collapsible the collapsible element
144 * @param {jQuery.Event|null} e either the event or null if unavailable
145 * @param {Object|undefined} options
147 function togglingHandler( $toggle
, $collapsible
, e
, options
) {
148 var wasCollapsed
, $textContainer
, collapseText
, expandText
;
149 options
= options
|| {};
153 e
.type
=== 'click' &&
154 e
.target
.nodeName
.toLowerCase() === 'a' &&
155 $( e
.target
).attr( 'href' )
157 // Don't fire if a link was clicked (for premade togglers)
159 } else if ( e
.type
=== 'keypress' && e
.which
!== 13 && e
.which
!== 32 ) {
160 // Only handle keypresses on the "Enter" or "Space" keys
168 // This allows the element to be hidden on initial toggle without fiddling with the class
169 if ( options
.wasCollapsed
!== undefined ) {
170 wasCollapsed
= options
.wasCollapsed
;
172 wasCollapsed
= $collapsible
.hasClass( 'mw-collapsed' );
175 // Toggle the state of the collapsible element (that is, expand or collapse)
176 $collapsible
.toggleClass( 'mw-collapsed', !wasCollapsed
);
178 // Toggle the mw-collapsible-toggle classes, if requested (for default and premade togglers by default)
179 if ( options
.toggleClasses
) {
181 .toggleClass( 'mw-collapsible-toggle-collapsed', !wasCollapsed
)
182 .toggleClass( 'mw-collapsible-toggle-expanded', wasCollapsed
);
185 // Toggle the text ("Show"/"Hide") within elements tagged with mw-collapsible-text
186 if ( options
.toggleText
) {
187 collapseText
= options
.toggleText
.collapseText
;
188 expandText
= options
.toggleText
.expandText
;
190 $textContainer
= $collapsible
.find( '.mw-collapsible-text' );
191 if ( $textContainer
.length
) {
192 $textContainer
.text( wasCollapsed
? collapseText
: expandText
);
196 // And finally toggle the element state itself
197 toggleElement( $collapsible
, wasCollapsed
? 'expand' : 'collapse', $toggle
, options
);
201 * Enable collapsible-functionality on all elements in the collection.
203 * - Will prevent binding twice to the same element.
204 * - Initial state is expanded by default, this can be overridden by adding class
205 * "mw-collapsed" to the "mw-collapsible" element.
206 * - Elements made collapsible have jQuery data "mw-made-collapsible" set to true.
207 * - The inner content is wrapped in a "div.mw-collapsible-content" (except for tables and lists).
209 * @param {Object} [options]
210 * @param {string} [options.collapseText] Text used for the toggler, when clicking it would
211 * collapse the element. Default: the 'data-collapsetext' attribute of the
212 * collapsible element or the content of 'collapsible-collapse' message.
213 * @param {string} [options.expandText] Text used for the toggler, when clicking it would
214 * expand the element. Default: the 'data-expandtext' attribute of the
215 * collapsible element or the content of 'collapsible-expand' message.
216 * @param {boolean} [options.collapsed] Whether to collapse immediately. By default
217 * collapse only if the elements has the 'mw-collapsible' class.
218 * @param {jQuery} [options.$customTogglers] Elements to be used as togglers
219 * for this collapsible element. By default, if the collapsible element
220 * has an id attribute like 'mw-customcollapsible-XXX', elements with a
221 * *class* of 'mw-customtoggle-XXX' are made togglers for it.
222 * @param {boolean} [options.plainMode=false] Whether to use a "plain mode" when making the
223 * element collapsible - that is, hide entire tables and lists (instead
224 * of hiding only all rows but first of tables, and hiding each list
225 * item separately for lists) and don't wrap other elements in
226 * div.mw-collapsible-content. May only be used with custom togglers.
230 $.fn
.makeCollapsible = function ( options
) {
231 options
= options
|| {};
233 this.each( function () {
234 var $collapsible
, collapseText
, expandText
, $caption
, $toggle
, actionHandler
, buildDefaultToggleLink
,
235 $toggleLink
, $firstItem
, collapsibleId
, $customTogglers
, firstval
;
237 // Ensure class "mw-collapsible" is present in case .makeCollapsible()
238 // is called on element(s) that don't have it yet.
239 $collapsible
= $( this ).addClass( 'mw-collapsible' );
241 // Return if it has been enabled already.
242 if ( $collapsible
.data( 'mw-made-collapsible' ) ) {
245 $collapsible
.data( 'mw-made-collapsible', true );
248 // Use custom text or default?
249 collapseText
= options
.collapseText
|| $collapsible
.attr( 'data-collapsetext' ) || mw
.msg( 'collapsible-collapse' );
250 expandText
= options
.expandText
|| $collapsible
.attr( 'data-expandtext' ) || mw
.msg( 'collapsible-expand' );
252 // Default click/keypress handler and toggle link to use when none is present
253 actionHandler = function ( e
, opts
) {
256 toggleText
: { collapseText
: collapseText
, expandText
: expandText
}
258 opts
= $.extend( defaultOpts
, options
, opts
);
259 togglingHandler( $( this ), $collapsible
, e
, opts
);
262 // Default toggle link. Only build it when needed to avoid jQuery memory leaks (event data).
263 buildDefaultToggleLink = function () {
264 return $( '<a class="mw-collapsible-text"></a>' )
265 .text( collapseText
)
266 .wrap( '<span class="mw-collapsible-toggle"></span>' )
272 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
);
275 // Check if this element has a custom position for the toggle link
276 // (ie. outside the container or deeper inside the tree)
277 if ( options
.$customTogglers
) {
278 $customTogglers
= $( options
.$customTogglers
);
280 collapsibleId
= $collapsible
.attr( 'id' ) || '';
281 if ( collapsibleId
.indexOf( 'mw-customcollapsible-' ) === 0 ) {
282 $customTogglers
= $( '.' + collapsibleId
.replace( 'mw-customcollapsible', 'mw-customtoggle' ) )
283 .addClass( 'mw-customtoggle' );
287 // Add event handlers to custom togglers or create our own ones
288 if ( $customTogglers
&& $customTogglers
.length
) {
289 actionHandler = function ( e
, opts
) {
290 var defaultOpts
= {};
291 opts
= $.extend( defaultOpts
, options
, opts
);
292 togglingHandler( $( this ), $collapsible
, e
, opts
);
295 $toggleLink
= $customTogglers
296 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
297 .prop( 'tabIndex', 0 );
300 // If this is not a custom case, do the default: wrap the
301 // contents and add the toggle link. Different elements are
302 // treated differently.
304 if ( $collapsible
.is( 'table' ) ) {
306 // If the table has a caption, collapse to the caption
307 // as opposed to the first row
308 $caption
= $collapsible
.find( '> caption' );
309 if ( $caption
.length
) {
310 $toggle
= $caption
.find( '> .mw-collapsible-toggle' );
312 // If there is no toggle link, add it to the end of the caption
313 if ( !$toggle
.length
) {
314 $toggleLink
= buildDefaultToggleLink().appendTo( $caption
);
316 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
317 .prop( 'tabIndex', 0 );
320 // The toggle-link will be in one of the cells (td or th) of the first row
321 $firstItem
= $collapsible
.find( 'tr:first th, tr:first td' );
322 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
324 // If theres no toggle link, add it to the last cell
325 if ( !$toggle
.length
) {
326 $toggleLink
= buildDefaultToggleLink().prependTo( $firstItem
.eq( -1 ) );
328 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
329 .prop( 'tabIndex', 0 );
333 } else if ( $collapsible
.parent().is( 'li' ) &&
334 $collapsible
.parent().children( '.mw-collapsible' ).length
=== 1 &&
335 $collapsible
.find( '> .mw-collapsible-toggle' ).length
=== 0
337 // special case of one collapsible in <li> tag
338 $toggleLink
= buildDefaultToggleLink();
339 $collapsible
.before( $toggleLink
);
340 } else if ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) {
341 // The toggle-link will be in the first list-item
342 $firstItem
= $collapsible
.find( 'li:first' );
343 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
345 // If theres no toggle link, add it
346 if ( !$toggle
.length
) {
347 // Make sure the numeral order doesn't get messed up, force the first (soon to be second) item
348 // to be "1". Except if the value-attribute is already used.
349 // If no value was set WebKit returns "", Mozilla returns '-1', others return 0, null or undefined.
350 firstval
= $firstItem
.prop( 'value' );
351 if ( firstval
=== undefined || !firstval
|| firstval
=== '-1' || firstval
=== -1 ) {
352 $firstItem
.prop( 'value', '1' );
354 $toggleLink
= buildDefaultToggleLink();
355 $toggleLink
.wrap( '<li class="mw-collapsible-toggle-li"></li>' ).parent().prependTo( $collapsible
);
357 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
358 .prop( 'tabIndex', 0 );
361 } else { // <div>, <p> etc.
363 // The toggle-link will be the first child of the element
364 $toggle
= $collapsible
.find( '> .mw-collapsible-toggle' );
366 // If a direct child .content-wrapper does not exists, create it
367 if ( !$collapsible
.find( '> .mw-collapsible-content' ).length
) {
368 $collapsible
.wrapInner( '<div class="mw-collapsible-content"></div>' );
371 // If theres no toggle link, add it
372 if ( !$toggle
.length
) {
373 $toggleLink
= buildDefaultToggleLink().prependTo( $collapsible
);
375 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
376 .prop( 'tabIndex', 0 );
381 $( this ).data( 'mw-collapsible', {
382 collapse: function () {
383 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
385 expand: function () {
386 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: true } );
388 toggle: function () {
389 actionHandler
.call( $toggleLink
.get( 0 ), null, null );
394 if ( options
.collapsed
|| $collapsible
.hasClass( 'mw-collapsed' ) ) {
395 // One toggler can hook to multiple elements, and one element can have
396 // multiple togglers. This is the sanest way to handle that.
397 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
403 * Fired after collapsible content has been initialized
405 * This gives an option to modify the collapsible behavior.
407 * @event wikipage_collapsibleContent
409 * @param {jQuery} $content All the elements that have been made collapsible
411 mw
.hook( 'wikipage.collapsibleContent' ).fire( this );
418 * @mixins jQuery.plugin.makeCollapsible
421 }( jQuery
, mediaWiki
) );