Javascript [Electronic resources] : The Definitive Guide (4th Edition) نسخه متنی

Availability

JavaScript 1.0; enhanced in JavaScript
1.1

Inherits from/Overrides

Inherits from Input, HTMLElement

Synopsis

A single Checkbox element with a unique name may be referenced in
either of these ways:

form.checkbox_name
form.elements[i]

When a form contains a group of checkboxes with the same name, they
are placed in an array and may be referenced as follows:

form.checkbox_name[j]
form.checkbox_name.length

Properties

Checkbox inherits properties from Input and HTMLElement and defines
or overrides the following:

checked

A read/write boolean property. If the checkbox is checked, the
checked property is true. If
the checkbox is not checked, checked is
false.

If you set checked to true, the
checkbox appears checked. Similarly, if you set this property to
false, the checkbox appears unchecked. Note that
setting the checked property does not cause the
Checkbox element's onclick event handler to
be invoked.

defaultChecked

A read-only boolean that specifies the initial state of the checkbox.
It is true if the checkbox is initially
checked -- i.e., if the checked attribute
appears in the checkbox's HTML <input>
tag. If this attribute does not appear, the checkbox is initially
unchecked and defaultChecked is
false.

value

A read/write string property that specifies the text passed to the
web server if the checkbox is checked when the form is submitted. The
initial value of value is specified by the
value attribute of the checkbox's HTML
<input> tag. If no value
attribute is specified, the default value string
is "on".

Note that the value field does not specify whether
the checkbox is selected; the checked property
specifies the current state of the checkbox. When defining a group of
related checkboxes that share the same name in a form that is
submitted to the server, it is important that each be given a
distinct value attribute.

Methods

Checkbox inherits the methods of Input and HTMLElement.

Event Handlers

Checkbox inherits event handlers from Input and HTMLElement and
defines or overrides the following:

onclick

Invoked when the checkbox is clicked.

HTML Syntax

A Checkbox element is created with a standard
HTML <input>
tag. Multiple Checkbox elements are often created in groups by
specifying multiple <input> tags that have
the same name attribute.

<form>
...
<input
type="checkbox"   // Specifies that this is a checkbox
[ name="name" ] // A name you can use later to refer to this checkbox
// or to the group of checkboxes with this name
// Specifies the name property
[ value="value" ] // The value returned when this checkbox is selected
// Specifies the value property
[ checked ]   // Specifies that the checkbox is initially checked
// Specifies the defaultChecked property
[ onclick="handler" ]  // JavaScript statements to be executed
>  // when the checkbox is clicked

label

  // The HTML text that should appear next to the checkbox
...
</form>

Description

The Checkbox element represents a single
graphical checkbox in an HTML form. Note that the text that appears
next to the checkbox is not part of the Checkbox element itself and
must be specified externally to the Checkbox's HTML
<input> tag.

The onclick event handler allows you to specify
JavaScript code to be executed when the checkbox is checked or
unchecked. You can examine the checked property to
determine the state of the checkbox and set this property to check or
uncheck the checkbox. Note that setting checked
changes the graphical appearance of the checkbox but does not invoke
the onclick event handler.

It is good programming style to specify the name
attribute for a checkbox; this is mandatory if the checkbox is part
of a form that submits data to a CGI script running on a web server.
Specifying a name attribute sets the
name property and allows you to refer to the
checkbox by name (instead of as a member of the form
elements array) in your JavaScript code, which
makes the code more modular and portable.

For example, if the name attribute of a checkbox
in form f is "opts",
f.opts refers to the Checkbox element. Checkbox
elements are often used in related groups, however, and each member
of the group is given the same name attribute (the
shared name defines the members of the group). In this case,
JavaScript places each Checkbox element in the group in an array, and
the array is given the shared name. If, for example, each of a group
of checkboxes in form f has its
name attribute set to "opts",
f.opts is an array of Checkbox elements, and
f.opts.length is the number of elements in the
array.

You can set the value attribute or the
value property of a checkbox to specify the string
that is passed to the server if the checkbox is checked when the form
is submitted. For a single checkbox used alone, the default
value of "on" is usually adequate.
When multiple checkboxes with the same name are used, each should
specify a distinct value so a list of values from
selected checkboxes can be passed to the server.

Usage

Checkbox elements can present the user with one or more options. This
element type is suitable for presenting non-mutually exclusive
choices. Use the Radio element for mutually exclusive lists of
options.

See Also

Form, HTMLElement, Input, Radio; HTMLInputElement in the DOM
reference section