Radio Button Group Builder

Radio Button Group Builder

In this topic ...

Quick Tips
Specifying Inputs
Using the Radio Button Group Builder

Related Topics ...

Overview: Creating Forms
HTML event action builder
HTML Guidelines
Passing Arguments to Actions

Use the Radio Button Group builder to create a set of radio buttons on a page. Provide the builder with a list of choices from which the user can choose. We can specify the text to display to the user as different from the value that the builder returns by specifying an XML structure as the radio button group's source data.
Unlike the radio button builder, which makes use of existing HTML radio buttons, the Radio Button Group builder creates radio buttons from scratch. When using this builder, do not put the radio buttons directly in your HTML. Instead, create in the HTML a container (typically a <div /> tag) that will hold the list of choices for which you are creating the control. Give the name of the control to this container tag. (Note that we can put style information on the <div /> tag, such as a "border-style" setting, and it will be saved for the <div /> that will hold the set of radio buttons.) When the page is rendered, the <div /> area is converted into a table, containing the radio buttons and text, according to the data you specify.
The Radio Button Group builder and the Select builder are almost identical in their inputs and their results -- they each provide the user with a list of choices and return a single value. The value will be stored in the "Inputs/" node in the WebApp. We can access this value either by using the Reference Chooser in other builder call editors or by calling the webAppAccess.getRequestInputs().getInputValue(TagName), where TagName is the named <span /> or <div /> tag on which the Radio Button Group builder call operates.

Quick Tips

Radio button group and select builders behave similarly -- Think of a Radio Button Group builder the same way you think of a select control. A Radio Button Group builder accepts a list of choices and returns a single value (which is one of those choices). Although the two controls look very different to the user, they are quite similar in nature.
Use an HTML Event Action builder call to process radio button group changes -- We can configure your model to react to radio button group selections by using an HTML Event Action builder call to process the OnClick event for the radio button group on the page. See HTML event action builder for more information.

Specifying Inputs

The Radio Button Group builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see Using the Builder Call Editor.

Input Name Description
Name Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Page Location Use the Page Location input to specify the page or pages on which this builder call will act.
See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Radio Group Data Specify data returned from a Function, Method, Service Call, or Variable. This data will be in XML. We can also specify a comma-delimited list or specify a method or Java expression that returns an object that implements java.util.Collection or an iterator for a Java collection. See Specifying Lists for more information.
Lookup Table Used This input replaces the radio Group Data input above if the model in which this Radio Button Group builder is located also contains one or more Lookup Table builders.
Use this input to choose the name of the Lookup Table builder call whose results you want to display with this Radio Button Group call.
The Radio Button Group builder call will display the results of the Lookup Table's builder's GetLookupTable method. The displayed content is determined by the Lookup Table builder call's "Value Tag" and "Label Tag " input settings
XML Data Source Elements
Label Element Enter the path to the XML element whose value you want to display as the label for each radio button.
If you leave this input blank, the radio button group uses the second element contained by each node in the source data for which the factory servlet creates a radio button.
Value Element Enter the path to the XML element whose value you want to pass as the input value for the radio button group.
If you leave this input blank, the radio button group uses the first element contained by each node in the source data for which the Factory servlet creates a radio button.
Selected Value value that will be shown as enabled when a user first runs the model. If you supply the Radio Button Group builder with XML data, the corresponding Label Element value will be selected.
For example: ${Variables/radioboxChoices/Item[0]}.
Orientation Choose to position the radio boxes horizontally (side by side) or vertically (one above the other).
Advanced
Alternate Rendering If this is checked, the builder constructs the radio box group to allow additional builders to be targetted within it. For example, if you wanted to make a radio button group for which each of the choices has an image rather than just text, you could use an image builder within the portion of the page that the Radio Button Group builder created. Checking this option also creates a loop variable and a counter variable, just as in the repeated region builder.

Using the Radio Button Group builder

You need to specify several settings to create a group of radio buttons. The first is selection options. This is the list of choices offered to the user and is usually drawn from a variable. There are two option styles that are acceptable:

Specifying a flat options list

If the displayed label for each choice is the same as the text that should be returned by the control, use a simple flat list as the radio button group's data source. In this case, you do not need to specify a label element or a value element. The XML structure below illustrates the format use when the text to be displayed to the user for each option is the same as the text that should be returned by the control (element names may be different from those shown here):
<options> <option>Choice 1</option> <option>Choice 2</option> <option>Choice 3</option> <option>Choice 4</option> </options>

Using name/value pairs

To display something different to the user than the value that is returned from the control, your source data must include an element whose value will be used as the value for the Radio Button Group input and an element whose value will be used to provide a label for each radio button. In the radio button group's builder call editor, specify the relative path (from the specified source data) to the "value" and "label" elements as the values for the Value Element and Label Element inputs.
For example, here is the Options format use if the text displayed to the user should be different from the value returned by the control:
<options> <option> <value>Ch2</value> <text>Choice 1</text> </option> <option> <value>Ch2</value> <text>Choice 2</text> </option> <option> <value>Ch3</value> <text>Choice 3</text> </option> </options>
In the example, you would enter text as the Label Element value and value for the Value Element value.

Using the Selected Value field

This is the value that is selected by default when the page is displayed. The value that you type in this field must match one of the options in the contents of the builder. We can also use a data reference like ${Variables/myVariable}.
For example, say you provide your builder with contents from a Variable such as:
<Options> <option>cat</option> <option>dog</option> <option>bird</option> </Options>
You could type bird in the selected value field to display bird as the default selected value. Or if you had a Variable called "myVariable" with the value of "cat", you could type ${Variables/myVariable} in the selected value field.
The option that matches the value specified in Selected Value is the one selected when the page is displayed. If the selected value does not match any of the options, then no default will be selected.

List orientation

In most situations, you will want a "Vertical" orientation. This causes buttons to appear in a vertical list with accompanying labels listed one under the other. In some cases, such as when we need to provide only two or three choices, you might want to display the choices across the page on a single line. In this situation, choose "horizontal" to create this linear type of button layout.

Using label and value elements

In general, the Label and Value elements are used to associate a visible label with an invisible value that is actually submitted. The Label Element specifies which value in a multi-valued source should become the text or visible label of an item in a select list. For example, if the output of some service call is a list in which each item is composed of three parts, the Label Element field allows specification of one of those parts as the item label, which will be visible in the list at runtime.
Consider the following structure:
<THE_STRUCTURE> <THE_LIST> <THE_ITEMS> <ITEM> <NAME>Fred</NAME> <AGE>22</AGE> <SSN>111223333</SSN> </ITEM> <ITEM> <NAME>Bob</NAME> <AGE>35</AGE> <SSN>222334444</SSN> </ITEM> </THE_ITEMS> </THE_LIST> </THE_STRUCTURE>
The Value Element specifies which element in a node should be assigned to the "value" attribute of the <OPTION> tags in the list produced at runtime. It is this value that is actually posted when the users submits a form containing a radio button group. In the example above, if the sub-item "AGE" is specified as the Value Element, then when the name "Fred" is selected by the user and the form posted, the value "22" would be transmitted to the Factory servlet, although this value would not be visible to the user (the "SSN" field is ignored).

Input Name	Description
Name	Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Page Location	Use the Page Location input to specify the page or pages on which this builder call will act. See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Radio Group Data	Specify data returned from a Function, Method, Service Call, or Variable. This data will be in XML. We can also specify a comma-delimited list or specify a method or Java expression that returns an object that implements `java.util.Collection` or an iterator for a Java collection. See Specifying Lists for more information.
Lookup Table Used	This input replaces the radio Group Data input above if the model in which this Radio Button Group builder is located also contains one or more Lookup Table builders. Use this input to choose the name of the Lookup Table builder call whose results you want to display with this Radio Button Group call. The Radio Button Group builder call will display the results of the Lookup Table's builder's `GetLookupTable` method. The displayed content is determined by the Lookup Table builder call's "Value Tag" and "Label Tag " input settings
XML Data Source Elements
Label Element	Enter the path to the XML element whose value you want to display as the label for each radio button. If you leave this input blank, the radio button group uses the second element contained by each node in the source data for which the factory servlet creates a radio button.
Value Element	Enter the path to the XML element whose value you want to pass as the input value for the radio button group. If you leave this input blank, the radio button group uses the first element contained by each node in the source data for which the Factory servlet creates a radio button.
Selected Value	value that will be shown as enabled when a user first runs the model. If you supply the Radio Button Group builder with XML data, the corresponding Label Element value will be selected. For example: `${Variables/radioboxChoices/Item[0]}`.
Orientation	Choose to position the radio boxes horizontally (side by side) or vertically (one above the other).
Advanced
Alternate Rendering	If this is checked, the builder constructs the radio box group to allow additional builders to be targetted within it. For example, if you wanted to make a radio button group for which each of the choices has an image rather than just text, you could use an image builder within the portion of the page that the Radio Button Group builder created. Checking this option also creates a loop variable and a counter variable, just as in the repeated region builder.