Parent | Child | Previous | Next
 

A5W_CHECKBOXES Function

Syntax

HTML_Input_Code as C = a5w_CheckBoxes(C choices ,C name [,C selected [,C style [,C orientation [,C events [,C id [,C separator [,L flagUseArraySyntaxForSingleChoice [,C class [,L flagDisabled [,C spanClass [,C verticalSpaceBetweenControls [,C customAttributes]]]]]]]]]]]])

Arguments

choicesCharacter

A CR-LF delimited list of choices to include in the checkbox list. Each choice is defined using the format displayValue|storedValue|attributes. storedValue and attributes are optional. If the storedValue is not specified, the value of the checkbox will be identical to the displayValue. Examples:

Simple list of choices
apple
orange
mango
List of choices with customized stored values
January|1
February|2
March|3
Defining Attributes
Not Applicable|1|required myCustomAttribute="some value"
Yes|2|required
No|3|required

To assign an attribute to all checkbox options, use the customAttributes argument.

nameCharacter

The name of the checkbox group. This is required.

selectedCharacter

Default = "". The default selected value for the checkbox group.

styleCharacter

Default = "". Optional inline CSS styles to add to the style attribute for each choice in the checkbox group.

orientationCharacter

Default = "horizontal". The orientation of the checkbox choices. The orientation can be one of the following:

Orientation
Description
"horizontal"

Choices are side by side, left to right.

"vertical:verticalSpace"

Choices are on separate lines, top to bottom. You can optionally specify additional space to include between each value using the syntax :verticalSpace after the word "vertical". For example, "vertical:20px".

"COLUMNS:LRTB:count"

Choices snake from left-to-right, top-to-bottom where count is the number of columns

"COLUMNS:TBLR:count"

Choices snaking from top-to-bottom, left-to-right where count is the number of rows

eventsCharacter

Default = "". Optional event attributes to add to each checkbox. For example, "onclick=\"alert('clicked '+this.value+'!');\"". See HTMLElement (MDN) to learn more about HTML element event attributes.

idCharacter

Default = "". An optional ID to assign each checkbox element. The generated id is the form "id.count" where count is a numeric value assigned to the choice. Numeric values are assigned to choices in the order listed in the choices variable, beginning with the number 1.

separatorCharacter

Default = "|". The character string used to separate each setting in the choices parameter. If choices use a separator other than "|" to define the display, stored, and optional attribute values, you pass in the separator string into the separator argument.

flagUseArraySyntaxForSingleChoiceLogical

Default = .t.. If choices contains one value, setting flagUseArraySyntaxForSingleChoice to .f. omits the brackets from the name assigned to the name attribute for the generated output. I.e., name="myCheckboxes" instead of name="myCheckboxes[]".

classCharacter

Default = "". One or more optional classes to assign to the class attribute for each checkbox option.

flagDisabledLogical

Default = .f.. If .t., the generated output creates a checkbox group that is disabled (the choices cannot be modified when interacted with in a browser.)

spanClassCharacter

Default = "". One or more class names to add to the <span> tag that wraps each choice.

verticalSpaceBetweenControlsCharacter

Default = "". A CSS length value that defines the vertical space to include between controls when orientation is set to "vertical". E.g. 25px.

customAttributesCharacter

Default = "". One or more attributes to add to each checkbox. For example: "required myCustomAttribute=\"some value\""

Returns

HTMLCharacter

Returns the generated <input> markup for a list of checkboxes that can then be added to the HTML for an application.

Description

Generate code for Checkbox controls.

Discussion

The A5W_CHECKBOXES() function generates <input> HTML elements for a list of choices. The generated markup can be inserted into the HTML for an application, such as a <div> on an .a5w page or a Static Text control in a UX component.

For example:

dim choices as c =<<%txt%
apple
orange
mango
%txt%

dim name as c = "fruit"

dim html as c = a5w_checkboxes(choices,name)

? html
= <span><input id="fruit.1" type="checkbox" value="apple" name="fruit[]"  />apple</span>
<span><input id="fruit.2" type="checkbox" value="orange" name="fruit[]"  />orange</span>
<span><input id="fruit.3" type="checkbox" value="mango" name="fruit[]"  />mango</span>

The value attribute can be a different value from the displayed choice by specifying a stored value. For example, in the Xbasic script below, a numeric value is specified for each choice. Note that the value attribute in the generated output contains the stored values:

dim choices as c =<<%txt%
January|1
February|2
March|3
%txt%

dim name as c = "Q1"

dim html as c = a5w_checkboxes(choices,name)

? html
= <span><input id="Q1.1" type="checkbox" value="1" name="Q1[]"  />January</span>
<span><input id="Q1.2" type="checkbox" value="2" name="Q1[]"  />February</span>
<span><input id="Q1.3" type="checkbox" value="3" name="Q1[]"  />March</span>

You can also specify optional attributes to include in the <input> tag for a choice after the stored value. For example:

dim choices as c =<<%txt%
Not Applicable|1|myCustomAttribute="some value"
Yes|2
No|3
%txt%

dim name as c = "yesNo"

dim html as c = a5w_checkboxes(choices,name)

? html
= <span><input id="yesNo.1" myCustomAttribute="some value" type="checkbox" value="1" name="yesNo[]"  />Not Applicable</span>
<span><input id="yesNo.2" type="checkbox" value="2" name="yesNo[]"  />Yes</span>
<span><input id="yesNo.3" type="checkbox" value="3" name="yesNo[]"  />No</span>