ss:ajax:delayedload ss:ajax:event ss:ajax:region ss:data:calendar ss:data:column ss:data:repeater ss:data:table ss:data:tree ss:forms:captcha ss:forms:checkbox ss:forms:codeeditor ss:forms:combobox ss:forms:datepicker ss:forms:daterange ss:forms:dialogbox ss:forms:editbox ss:forms:fileupload ss:forms:fileuploadimage ss:forms:form ss:forms:hidden ss:forms:money ss:forms:officeuseregion ss:forms:option ss:forms:password ss:forms:paymentmethod ss:forms:radiobutton ss:forms:row ss:forms:searchbox ss:forms:selectlist ss:forms:signature ss:forms:slider ss:forms:spinbox ss:forms:submitbutton ss:forms:submitimage ss:forms:submitlink ss:forms:textarea ss:forms:timepicker ss:layout:rotator ss:layout:stepper ss:layout:stepperpanel ss:layout:tablist ss:layout:tablistitem ss:logic:dependency ss:logic:parse ss:logic:if ss:logic:else ss:logic:include ss:logic:template ss:logic:variable ss:navigation:breadcrumbs ss:navigation:item ss:navigation:primary ss:navigation:secondary ss:personalisation:firstname ss:personalisation:fullname ss:personalisation:lastname ss:personalisation:other ss:regions:content ss:regions:contentadditional ss:regions:security ss:regions:togglable ss:standard:audio ss:standard:embed ss:standard:icon ss:standard:image ss:standard:label ss:standard:link ss:standard:script ss:standard:video ss:templates:column ss:templates:row ss:templates:section ss:templates:teammember ss:thirdparty:googlemap ss:thirdparty:googlemapmarker
.
.
.

<ss:forms:checkbox />

Check boxes allow the user to toggle things on and off in a form. They can be used singularly (as a sort of alternative to two radio buttons), or they can be used in groups where the user can select any number of options.

For example you could have the following CheckBox:
  • <ss:forms:checkbox name="switch" valuechecked="on" valueunchecked="off" />
which will submit either "on" or "off" to the server. Or you could have valuechecked="blue" valueunchecked="red", which implies that the default value for this particular parameter is "red", rather than no value at all.

Where CheckBoxes shine is where you need the user to specify zero, one, or many values for a single item in a form:
  • <ss:forms:checkbox name="colours[]" valuechecked="red" />
  • <ss:forms:checkbox name="colours[]" valuechecked="green" />
  • <ss:forms:checkbox name="colours[]" valuechecked="blue" />
Here the user can select the colours they like, which will be posted to the server to the field colours. Note valueunchecked is not relevent in this case; if no values are selected then the value for colours is empty.

Attributes

focusOnLoad
bool
If true, this control will attempt to focus itself after the page has loaded. Note that only one element may be focused on the page at a time. Default = false.
height
mixed
Sets the height of the element. The default units are pixels. include the percentage symbol % to user percentage values.
id
string
Most form items need a unique id so that they can submit data to the server. No two form items may have the same id. For situations where multiple form items submit to the same field, see the name attribute. Id's that begin with contact_ will automatically save Contact information to the Contact database as long as the user has entered enough identifying information (ideally Name and Email). Check the Contact Fields page for correct field names.
name
string
Sets the name of the form item. Most of the time, the id attribute will suffice. However with form items that post multiple values into an array, each item will need to have the same name, followed by []. For example three controls with name="data[]", will all post into 'data'. Radio buttons belonging to the same group will have to share the same name.
valueChecked
string
What is posted to the server when this checkbox is checked. Defaults to "1", which is fine if you have a single checkbox for enabling/disabling a boolean option. If you have multiple checkboxes for the same name, then each must have a different valuechecked.
valueUnChecked
string
The value the server sees when this checkbox is not checked. Relevent only when there is a single checkbox for a given name.
width
mixed
Sets the width of the element. The default units are pixels. include the percentage symbol % to user percentage values.

Examples

Single Basic Checkbox

The most basic of checkboxes.

XML Code:


Run Example

Multiple Checkboxes of Same Name

Demonstrates multiple checkboxes mapped to the same name.

XML Code:


Run Example

AJAX Interaction (Terms and Conditions Example)

Demonstrates showing and hiding elements inside an AJAX Region depending on the state of a checkbox.

XML Code:


Run Example

ValueChecked / ValueUnchecked

Alters the result of the checkboxes value when checked or unchecked.

XML Code:


Run Example