Collapsibleset Widget

Categories: Widgets

Collapsibleset Widgetversion added: 1.0

Description: Creates a set of collapsible blocks of content

QuickNavExamples

Options

Methods

Events

Sets of collapsibles

jQuery Mobile will visually style a set of collapsibles as a group and will make the set behave like an accordion in that only one collapsible can be open at a time if you wrap the collapsibles in a div that has the attribute data-role="collapsibleset".

By default, all the collapsible sections will be collapsed. To set a section to be open when the page loads, add the data-collapsed="false" attribute to the heading of the section you want expanded.

1
2
3
4
5
6
7
8
9
10
11
12
13
 
<div data-role="collapsible-set">
 
  <div data-role="collapsible" data-collapsed="false">
    <h3>Section 1</h3>
    <p>I'm the collapsibleset content for section 1. My content is initially visible.</p>
  </div>
 
  <div data-role="collapsible">
    <h3>Section 2</h3>
    <p>I'm the collapsibleset content for section 2.</p>
  </div>
 
</div>

Here is an example of a collapsibleset widget with 5 sections.

Non-inset collapsibleset widgets

For full width collapsibles without corner styling add the data-inset="false" attribute to the set.

Mini collapsibleset widgets

For a more compact version that is useful in tight spaces, add the data-mini="true" attribute to the set to create a mini version.

Custom icons

The icon displayed when a collapsible is shown or hidden can be overridden by using the data-collapsed-icon and data-expanded-icon attributes. Both the collapsibleset widget and the collapsible widget accepts these attributes. When you set one or both of these attributes on the collapsibleset widget all collapsible widgets that are part of the collapsibleset display the icon specified by the chosen value. You can override the icon displayed by individual collapsible widgets by setting one or both of these attributes on the collapsible widget itself.

Icon positioning

The default icon positioning for collapsible headings can be overridden by using the data-iconpos attribute. You can set the attribute either on the collapsibleset to affect all collapsibles in the set, or on an individual collapsible widget to affect only the one widget.

Theming collapsible content

The standard data-theme attribute can be used to set the color of each collapsible in a set. To provide a clearer visual grouping of the content with the headers, add the data-content-theme attribute with a swatch letter. This adds a themed background color and border to the content block. For consistent theming, add these attributes to the parent collapsibleset widget.

1
 
<div data-role="collapsible-set" data-theme="b" data-content-theme="a">

Theming individual sections

To have individual sections in a group styled differently, add data-theme and data-content-theme attributes to specific collapsibles.

Providing pre-rendered markup

You can improve the load time of your page by providing the markup that the collapsibleset widget would normally create during its initialization.

By providing this markup yourself, and by indicating that you have done so by setting the attribute data-enhanced="true", you instruct the collapsibleset widget to skip these DOM manipulations during instantiation and to assume that the required DOM structure is already present.

When you provide such pre-rendered markup you must also set all the classes that the framework would normally set, and you must also set all data attributes whose values differ from the default to indicate that the pre-rendered markup reflects the non-default value of the corresponding widget option.

The collapsibleset widget does not require that the collapsibles it contains also be pre-rendered.

In the example below, pre-rendered markup for a collapsibleset is provided. The attribute data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the container element indicates that the "corners" widget option is to be false. One of the child collapsibles is provided as-is, while the other is pre-rendered.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
<div data-role="collapsibleset" class="ui-collapsible-set" data-corners="false">
  <div data-role="collapsible">
    <h2>Child collapsible</h2>
    <p>This is the collapsible content.</p>
  </div>
  <div data-role="collapsible" data-enhanced="true" class="ui-collapsible ui-collapsible-inset ui-corner-all" data-collapsed="false" data-corners="true">
    <h2 class="ui-collapsible-heading">
      <a href="#" class="ui-collapsible-heading-toggle ui-btn ui-btn-icon-left ui-icon-minus">
        Pre-rendered child collapsible
        <span class="ui-collapsible-heading-status">click to collapse contents</span>
      </a>
    </h2>
    <div class="ui-collapsible-content" aria-hidden="false">
      <p>This is the collapsible content.</p>
    </div>
  </div>
</div>

Options

collapsedIcon 

Type: String
Default: "plus"
Sets the icon for the headers of the collapsible containers when in a collapsed state.

This option is also exposed as a data attribute: data-collapsed-icon="arrow-r".

Code examples:

Initialize the collapsibleset with the collapsedIcon option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  collapsedIcon: "arrow-r"
});

Get or set the collapsedIcon option, after initialization:

1
2
3
4
5
 
// Getter
var collapsedIcon = $( ".selector" ).collapsibleset( "option", "collapsedIcon" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "collapsedIcon", "arrow-r" );

corners 

Type: Boolean
Default: true
Applies the theme border-radius to the first and last collapsible if set to true.

This option is also exposed as a data attribute:data-corners="false".

Code examples:

Initialize the collapsibleset with the corners option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  corners: false
});

Get or set the corners option, after initialization:

1
2
3
4
5
 
// Getter
var corners = $( ".selector" ).collapsibleset( "option", "corners" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "corners", false );

defaults 

Type: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the collapsibleset with the defaults option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  defaults: true
});

Get or set the defaults option, after initialization:

1
2
3
4
5
 
// Getter
var defaults = $( ".selector" ).collapsibleset( "option", "defaults" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "defaults", true );

disabled 

Type: Boolean
Default: false
Disables the collapsibleset if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the collapsibleset with the disabled option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).collapsibleset( "option", "disabled" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "disabled", true );

enhanced 

Type: Boolean
Default: false
Indicates that the markup necessary for a collapsibleset widget has been provided as part of the original markup.

This option is also exposed as a data attribute: data-enhanced="true".

Code examples:

Initialize the collapsibleset with the enhanced option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  enhanced: true
});

Get or set the enhanced option, after initialization:

1
2
3
4
5
 
// Getter
var enhanced = $( ".selector" ).collapsibleset( "option", "enhanced" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "enhanced", true );

expandedIcon 

Type: String
Default: "minus"
Sets the icon for the header of the collapsible container when in an expanded state.

This option is also exposed as a data attribute: data-expanded-icon="arrow-d".

Code examples:

Initialize the collapsibleset with the expandedIcon option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  expandedIcon: "arrow-d"
});

Get or set the expandedIcon option, after initialization:

1
2
3
4
5
 
// Getter
var expandedIcon = $( ".selector" ).collapsibleset( "option", "expandedIcon" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "expandedIcon", "arrow-d" );

iconpos 

Type: String
Default: "left"
Positions the icon in the collapsible headers.

Possible values: left, right, top, bottom, none, notext.

This option is also exposed as a data attribute: data-iconpos="right".

Code examples:

Initialize the collapsibleset with the iconpos option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  iconpos: right
});

Get or set the iconpos option, after initialization:

1
2
3
4
5
 
// Getter
var iconpos = $( ".selector" ).collapsibleset( "option", "iconpos" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "iconpos", right );

initSelector 

Type: String
Default: null

The default initSelector for the collapsibleset widget is:

1
 
":jqmData(role='collapsibleset')"

This option is deprecated in 1.4.0 and will be removed in 1.5.0.

The old value of the collapsibleset widget's initSelector option (":jqmData(role='collapsible-set')") is deprecated. As of jQuery Mobile 1.5.0, only widgets that have the attribute data-role="collapsibleset" will be enhanced as collapsibleset widgets.

As of jQuery Mobile 1.4.0, the initSelector is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit event and overwriting the initSelector on the prototype:

1
2
3
 
$( document ).on( "mobileinit", function() {
  $.mobile.collapsibleset.prototype.initSelector = "div.custom";
});

Note: Remember to attach the mobileinit handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.

The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates collapsibleset widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

initSelector 

Type: Selector
Default: See below

The default initSelector for the collapsibleset widget is:

1
 
":jqmData(role='collapsibleset')"

Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit event and overwriting the initSelector on the prototype:

1
2
3
 
$( document ).on( "mobileinit", function() {
  $.mobile.collapsibleset.prototype.initSelector = "div.custom";
});

Note: Remember to attach the mobileinit handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.

The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates collapsibleset widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

inset 

Type: Boolean
Default: true
By setting this option to false the collapsibles will get a full width appearance without corners. If the value is false for an individual collapsible container, but that container is part of a collapsibleset widget, then the value is inherited from the parent collapsibleset widget.

This option is also exposed as a data attribute: data-inset="true".

Code examples:

Initialize the collapsibleset with the inset option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  inset: false
});

Get or set the inset option, after initialization:

1
2
3
4
5
 
// Getter
var inset = $( ".selector" ).collapsibleset( "option", "inset" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "inset", false );

mini 

Type: Boolean
Default: false
Sets the size of the element to a more compact, mini version. If the value is false for an individual collapsible container, but that container is part of a collapsibleset widget, then the value is inherited from the parent collapsibleset widget.

This option is also exposed as a data attribute: data-mini="false".

Code examples:

Initialize the collapsibleset with the mini option specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  mini: true
});

Get or set the mini option, after initialization:

1
2
3
4
5
 
// Getter
var mini = $( ".selector" ).collapsibleset( "option", "mini" );
 
// Setter
$( ".selector" ).collapsibleset( "option", "mini", true );

Methods

destroy()Returns: jQuery (plugin only)

Removes the collapsibleset functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).collapsibleset( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the collapsibleset.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
 
$( ".selector" ).collapsibleset( "disable" );

enable()Returns: jQuery (plugin only)

Enables the collapsibleset.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
 
$( ".selector" ).collapsibleset( "enable" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
var isDisabled = $( ".selector" ).collapsibleset( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current collapsibleset options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
var options = $( ".selector" ).collapsibleset( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the collapsibleset option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).collapsibleset( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the collapsibleset.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
 
$( ".selector" ).collapsibleset( "option", { disabled: true } );

refresh()Returns: jQuery (plugin only)

Updates the collapsibleset widget.

If you manipulate a collapsibleset widget via JavaScript (e.g. by adding new collapsibles, removing old ones, or showing/hiding existing ones), you must call the refresh method on it to update the visual styling. This method will instantiate collapsibles on child elements which are marked data-role="collapsible", so there is no need to manually call .collapsible().

  • This method does not accept any arguments.
Code examples:

Invoke the refresh method:

1
 
$( ".selector" ).collapsibleset( "refresh" );

Events

create( event, ui )Type: collapsiblesetcreate

Triggered when the collapsibleset is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the collapsibleset with the create callback specified:

1
2
3
 
$( ".selector" ).collapsibleset({
  create: function( event, ui ) {}
});

Bind an event listener to the collapsiblesetcreate event:

1
 
$( ".selector" ).on( "collapsiblesetcreate", function( event, ui ) {} );

Example:

A basic example of a collapsibleset widget.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>collapsibleset demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.css">
  <script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
  <script src="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="header">
    <h1>jQuery Mobile Example</h1>
  </div>
  <div role="main" class="ui-content">
    <div data-role="collapsibleset">
      <div data-role="collapsible" data-collapsed="false">
        <h3>Section A</h3>
        <p>I'm the collapsibleset content for section A.</p>
      </div>
      <div data-role="collapsible">
        <h3>Section B</h3>
        <p>I'm the collapsibleset content for section B.</p>
      </div>
    </div>
  </div>
</div>
 
</body>
</html>

Demo: