The InputElements user guide
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.
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.
These elements do not have labels, so are derived from the base class InputElement.
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 |
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. |
These elements can have labels, so are derived from the InputElementWithLabel class
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. |
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.
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. |
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. |
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.
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. |
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. |