Class RapidContext.Widget.Form

.Widget.Form(attrs, …childopt) → {Widget}

The form widget class. Provides a grouping for form fields, using the <form> HTML element. The form widget supports form reset, validation and data retrieval.

Constructor Summary
	`new Form(attrs, …childopt) → {Widget}` Creates a new form widget.

Method Summary
	`addAll(…child)` Adds one or more children to this widget.
	`addChildNode(child)` Adds a single child DOM node to this widget.
	`addClass(…cls)` Adds the specified CSS class names to this HTML DOM node.
	`addValidator(field, validator)` Adds a custom form validator for a named form field.
	`blurAll()` Blurs (unfocuses) this DOM node and all relevant child nodes.
	`destroy()` The internal widget destructor function.
	`disable()` Disables this widget if it was previously enabled.
	`emit(event, optsopt) → {boolean}` Dispatches a single event from this DOM node.
	`enable()` Enables this widget if it was previously disabled.
	`fieldMap() → {Object}` Returns a map with all child DOM nodes containing form fields with a name attribute.
	`fields() → {Array}` Returns an array with all child DOM nodes containing form fields.
	`getChildNodes() → {Array}` Returns an array with all child DOM nodes.
	`hasClass(…cls) → {boolean}` Checks if this HTML DOM node has the specified CSS class names.
	`hide()` Hides this widget node if it was previously visible.
	`isDisabled() → {boolean}` Checks if this widget is disabled.
	`isHidden() → {boolean}` Checks if this widget node is hidden.
	`off(eventopt, selectoropt, listeneropt) → {Node}` Removes one or more previously attached event listeners.
	`on(event, selectoropt, listener, optsopt) → {Node}` Attaches a listener function for one or more events.
	`once(event, selectoropt, listener, optsopt) → {Node}` Attaches a single event listener function.
	`removeAll()` Removes all children to this widget.
	`removeChildNode(child)` Removes a single child DOM node from this widget.
	`removeClass(…cls)` Removes the specified CSS class names from this HTML DOM node.
	`removeValidators(fieldopt)` Removes all custom form validators for a named form field.
	`reset()` Resets all fields and validations to their original state.
	`setAttrs(attrs)` Updates the widget or HTML DOM node attributes.
	`setStyle(styles)` Updates the CSS styles of this HTML DOM node.
	`show()` Shows this widget node if it was previously hidden.
	`toggleClass(…cls) → {boolean}` Toggles adding and removing the specified CSS class names to and from this HTML DOM node.
	`uid() → {string}` Returns the unique identifier for this DOM node.
	`update(values)` Updates the fields in this form with a specified map of values.
	`validate() → {boolean}` Validates this form using the form validators found.
	`validateReset()` Resets all form validations.
	`validators() → {Array}` Returns an array with all child DOM nodes containing form validator widgets.
	`valueMap() → {Object}` Returns a map with all form field values.

Constructor

new Form(attrs, …childopt) → {Widget}

Creates a new form widget.

Parameters:

Name Type Attributes Description

attrs

{Object}

the widget and node attributes

Properties

Name	Type	Attributes	Description
`hidden`	{boolean}	<optional>	the hidden widget flag, defaults to false

child {string|Node|Array} <optional>
<repeatable> the child widgets or DOM nodes

Returns:

{Widget} the widget DOM node

Examples:

JavaScript

var field = RapidContext.Widget.TextField({ name: "name", placeholder: "Your Name Here" });
var attrs = { name: "name", message: "Please enter your name to proceed." };
var valid = RapidContext.Widget.FormValidator(attrs);
var exampleForm = RapidContext.Widget.Form({}, field, valid);

User Interface XML

<Form id="exampleForm">
  <TextField name="name" placeholder="Your Name Here" />
  <FormValidator name="name" message="Please enter your name to proceed." />
</Form>

Source:

RapidContext_Widget_Form.js, line 48

Extends

RapidContext.Widget

Methods

addAll(…child)

Adds one or more children to this widget. This method will flatten any arrays among the arguments and ignores any null or undefined arguments. Any DOM nodes or widgets will be added to the end, and other objects will be converted to a text node first. Subclasses should normally override the addChildNode() method instead of this one, since that is the basis for DOM node insertion.

Parameters:

Name	Type	Attributes	Description
`child`	{string\|Node\|Array}	<repeatable>	the children to add

Inherited From:

RapidContext.Widget#addAll

Source:

RapidContext_Widget.js, line 535

addChildNode(child)

Adds a single child DOM node to this widget. This method is sometimes overridden by child widgets in order to hide or control intermediate DOM nodes required by the widget.

Parameters:

Name	Type	Description
`child`	{Widget\|Node}	the DOM node to add

Inherited From:

RapidContext.Widget#addChildNode

Source:

RapidContext_Widget.js, line 499

addClass(…cls)

Adds the specified CSS class names to this HTML DOM node.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to add

Inherited From:

RapidContext.Widget#addClass

Source:

RapidContext_Widget.js, line 329

addValidator(field, validator)

Adds a custom form validator for a named form field. The function will be called as [field].validator([value], [field], [form]) and should return true, false or a validation error message. The validator will be called on each input event and before form submission for enabled fields.

Note: Checkbox validators will be called once for each <input> element, regardless of checked state. Radio validators will only be called with either the first or the checked <input> element.

Parameters:

Name	Type	Description
`field`	{string\|Element}	the form field or name
`validator`	{function}	the validator function

Source:

RapidContext_Widget_Form.js, line 210

blurAll()

Blurs (unfocuses) this DOM node and all relevant child nodes. This function will recursively blur all <a>, <button>, <input>, <textarea> and <select> child nodes found.

Inherited From:: RapidContext.Widget#blurAll
Source:: RapidContext_Widget.js, line 475

destroy()

The internal widget destructor function. This method should only be called by destroyWidget() and may be overridden by subclasses. By default this method does nothing.

Inherited From:: RapidContext.Widget#destroy
Source:: RapidContext_Widget.js, line 198

disable()

Disables this widget if it was previously enabled. This method is equivalent to calling setAttrs({ disabled: true }).

Inherited From:: RapidContext.Widget#disable
Source:: RapidContext_Widget.js, line 420

emit(event, optsopt) → {boolean}

Dispatches a single event from this DOM node. Also creates a new CustomEvent instance if needed.

Parameters:

Name Type Attributes Description

event {string/Event} the event type name or instance

opts

{Object}

the event options

Properties

Name	Type	Attributes	Default	Description
`async`	{boolean}	<optional>	true	the async dispatch flag
`bubbles`	{boolean}	<optional>		the event bubbles flag
`cancelable`	{boolean}	<optional>		the cancellable event flag
`detail`	{Object}	<optional>		the additional event details

Returns:

{boolean} true if event was async or not cancelled

Inherited From:

RapidContext.UI.Event#emit

Source:

rapidcontext/ui/event.mjs, line 26

enable()

Enables this widget if it was previously disabled. This is equivalent to calling setAttrs({ disabled: false }).

Inherited From:: RapidContext.Widget#enable
Source:: RapidContext_Widget.js, line 412

fieldMap() → {Object}

Returns a map with all child DOM nodes containing form fields with a name attribute. If multiple fields have the same name, the returned map will contain an array with all matching fields.

Returns:: {Object} the map of form field elements
Source:: RapidContext_Widget_Form.js, line 128

fields() → {Array}

Returns an array with all child DOM nodes containing form fields.

Returns:: {Array} the array of form field elements
See:: https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements
Source:: RapidContext_Widget_Form.js, line 115

getChildNodes() → {Array}

Returns an array with all child DOM nodes. Note that the array is a real JavaScript array, not a dynamic NodeList. This method is sometimes overridden by child widgets in order to hide intermediate DOM nodes required by the widget.

Returns:: {Array} the array of child DOM nodes
Inherited From:: RapidContext.Widget#getChildNodes
Source:: RapidContext_Widget.js, line 487

hasClass(…cls) → {boolean}

Checks if this HTML DOM node has the specified CSS class names. Note that more than one CSS class name may be checked, in which case all must be present.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to check

Returns:

{boolean} true if all CSS classes were present, or false otherwise

Inherited From:

RapidContext.Widget#hasClass

Source:

RapidContext_Widget.js, line 311

hide()

Hides this widget node if it was previously visible. This method is equivalent to calling setAttrs({ hidden: true }). It is safe for all types of widgets, since it only adds the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#hide
Source:: RapidContext_Widget.js, line 466

isDisabled() → {boolean}

Checks if this widget is disabled. This method checks both the "widgetDisabled" CSS class and the disabled property. Changes to the disabled status can be made with enable(), disable() or setAttrs().

Returns:: {boolean} true if the widget is disabled, or false otherwise
Inherited From:: RapidContext.Widget#isDisabled
Source:: RapidContext_Widget.js, line 391

isHidden() → {boolean}

Checks if this widget node is hidden. This method checks for the existence of the widgetHidden CSS class. It does NOT check the actual widget visibility (the display style property set by animations for example).

Returns:: {boolean} true if the widget is hidden, or false otherwise
Inherited From:: RapidContext.Widget#isHidden
Source:: RapidContext_Widget.js, line 433

off(eventopt, selectoropt, listeneropt) → {Node}

Removes one or more previously attached event listeners. If no event details or listeners are specified, all matching handlers are removed.

Parameters:

Name	Type	Attributes	Description
`event`	{string}	<optional>	the event type name (or space separated names)
`selector`	{string}	<optional>	the CSS selector to match for event target
`listener`	{function}	<optional>	the event handler function (or `false`)

Returns:

{Node} the input DOM node (for chaining calls)

Inherited From:

RapidContext.UI.Event#off

Source:

rapidcontext/ui/event.mjs, line 77

on(event, selectoropt, listener, optsopt) → {Node}

Attaches a listener function for one or more events.

Parameters:

Name Type Attributes Description

event {string} the event type name (or space separated names)

selector {string} <optional> the CSS selector to match for event target

listener {function} the event handler function (or false)

opts

{Object}

the event listener options (see addEventListener)

Properties

Name	Type	Attributes	Description
`delay`	{number}	<optional>	an inactivity delay before calling listener

Returns:

{Node} the input DOM node (for chaining calls)

Inherited From:

RapidContext.UI.Event#on

Source:

rapidcontext/ui/event.mjs, line 44

once(event, selectoropt, listener, optsopt) → {Node}

Attaches a single event listener function. The listener will be removed the first time an event is triggered.

Parameters:

Name Type Attributes Description

event {string} the event type name (or space separated names)

selector {string} <optional> the CSS selector to match for event target

listener {function} the event handler function (or false)

opts

{Object}

the event listener options (see addEventListener)

Properties

Name	Type	Attributes	Description
`delay`	{number}	<optional>	an inactivity delay before calling listener

Returns:

{Node} the input DOM node (for chaining calls)

Inherited From:

RapidContext.UI.Event#once

Source:

rapidcontext/ui/event.mjs, line 60

removeAll()

Removes all children to this widget. This method will also destroy and child widgets and disconnect all signal listeners. This method uses the getChildNodes() and removeChildNode() methods to find and remove the individual child nodes.

Inherited From:: RapidContext.Widget#removeAll
Source:: RapidContext_Widget.js, line 547

removeChildNode(child)

Removes a single child DOM node from this widget. This method is sometimes overridden by child widgets in order to hide or control intermediate DOM nodes required by the widget.

Note that this method will NOT destroy the removed child widget, so care must be taken to ensure proper child widget destruction.

Parameters:

Name	Type	Description
`child`	{Widget\|Node}	the DOM node to remove

Inherited From:

RapidContext.Widget#removeChildNode

Source:

RapidContext_Widget.js, line 518

removeClass(…cls)

Removes the specified CSS class names from this HTML DOM node. Note that this method will not remove any class starting with "widget".

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Inherited From:

RapidContext.Widget#removeClass

Source:

RapidContext_Widget.js, line 349

removeValidators(fieldopt)

Removes all custom form validators for a named form field.

Parameters:

Name	Type	Attributes	Description
`field`	{string\|Element}	<optional>	the form field, name, or null for all

Source:

RapidContext_Widget_Form.js, line 221

reset()

Resets all fields and validations to their original state.

Source:: RapidContext_Widget_Form.js, line 142

setAttrs(attrs)

Updates the widget or HTML DOM node attributes. This method is sometimes overridden by individual widgets to allow modification of additional widget attributes.

Parameters:

Name Type Description

attrs

{Object}

the widget and node attributes to set

Properties

Name	Type	Attributes	Description
`disabled`	{boolean}	<optional>	the disabled widget flag
`hidden`	{boolean}	<optional>	the hidden widget flag
`class`	{string}	<optional>	the CSS class names

Inherited From:

RapidContext.Widget#setAttrs

Source:

RapidContext_Widget.js, line 235

setStyle(styles)

Updates the CSS styles of this HTML DOM node. This method is identical to MochiKit.Style.setStyle, but uses "this" as the first argument.

Parameters:

Name	Type	Description
`styles`	{Object}	an object with the styles to set

Inherited From:

RapidContext.Widget#setStyle

Example:

widget.setStyle({ "font-size": "bold", "color": "red" });

Source:

RapidContext_Widget.js, line 288

show()

Shows this widget node if it was previously hidden. This method is equivalent to calling setAttrs({ hidden: false }). It is safe for all types of widgets, since it only removes the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#show
Source:: RapidContext_Widget.js, line 456

toggleClass(…cls) → {boolean}

Toggles adding and removing the specified CSS class names to and from this HTML DOM node. If all the CSS classes are already set, they will be removed. Otherwise they will be added.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Returns:

{boolean} true if the CSS classes were added, or false otherwise

Inherited From:

RapidContext.Widget#toggleClass

Source:

RapidContext_Widget.js, line 372

uid() → {string}

Returns the unique identifier for this DOM node. If a node id has already been set, that id will be returned. Otherwise a new id will be generated and assigned to the widget DOM node.

Returns:: {string} the the unique DOM node identifier
Inherited From:: RapidContext.Widget#uid
Source:: RapidContext_Widget.js, line 186

update(values)

Updates the fields in this form with a specified map of values. If multiple fields have the same name, the value will be set to all of them.

Parameters:

Name	Type	Description
`values`	{Object}	the map of form field values

Source:

RapidContext_Widget_Form.js, line 178

validate() → {boolean}

Validates this form using the form validators found.

Returns:: {boolean} true if the form validated successfully, or false if the validation failed
Source:: RapidContext_Widget_Form.js, line 265

validateReset()

Resets all form validations. This method is automatically called when form is reset.

See:: #reset
Source:: RapidContext_Widget_Form.js, line 298

validators() → {Array}

Returns an array with all child DOM nodes containing form validator widgets.

Returns:: {Array} the array of form validator widgets
Source:: RapidContext_Widget_Form.js, line 255

valueMap() → {Object}

Returns a map with all form field values. If multiple fields have the same name, the value will be set to an array of all values. Disabled fields and unchecked checkboxes or radiobuttons will be ignored.

Returns:: {Object} the map of form field values
Source:: RapidContext_Widget_Form.js, line 158