forms:checkbox
AJAX
ajax:delayedload ajax:event ajax:navigation ajax:region
Data
data:calendar data:column data:eventrepeater data:postrepeater data:productbrandrepeater data:productcategoryrepeater data:productrepeater data:repeater data:table data:template data:tree
Forms
forms:address forms:captcha forms:checkbox
ATTRIBUTES
EXAMPLES
forms:checkboxgroup forms:codeeditor forms:combobox forms:datepicker forms:dialogbox forms:editbox forms:fileupload forms:form forms:hidden forms:money forms:officeuseregion forms:option forms:password forms:paymentmethod forms:radiobutton forms:radiobuttongroup forms:row forms:searchbox forms:signature forms:slider forms:spinbox forms:submitbutton forms:submitimage forms:submitlink forms:successcontent forms:textarea forms:timepicker
Layout
layout:gallery layout:productgallery layout:rotator layout:stepper layout:stepperpanel layout:tablist layout:tablistitem
Logic
logic:dependency logic:else logic:if logic:include logic:parse logic:variable
Navigation
navigation:breadcrumbs navigation:item navigation:primary navigation:secondary
Personalisation
personalisation:firstname personalisation:fullname personalisation:lastname personalisation:other
Standard
standard:audio standard:embed standard:icon standard:image standard:link standard:script standard:tooltip standard:video
Templates
templates:button templates:card templates:column templates:fancybox templates:faq templates:flexlayout templates:header templates:row templates:section templates:styles templates:teammember templates:testimonial
Regions
regions:content regions:contentadditional regions:security regions:togglable
Third Party
thirdparty:googlemap thirdparty:googlemapmarker

<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:
  • <forms:checkbox id="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:
  • <forms:checkbox name="colours[]" valuechecked="red" />
  • <forms:checkbox name="colours[]" valuechecked="green" />
  • <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

autoFocus
bool
Auto Focus

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
checked
bool
Whether or not the checkbox is checked
dataColumn
Sets the data column

The datacolumn links the form item to a key used when getting or saving from a component (as defined by the parent form).
disabled
bool
Disable Input

Disables the input, preventing user interaction
height
string
Height

Sets the height of the element. The default units are pixels. include the percentage symbol % to user percentage values.
id
string
(Required) 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.
noContainer
bool
Set to true if you need a simple <input type="checkbox"> without any container elements
saveState
bool
Restore state on reload

Whether the value of the input persists when the page is revisited.
Default = false
transformations
Value Transformations

Sets the value transformations to be applied to the value of the form item as a comma separated string.
validations
Validations

Sets the validations to be applied to the value of the form item as a comma separated string.

Eg: validations="mandatory"
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
string
Width

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.

HTML:

The most basic checkbox: <forms:checkbox id="single_checkbox_1" label="Tick me!" />

Run Example

Multiple Checkboxes of Same Name

Demonstrates multiple checkboxes mapped to the same name.

HTML:

<forms:row label="Preferred Fruits"> <forms:checkbox name="fruit[]" id="fruit_apple" label="Apple" valuechecked="Apple" /> <forms:checkbox name="fruit[]" id="fruit_orange" label="Orange" valuechecked="Orange" /> <forms:checkbox name="fruit[]" id="fruit_pear" label="Pear" valuechecked="Pear" /> </forms:row>

Run Example

AJAX Interaction (Terms and Conditions Example)

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

HTML:

<forms:form> <ajax:event id="terms_ajaxevent" updateregions="terms_ajaxregion" /> <forms:row type="one_column"> <forms:checkbox id="terms_checkbox" onclickajax="terms_ajaxevent" label="I accept the &lt;a href=&quot;https://www.google.com/policies/terms/&quot; target=&quot;_blank&quot;&gt;Terms and Conditions&lt;/a&gt;" /> </forms:row> <ajax:region id="terms_ajaxregion"> <logic:if test="$terms_checkbox.checked"> <forms:row type="one_column" align="center"> <forms:submitbutton>Submit Form</forms:submitbutton> </forms:row> </logic:if> </ajax:region> </forms:form>

Run Example

ValueChecked and ValueUnchecked

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

HTML:

<p>ValueChecked is the value returned when the checkbox is ticked.<br /> ValueUnchecked is the value returned when the checkbox is unticked.</p> <forms:form> <ajax:event id="checkbox_ajaxevent" updateregions="checkbox_ajaxregion" /> <forms:row type="one_column"> <forms:checkbox id="checkbox_1" onclickajax="checkbox_ajaxevent" label="My valuechecked is '1'; My valueuncheked is '0'" /><br /> <forms:checkbox id="checkbox_2" onclickajax="checkbox_ajaxevent" label="My valuechecked is 'on'; My valueuncheked is 'off'" valuechecked="on" valueunchecked="off" /><br /> <forms:checkbox id="checkbox_3" onclickajax="checkbox_ajaxevent" label="My valuechecked is 'apples'; My valueuncheked is 'oranges'; My default value is apples" valuechecked="apples" valueunchecked="oranges" value="apples" /><br /> </forms:row> <ajax:region id="checkbox_ajaxregion"> <br /> Checkbox 1 Value: [? $checkbox_1.value ?]<br /> Checkbox 2 Value: [? $checkbox_2.value ?]<br /> Checkbox 3 Value: [? $checkbox_3.value ?]<br /> </ajax:region> </forms:form>

Run Example