usbuttonset()

The usbuttonset() function is a framework-independent function. It creates a group of buttons that act as "radio buttons" in a framework-independent fashion. Only a single button in the group may be selected (or: active) at any one time:

The selected button determines the value attributed to the group as a whole. The group may appear in disabled state: in this state, none of the buttons can be selected.

This function does not "transform" the HTML element on which it executes; rather, it generates the elements needed to realise the radio button group. The generated elements are quite framework-specific: for Bootstrap frameworks, a number of button elements is generated and added to the HTML element on which the function executes, whereas on jquery-ui and ‘none’ frameworks, an input element of type ‘radio’ and a label element are generated for each value option. For all frameworks however, it is the CSS that transforms the generated elements to the expected visual output.

Returns the HTML element.

Syntax

.usbuttonset( options )
.usbuttonset( "disable", disable-def-true )
.usbuttonset( "value", value )

options  ::= {
  values: prompt-values,
  disable: disable-def-false,
  name: name
}

prompt-values      ::= prompt-value, prompt-value...
prompt-value       ::= { prompt: prompt, val: value }

disable-def-false  ::= { true | false }

disable-def-true       ::=  { true | false }

You must call .usbuttonset() with either an options struct, with the "disable" parameter, or with the "value" parameter.

Use the options struct to define properties of the radio button group. In this struct, prompt-values is an array of objects each of which must have a 'prompt' and a 'val' property. 'Prompt' is a string designating the visual prompt displayed for the radio option. 'Prompt' may be a simple string but also an HTML fragment. 'Val' is a simple string value that designates the value associated with the radio option.

'Disable' is a boolean that determines whether the radio button group appears in the enabled or disabled state. The default is 'false' (= enabled). 'Name' is an optional string value that you can use if you need to distinguish buttons in multiple radio button groups.

With the "disable" parameter, the optional second parameter is a boolean that determines whether the buttons must appear in disabled state. The default is 'true' (= disabled).

With the "value" parameter, the required value designates the string value to which the radio button group is set or reset.

Example

var $buttonSet = $("<div />").usbuttonset(
  { values: [
    { prompt: "Male", val: "M" },
    { prompt: "Female", val: "F" },
    { prompt: "Unknown", val: "X" },
    ],
    name: "Test4"
  }).appendTo(".Data");

$buttonSet.usbuttonset( "disable", false );
$buttonSet.usbuttonset( "value", "M" );