Validation Radio Button widget overview and structure

The Validation Radio Button widget is a group of radio buttons with validation support for the selection. The widget enforces the selection of one radio button from the group.

The following example shows a Validation Radio Button widget in various states.

A.: Validation Radio Button widget error messages
B.: Validation Radio Button widget group

The Validation Radio Button widget includes three states beyond the initial state: valid, invalid, and required value. You can alter the properties of these states by editing the corresponding CSS file (SpryValidationRadio.css), depending on the desired validation results. A Validation Radio Button widget can validate at various points: when the user clicks outside the widget, as the user makes selections, or when the user tries to submit the form.

Initial state: When the page loads in the browser, or when the user resets the form.
Valid state: When the user makes a selection, and the form can be submitted.
Required state: When the user fails to make a required selection.
Invalid state: When the user selects a radio button whose value is not acceptable.

Whenever a Validation Radio Button widget enters one of these states through user interaction, the Spry framework logic applies a specific CSS class to the HTML container for the widget at run time. For example, if a user tries to submit a form, but makes no selections, Spry applies a class to the widget that causes it to display the error message, “Please make a selection.” The rules that control the style and display states of error messages reside in the SpryValidationRadio.css file that accompanies the widget.

The HTML code for the Validation Radio Button widget, usually inside a form, is made up of a container tag (in the following example, a span tag) that surrounds the input type="radio" tag of the radio button. The HTML code for the Validation Radio Button widget also includes script tags in the head of the document and after the widget’s HTML code. The script tag in the head of the document defines all of the JavaScript functions related to the Radio Button widget. The script tag after the widget code creates a JavaScript object that makes the Validation Radio Button widget interactive.

Following is the HTML code for a Validation Radio Button widget:

<head> 
...  
<!-- Link the Spry Validation Radio Button JavaScript library --> 
<script src="SpryAssets/SpryValidationRadio.js" type="text/javascript"></script> 
<!-- Link the CSS style sheet that styles the widget -->
<link href="SpryAssets/SpryValidationRadio.css" rel="stylesheet" type="text/css" /> 
</head>
<body>
	<form id="form1" name="form1" method="post" action="">
		<!-- Create the Radio Button widget and assign a unique id-->
		<span id="RadioWidget">
			<input type="radio" name="fieldName" value="1">
			<input type="radio" name="fieldName" value="2">
			<!--Add an error message-->
			<span class="radioRequiredMsg">Please make a selection.</span>
		</span>
	</form>
<!-- Initialize the Validation Radio Button widget object-->
<script type="text/javascript">
	var spryRadio1 = new Spry.Widget.ValidationRadio("RadioWidget");
</script>
</body>

In the code, the new JavaScript operator initializes the Radio Button widget object, and transforms the span content with the ID of RadioWidget from static HTML code into an interactive page element.

The span tag for the error message in the widget has a CSS class applied to it. This class (which is set to display:none; by default), controls the style and visibility of the error message, and exists in the accompanying SpryValidationRadio.css file. When the widget enters different states as a result of user interaction, Spry places different classes on the container for the widget, which in turn affects the error-message class.

You can add other error messages to a Validation Radio Button widget by creating a span tag (or any other type of tag) to hold the text of the error message. Then, by applying a CSS class to it, you can hide or show the message, depending on the widget state.

You can change the default appearance of the Validation Radio Button widget's states by editing the corresponding CSS rule in the SpryValidationRadio.css file. For example, to change the background color for a state, edit the corresponding rule or add a new rule (if it’s not already present) in the style sheet.

Variation on tags used for Radio Button widget structure

In the preceding example, span tags create the structure for the widget:

Container SPAN
	INPUT type="radio"
	Error message SPAN

You can, however, use almost any container tag to create the widget.

Container DIV
	INPUT type="radio"
	Error Message P

Spry uses the tag ID (not the tag itself) to create the widget. Spry also displays error messages using CSS code that is indifferent to the actual tag used to contain the error message.

The ID passed into the widget constructor identifies a specific HTML element. The constructor finds this element and looks inside the identified container for a corresponding input tag. If the ID passed to the constructor is the ID of the input tag (rather than a container tag), the constructor attaches validation triggers directly to the input tag. If no container tag is present, however, the widget cannot display error messages, and different validation states alter only the appearance of the input tag element (for example, its background color).