aa76d6dfbbe5e0f74e82b20f0c46c7001e5ebbab
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 $( '<a class="mw-collapsible-text"></a>' )
266 .text( collapseText
)
267 .wrap( '<span class="mw-collapsible-toggle"></span>' )
273 .prepend( '<span>[</span>' )
274 .append( '<span>]</span>' )
275 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
);
278 // Check if this element has a custom position for the toggle link
279 // (ie. outside the container or deeper inside the tree)
280 if ( options
.$customTogglers
) {
281 $customTogglers
= $( options
.$customTogglers
);
283 collapsibleId
= $collapsible
.attr( 'id' ) || '';
284 if ( collapsibleId
.indexOf( 'mw-customcollapsible-' ) === 0 ) {
285 $customTogglers
= $( '.' + collapsibleId
.replace( 'mw-customcollapsible', 'mw-customtoggle' ) )
286 .addClass( 'mw-customtoggle' );
290 // Add event handlers to custom togglers or create our own ones
291 if ( $customTogglers
&& $customTogglers
.length
) {
292 actionHandler = function ( e
, opts
) {
293 var defaultOpts
= {};
294 opts
= $.extend( defaultOpts
, options
, opts
);
295 togglingHandler( $( this ), $collapsible
, e
, opts
);
298 $toggleLink
= $customTogglers
299 .on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
300 .prop( 'tabIndex', 0 );
303 // If this is not a custom case, do the default: wrap the
304 // contents and add the toggle link. Different elements are
305 // treated differently.
307 if ( $collapsible
.is( 'table' ) ) {
309 // If the table has a caption, collapse to the caption
310 // as opposed to the first row
311 $caption
= $collapsible
.find( '> caption' );
312 if ( $caption
.length
) {
313 $toggle
= $caption
.find( '> .mw-collapsible-toggle' );
315 // If there is no toggle link, add it to the end of the caption
316 if ( !$toggle
.length
) {
317 $toggleLink
= buildDefaultToggleLink().appendTo( $caption
);
319 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
320 .prop( 'tabIndex', 0 );
323 // The toggle-link will be in one of the cells (td or th) of the first row
324 $firstItem
= $collapsible
.find( 'tr:first th, tr:first td' );
325 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
327 // If theres no toggle link, add it to the last cell
328 if ( !$toggle
.length
) {
329 $toggleLink
= buildDefaultToggleLink().prependTo( $firstItem
.eq( -1 ) );
331 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
332 .prop( 'tabIndex', 0 );
336 } else if ( $collapsible
.parent().is( 'li' ) &&
337 $collapsible
.parent().children( '.mw-collapsible' ).length
=== 1 &&
338 $collapsible
.find( '> .mw-collapsible-toggle' ).length
=== 0
340 // special case of one collapsible in <li> tag
341 $toggleLink
= buildDefaultToggleLink();
342 $collapsible
.before( $toggleLink
);
343 } else if ( $collapsible
.is( 'ul' ) || $collapsible
.is( 'ol' ) ) {
344 // The toggle-link will be in the first list-item
345 $firstItem
= $collapsible
.find( 'li:first' );
346 $toggle
= $firstItem
.find( '> .mw-collapsible-toggle' );
348 // If theres no toggle link, add it
349 if ( !$toggle
.length
) {
350 // Make sure the numeral order doesn't get messed up, force the first (soon to be second) item
351 // to be "1". Except if the value-attribute is already used.
352 // If no value was set WebKit returns "", Mozilla returns '-1', others return 0, null or undefined.
353 firstval
= $firstItem
.prop( 'value' );
354 if ( firstval
=== undefined || !firstval
|| firstval
=== '-1' || firstval
=== -1 ) {
355 $firstItem
.prop( 'value', '1' );
357 $toggleLink
= buildDefaultToggleLink();
358 $toggleLink
.wrap( '<li class="mw-collapsible-toggle-li"></li>' ).parent().prependTo( $collapsible
);
360 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
361 .prop( 'tabIndex', 0 );
364 } else { // <div>, <p> etc.
366 // The toggle-link will be the first child of the element
367 $toggle
= $collapsible
.find( '> .mw-collapsible-toggle' );
369 // If a direct child .content-wrapper does not exists, create it
370 if ( !$collapsible
.find( '> .mw-collapsible-content' ).length
) {
371 $collapsible
.wrapInner( '<div class="mw-collapsible-content"></div>' );
374 // If theres no toggle link, add it
375 if ( !$toggle
.length
) {
376 $toggleLink
= buildDefaultToggleLink().prependTo( $collapsible
);
378 $toggleLink
= $toggle
.on( 'click.mw-collapsible keypress.mw-collapsible', actionHandler
)
379 .prop( 'tabIndex', 0 );
384 $( this ).data( 'mw-collapsible', {
385 collapse: function () {
386 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
388 expand: function () {
389 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: true } );
391 toggle: function () {
392 actionHandler
.call( $toggleLink
.get( 0 ), null, null );
397 if ( options
.collapsed
|| $collapsible
.hasClass( 'mw-collapsed' ) ) {
398 // One toggler can hook to multiple elements, and one element can have
399 // multiple togglers. This is the sanest way to handle that.
400 actionHandler
.call( $toggleLink
.get( 0 ), null, { instantHide
: true, wasCollapsed
: false } );
406 * Fired after collapsible content has been initialized
408 * This gives an option to modify the collapsible behavior.
410 * @event wikipage_collapsibleContent
412 * @param {jQuery} $content All the elements that have been made collapsible
414 mw
.hook( 'wikipage.collapsibleContent' ).fire( this );
421 * @mixins jQuery.plugin.makeCollapsible
424 }( jQuery
, mediaWiki
) );