Controlgroup Widgetversion added: 1.3
Description: Groups buttons together.
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.
<div data-role="controlgroup"> <a href="#" class="ui-btn ui-corner-all">Yes</a> <a href="#" class="ui-btn ui-corner-all">No</a> <a href="#" class="ui-btn ui-corner-all">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
true
Sets whether to draw the controlgroup with rounded corners.
This option is also exposed as a data attribute: data-corners="false"
.
Initialize the controlgroup with the corners
option specified:
$( ".selector" ).controlgroup({ corners: false });
Get or set the corners
option, after initialization:
// Getter var corners = $( ".selector" ).controlgroup( "option", "corners" ); // Setter $( ".selector" ).controlgroup( "option", "corners", false );
defaults
false
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"
.
Initialize the controlgroup with the defaults
option specified:
$( ".selector" ).controlgroup({ defaults: true });
Get or set the defaults
option, after initialization:
// Getter var defaults = $( ".selector" ).controlgroup( "option", "defaults" ); // Setter $( ".selector" ).controlgroup( "option", "defaults", true );
disabled
false
true
. This option is also exposed as a data attribute: data-disabled="true"
.
Initialize the controlgroup with the disabled
option specified:
$( ".selector" ).controlgroup({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).controlgroup( "option", "disabled" ); // Setter $( ".selector" ).controlgroup( "option", "disabled", true );
excludeInvisible
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"
.
Initialize the controlgroup with the excludeInvisible
option specified:
$( ".selector" ).controlgroup({ excludeInvisible: false });
Get or set the excludeInvisible
option, after initialization:
// Getter var excludeInvisible = $( ".selector" ).controlgroup( "option", "excludeInvisible" ); // Setter $( ".selector" ).controlgroup( "option", "excludeInvisible", false );
initSelector
See below
The default initSelector
for the controlgroup widget is:
":jqmData(role='controlgroup')"
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:
$( document ).on( "mobileinit", function() { $.mobile.controlgroup.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 controlgroup widgets on each of the resulting list of elements.
(version deprecated: 1.4.0)mini
null (false)
true
, this will display a more compact version of the controlgroup that uses less vertical height by applying the ui-mini
class to the outermost element of the controlgroup widget. This option is also exposed as a data attribute: data-mini="true"
.
shadow
false
Sets whether a drop shadow is drawn around the controlgroup.
This option is also exposed as a data attribute: data-shadow="false"
.
Initialize the controlgroup with the shadow
option specified:
$( ".selector" ).controlgroup({ shadow: true });
Get or set the shadow
option, after initialization:
// Getter var shadow = $( ".selector" ).controlgroup( "option", "shadow" ); // Setter $( ".selector" ).controlgroup( "option", "shadow", true );
theme
null, inherited from parent
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Initialize the controlgroup with the theme
option specified:
$( ".selector" ).controlgroup({ theme: "b" });
Get or set the theme
option, after initialization:
// Getter var theme = $( ".selector" ).controlgroup( "option", "theme" ); // Setter $( ".selector" ).controlgroup( "option", "theme", "b" );
type
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"
.
Initialize the controlgroup with the type
option specified:
$( ".selector" ).controlgroup({ type: "horizontal" });
Get or set the type
option, after initialization:
// Getter var type = $( ".selector" ).controlgroup( "option", "type" ); // Setter $( ".selector" ).controlgroup( "option", "type", "horizontal" );
Methods
container()Returns: jQuery (plugin only)
$( ".selector" ).controlgroup( "container" );
- This method does not accept any arguments.
Invoke the container method:
$( ".selector" ).controlgroup( "container" );
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).controlgroup( "destroy" );
disable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).controlgroup( "disable" );
enable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).controlgroup( "enable" );
option( optionName )Returns: Object
optionName
.- optionNameType: StringThe name of the option to get.
Invoke the method:
var isDisabled = $( ".selector" ).controlgroup( "option", "disabled" );
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).controlgroup( "option" );
option( optionName, value )Returns: jQuery (plugin only)
optionName
.- optionNameType: StringThe name of the option to set.
- valueType: ObjectA value to set for the option.
Invoke the method:
$( ".selector" ).controlgroup( "option", "disabled", true );
option( options )Returns: jQuery (plugin only)
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).controlgroup( "option", { disabled: true } );
Events
create( event, ui )Type: controlgroupcreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the controlgroup with the create callback specified:
$( ".selector" ).controlgroup({ create: function( event, ui ) {} });
Bind an event listener to the controlgroupcreate event:
$( ".selector" ).on( "controlgroupcreate", function( event, ui ) {} );
Example:
A basic example of a controlgroup.
<!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.4.5/jquery.mobile-1.4.5.min.css"> <script src="//code.jquery.com/jquery-1.10.2.min.js"></script> <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script> </head> <body> <div data-role="page" id="page1"> <div role="main" class="ui-content"> <div data-role="controlgroup"> <a href="#" class="ui-btn ui-corner-all">Yes</a> <a href="#" class="ui-btn ui-corner-all">No</a> <a href="#" class="ui-btn ui-corner-all">Maybe</a> </div> </div> </div> </body> </html>