Controlgroup Widget

Categories: Widgets

Controlgroup Widgetversion added: 1.3

Description: Groups buttons together.

QuickNavExamples

Options

Methods

Events

Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute — the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.

1
2
3
4
5
 
<div data-role="controlgroup">
  <a href="#" data-role="button">Yes</a>
  <a href="#" data-role="button">No</a>
  <a href="#" data-role="button">Maybe</a>
</div>

This will result in the following button group:

By adding the data-type="horizontal" attribute to the controlgroup container, you can swap to a horizontal-style group that floats the buttons side-by-side and sets the width to only be large enough to fit the content. (Be aware that these will wrap to multiple lines if the number of buttons or the overall text length is too wide for the screen.)

Horizontal grouped buttons:

Labels

If you use a controlgroup for input, button or select buttons we recommend wrapping them in a fieldset element that has a legend which acts as the combined label for the group. The label elements of each individual button in the group will be hidden for styling purposes, and are only accessible by screen readers. Using the label as a wrapper around the form element prevents the framework from hiding it, so you have to use the for attribute to associate the label with the input.

Options

corners 

Type: Boolean
Default: true

Sets whether to draw the controlgroup with rounded corners.

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

Code examples:

Initialize the controlgroup with the corners option specified:

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

Get or set the corners option, after initialization:

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

excludeInvisible 

Type: Boolean
Default: true

Sets whether to exclude invisible children in the assignment of rounded corners.

When set to false, all children of a controlgroup are taken into account when assigning rounded corners, including hidden children. Thus, if, for example, the controlgroup's first child is hidden, the controlgroup will, in effect, not have rounded corners on the top edge.

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

Code examples:

Initialize the controlgroup with the excludeInvisible option specified:

1
2
3
 
$( ".selector" ).controlgroup({
  excludeInvisible: false
});

Get or set the excludeInvisible option, after initialization:

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

initSelector 

Type: jQuery selector string
Default: ":jqmData(role='controlgroup')"

This is used to define the selectors (element types, data roles, etc.) that will automatically be initialized as controlgroups. To change which elements are initialized, bind this option to the mobileinit event:

1
2
3
 
$( document ).on( "mobileinit", function() {
  $.mobile.controlgroup.prototype.options.initSelector = ".mycontrolgroup";
});

mini 

Type: Boolean
Default: false

If set to true, this will display a more compact version of the controlgroup that uses less vertical space. Possible values: true, false.

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

Code examples:

Initialize the controlgroup with the mini option specified:

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

Get or set the mini option, after initialization:

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

shadow 

Type: Boolean
Default: false

Sets whether a drop shadow is drawn around the controlgroup.

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

Code examples:

Initialize the controlgroup with the shadow option specified:

1
2
3
 
$( ".selector" ).controlgroup({
  shadow: true
});

Get or set the shadow option, after initialization:

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

type 

Type: String
Default: vertical

Sets whether children should be stacked on top of each other or next to each other. If set to "horizontal", the children of the controlgroup will be stacked next to each other.

This option is also exposed as a data attribute: data-type="horizontal".

Code examples:

Initialize the controlgroup with the type option specified:

1
2
3
 
$( ".selector" ).controlgroup({
  type: "horizontal"
});

Get or set the type option, after initialization:

1
2
3
4
5
 
// Getter
var type = $( ".selector" ).controlgroup( "option", "type" );
 
// Setter
$( ".selector" ).controlgroup( "option", "type", "horizontal" );

Methods

container()Returns: jQuery (plugin only)

Obtain the container element within which the controlgroup's child elements are to be placed.
1
 
$( ".selector" ).controlgroup( "container" );
  • This method does not accept any arguments.
Code examples:

Invoke the container method:

1
 
$( ".selector" ).controlgroup( "container" );

Events

create( event, ui )Type: controlgroupcreate

Triggered when a controlgroup is created.

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

Code examples:

Initialize the controlgroup with the create callback specified:

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

Bind an event listener to the controlgroupcreate event:

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

Example:

A basic example of a controlgroup.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>controlgroup demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.css">
  <script src="//code.jquery.com/jquery-1.9.1.min.js"></script>
  <script src="//code.jquery.com/mobile/1.3.2/jquery.mobile-1.3.2.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="content">
    <div data-role="controlgroup">
      <a href="#" data-role="button">Yes</a>
      <a href="#" data-role="button">No</a>
      <a href="#" data-role="button">Maybe</a>
    </div>
  </div>
</div>
 
</body>
</html>

Demo: