Lotus Domino Designer 8 Help

JSP CUSTOM TAG LIBRARIES

checkbox tag
In the context of a form tag, enables you to edit the value of an item in a document using a checkbox control. This tag interacts with the form in either read mode (to generate a read only value) or edit mode (to generate an HTML <input> tag). In edit mode, this tag automatically updates the corresponding item values in the current document when the document is saved.

This tag interacts with the HTML "value" attribute of the input tag; it does not overwrite it. For single value fields, if the current value of the item in the document matches the value specified in the value attribute, the checkbox is selected. For multiple value fields, if any of the values of the item match the value specified in the value attribute, the checkbox is selected. When working with multi-value fields, make sure that the name and itemname attributes of each selected checkbox tag match.

When the form is submitted, only the value of the selected checkboxes are accepted. For single value fields, when the document is going to be saved, if the checkbox value is present, it is written into the item as the item value. If the checkbox value is not present, then "" (empty string) or 0 (zero) is written to the item value (depending on type). For multi-value fields, the form submission data contains all the selected values for a particular name and these are all written as the value of the item.

You cannot use the validation tags to validate user input. No error is thrown, but no validation is performed. If you want to ensure that a value is selected, provide a default value in the "value" attribute.

Contexts

Valid in:

form

Syntax

<domino:checkbox name="name of the control" itemname="name of the item in the document" datatype="text|number|date|datetime|readers|authors|names" multivalue="true|false" default="formula or simple value" label="text to display on control" labelkey="resource string" labelbefore="true|false" bundle="name of .properties file bundle" locale="<languageCode>_<countryCode>" debug="true|false" onfailure="inline|exception" time="true|false" value="HTML attribute that represents the checked state of a checkbox" The standard HTML tag attributes listed below>

Attributes

bundle

Name of the message bundle to use to look up internationalized messages. Default is messages. Optional.

datatype

Specifies the type of item being added to a new document as well as the automatic validation and conversion being performed on the server. Must be one of the following:

Value	Description:
text	Does not validate or convert the value entered.
number	Validates and converts the value entered to a number.
date	Validates and converts the value entered to a date.
datetime	Validates and converts the value entered to a datetime field with the format: 10/02/99 10:10 PM.
readers	Does not validate or convert the value entered. Treats the item as a readers field.
authors	Does not validate or convert the value entered. Treats the item as an authors field.
names	Does not validate or convert the value entered. Treats the item as a names field.

Default is text. The tag tries to save the data as the data type specified but can be overridden by the document. Optional.

default

Boolean value. Indicates whether to select the checkbox by default. If true, selects the checkbox; the value in the HTML value attribute is placed in the item in the document. Default is false. Optional.

itemname

Name of the item in the document that this checkbox control is associated with. This attribute is useful if the itemname and name of the control on the page need to be different, due to invalid characters in the itemname, for example. By default, this attribute equals the value of the name attribute. Optional.

labelbefore

Boolean value. If true, displays the label before the generated HTML

<input>

tag displays. Default is false. Optional.

labelkey

Locale-specific resource string to load and use in place of the label attribute. If exists, overrides the label attribute. Optional.

locale

Locale to use to lookup the proper string for the labelkey attribute. If specified, overrides the locale that the browser specifies in the AcceptLang string. Use the following syntax: "<languageCode>_<countryCode>". See

Locale codes

for more details. By default, uses the first locale specified in the AcceptLang string for the browser. An error is thrown if you specify this attribute and do not specify the labelkey attribute. Optional.

multivalue

Boolean value. If true, indicates that the field supports multiple values. In order for the checkbox tag to work properly with multi-value fields, the name and itemname attributes must match for each checkbox tag specified. When the document is saved, if the checkbox is selected on the client, the value attribute is added to the item's multiple value. If not selected, the value is removed from the item's multiple value. If any of the values of the item match the checkbox's

HTML Attributes

attribute, the checkbox is automatically selected. Default is false. Optional.

name

Name of the control on the Web page. The itemname of the control in the document defaults to this value. Required.

See the Common Domino JSP tag attributes section for definitions of debug, onfailure, and time.

HTML Attributes

Domino supports the following HTML tag attributes:

value

HTML attribute that indicates what value represents the checked state of a checkbox. If the associated item has this value, the checkbox is selected. Required.

See the Common HTML tag attributes section for definitions of the following: