California Ajax Solutions Team

www.CalAST.com

The InputElements user guide

Introduction

This web page is the user manual for the InputElements library.

InputElements is an object-oriented JavaScript library for building forms and other parts of web pages in a consistent manner with a standardized API. The InputElements library consists of a number of components, only some of which the user needs to understand:

Only the last three items are required, since ideally the user will never see the first three.

Note also that all element have a property named input, and there is nothing preventing the user from accessing it directly with all the properties and methods of the corresponding DOM object.

Class Hierarchy

This section describes the structure of the library and how classes are related. Feel free to skip over this if you believe this information is not necessary for your purposes.

There are two base classes, which are not intended to be used directly in applications but are documented for completeness. These two base classes are InputElement and ElementLabel. Using both composition and inheritance, all other objects in the library derive from these in one way or another. There is also an intermediate-level class named InputElementWithLabel. Some classes are derived from that class, but it is not intended to be used directly either.

The InputElement class creates a DOM node of type INPUT. Any class that is a type of input (e.g., a textbox) inherits from InputElement. Classes that are not inputs, like drop-down lists, do not. InputElement implements methods appendTo, enable, disable, onClick, and onChange.

The ElementLabel class creates a DOM node of type LABEL, but only in response to the user actually setting a label value. No class has ElementLabel as a parent; it is used only in composition. ElementLabel implements the methods getLabel, setLabel and setTextAlign.

The InputElementWithLabel class is the parent of many other classes in the library. It inherits from InputElement and includes an ElementLabel via composition. InputElementWithLabel implements two wrapper methods for setLabel and setTextAlign, and overrides the appendTo method with one that knows about labels.

Objects that are described in the section Elements that are not True Inputs have ElementLabel members, but are not derived from InputElement or InputElementWithLabel. They just have the same interface for consistency.

Simple Elements

These elements do not have labels, so are derived from the base class InputElement.

InputElementHidden

This object provides a way to pass information to the server as part of a form without any on-screen representation.

Method Arguments Purpose
InputElementHidden tag, value Constructor, creates element with tag as name and id, sets value
appendTo parent DOM node Appends the object to the specified DOM node
setValue val Changes the value of the element, set in constructor
getValue none Returns the value of the object

InputElementButton

This object adds a button element to a form, with an optional (but commonly required) event handler. In addition, you can associate a value with the button and retrieve it later (say, in an event listener). In the DOM, the value of a button is its display text, but InputElements provides an additional storage location.

Method Arguments Purpose
InputElementButton tag, text Constructor, creates element with tag as name and id, and specified text as button label
appendTo parent DOM node Appends the object to the specified DOM node
onClick function Adds an onclick event handler to the object
setLabel text Provides a way to change the label text after object creation
setValue object Save an object inside the button for later use
getValue (none) Retrieves the previously saved value.
disable (none) Disable the control.
enable (none) Enable the control.

Elements with Labels

These elements can have labels, so are derived from the InputElementWithLabel class

InputElementTextbox

This object extends the standard DOM textbox.

Method Arguments Purpose
InputElementTextbox tag Constructor, creates element with tag as name and id
appendTo parent DOM node Appends the object to the specified DOM node
onChange function Adds an onchange event handler to the object
setLabel text Adds a label to the textbox
setTextAlign 'right' or 'left' Changes label placement; default is left.
setSize width Sets the size of the textbox
setTooltip text Specifies the text shown when hovering over element
setValue text Specifies the value to be displayed in the textbox
getValue none Returns the current value of the text in the element
disable (none) Disable the control.
enable (none) Enable the control.

InputElementEmail

This object represents the HTML5 email type input. It has the same methods as InputElementTextbox. In some browsers, it may be treated as a textbox if HTML5 is not fully supported.

InputElementCheckbox

This object extends the standard DOM checkbox.

Method Arguments Purpose
InputElementCheckbox tag Constructor, creates element with tag as name and id
appendTo parent DOM node Appends the object to the specified DOM node
onChange function Adds an onchange event handler to the object
setLabel text Adds a label to the checkbox
setTextAlign 'right' or 'left' Changes label placement; default is left.
setChecked none Causes box to display as checked, value to be sent to server
clearChecked none Causes box to display as unchecked, will not be sent to server
isChecked none Returns true if box is checked, false otherwise
setValue string Stores a string value as an attribute of the checkbox
getValue none Returns string value associated with the checkbox
disable none Disable the control.
enable none Enable the control.

InputElementRadioGroup

This object represents a group of radio buttons with an optional group label. There is also an object representing a radio button, but a single button is uninteresting and the semantics of radio buttons only makes sense in the context of a group from which only one can be selected. Each individual button within the group has a label of its own, and there is a label for the group. However, groups of radio buttons are not part of the DOM, so the group is never part of the tree, unlike other InputElement objects. All of the buttons that are part of the group are added together when the appendTo method is invoked, so this must always be the last action taken.

Method Arguments Purpose
InputElementRadioGroup tag Constructor, creates an object to represent this group of buttons. Tag is used as the name of all buttons in the group.
appendTo parent DOM node Appends the buttons to the specified DOM node
setLabel text Adds a label to the group
setTextAlign 'right' or 'left' Changes group label placement; default is left.
addButton label, value Adds a new radio button to the group. The specified label is the label for the button itself. The value will be assigned to the radio button. If no value is specified, label will be used for the value as well.
selectButton index The specified button (zero being the first) will be selected.
selectButtonByLabel label The button whose label matches the argument will be selected.
getGroupSize none Returns the number of buttons in the group.
getSelected none Returns the value of the currently selected button, or null if none selected.
getButton index Returns the button object specified by the index argument. Can be used to compose other objects from the buttons in the group.
getValue none Returns the value of the currently selected button.

Elements that are not True Inputs

Since these objects are not inputs in the HTML sense, they cannot derive from the base or labeled classes. However, they are designed to have the same interface and to work in the same way.

InputElementTextarea

This element extends the standard DOM textarea object. Note that this looks like the textbox API except that the setSize method has a height as well as a width.

Method Arguments Purpose
InputElementTextarea tag Constructor, creates element with tag as name and id
appendTo parent DOM node Appends the object to the specified DOM node
onChange function Adds an onchange event handler to the object
setLabel text Adds a label to the textarea
setTextAlign 'right' or 'left' Changes label placement; default is left.
setSize width, height Sets the size of the textarea
setTooltip text Specifies the text shown when hovering over element
setValue text Specifies the value to be displayed in the textarea
getValue none Returns the current value of the text in the element
disable (none) Disable the control.
enable (none) Enable the control.

InputElementDDL

This element extends the drop-down-list (HTML SELECT) DOM object. At present, multiple-select is not supported.

Method Arguments Purpose
InputElementDDL tag Constructor, creates select element with tag as name and id
appendTo parent DOM node Appends the object to the specified DOM node
onChange function Adds an onchange event handler to the object
setLabel text Adds a label to the select
setTextAlign 'right' or 'left' Changes label placement; default is left.
setAttribute name,value  Adds an HTML attribute to the select.
addOption txt,val,def,sel Adds an option to the select, using txt as the on-screen display value, val as the option value, def as the default, and sel as selected. Uses the standard JavaScript Option object to build the option element. Only txt is required. If not specified, val will default to txt.
addOptionList array of strings Adds a group of options to the select, as if the addOption method was called for each member of the array with only the txt value specified.
select index Sets the selectedIndex property of the select to index
getSelectedRow none Returns the currently selected index, or -1 if none selected
getValue none Returns the value of the currently selected item from the list, or null if none
getRowCount none Returns the number of options added to the select
getOption index Returns an object representing the specified option or null. The returned object contains the display text and value of that option.
selectByValue value Sets the current selected index to the option whose value matches the argument. This is especially useful in providing an edit form, where the current values are set for all the form elements.
disable (none) Disable the control.
enable (none) Enable the control.