Standard components / FormField

Try a working example of FormFieldComponent and then see the code for the example.

This is a basic component for form fields, from which most other form field components should inherit from. The important thing that it does, it defines a value_holder concept - a part inside the DOM-structure that actually holds the value (an input) and is being submitted when the form is submitted. It is needed because very often the presentation (html) of a form field in real-world application may actually consist of a number of html-elements (thin field + label + hint underneath the field + error hints all wrapped by a parent <div>).

It also introduces some basic form field functionality that is used by all inheriting components. Let's go over all of that one by one.

Value holder

In its most basic form, a form field dom structure may actually consist of just a single html element - <input>, which itself will be the value holder. FormFieldComponent implements a two-way binding between the html element's value and component's value attribute. Thus, if user types something into the field, the component's attribute is updated immediately (on each keyup or change) event. Regardless of the structure of the html for your component, value holder is identified by the data-component-part="value_holder" attribute attached to the respective element. Webface will programattically add data-component-attr="value" to bind the html-element's value to the component's value attribute.

Normally, in order to bind html attribute, such as value="" to some component's attribute, you'd need to add data-component-attr-map="value:value", but the value attribute is a special case: when Webface sees it on an <input> and that input also has data-component-attr="value" it will bind to the .value property of that html-element automatically.

Publishing the change event

Whenever the value attribute changes, either through user input, or programmatically, by calling FormFieldComponent.set("value", ...) a change event is published by the component. This is convenient if your component is a child of some form component which, say, interactively reacts to changes in its fields and does something in response. For instance, we can imagine such a form component to show additional fields if user enters 2 in the "number of children" field.

Resetting the field

A field can be reset to its initial value - the one that was assigned during component initialization. Just call FormFieldComponent.reset(). A change event will also be published by the component upon a reset.

ATTENTION: initial value is not previous value! If you want to set a previous value, you can do it by using the FormFieldComponent.previous_value property (note: it's not an attribute, but actual object property) and write something like form_field.set("value", form_field.previous_value);

Validations

If you have an element with the data-component-attr="validation_errors_summary" attribute such as <div data-component-attr="validation_errors_summary" class="errorsSummary"></div>, then upon running validations with FormFieldComponent.validate() it will automatically add error messages into that html-element and the corresponding component validation_errors_summary property, because validation_errors_summary is declared as an attribute in FormFieldComponent.

Other attributes

There a couple of attributes each FormFieldComponent instance (or an instance of its descendant class) is supposed to have.

  • name which corresponds to the name="" html attribute of the form field. This is obviously useful when you're submitting a form: a browser needs to know field's name in order to send the value to the server.
  • disabled which corresponds to the disable="disabled" html attribute.
In order for those to work, you need not forget to set attribute map on the <input> html-element: