It is instructive to briefly examine HTML forms and patterns involving
them, before we dive into the details of Obviel forms and how these
patterns are implemented.

A HTML form consists of a HTML form element. Inside the form
element are various input, textarea and select elements
describing the fields of the form that the user can fill in. In
addition there are one or more button or submit input elements
that let the user submit the form, or cancel the submission. More
complex JavaScript asssisted input widgets may also exist, for
instance to allow the user to enter a date.

When the form is submitted, it is sent to a particular URL, identified
with the action attribute on the form tag. This initiates a
form submission. The entered data are encoded, either in the URL if
the form is submitted with a GET request, or in a form data format
when doing a POST submission.

The web server software or web framework on the server side that you
use knows how to decode the form data, and then hands it to your
application in some way, to take an action: for instance to add a
record to a database.

When browser submits a form to the action URL, the action URL also
sends back a HTML response, which the browser then displays. This can
contain the results of the form processing.

An add form is used to add new information to the application: a blog
entry, someone’s address, or whatever else is relevant to the
application domain. Add forms are empty when they are displayed first:
its fields are either empty or have a default value in them that the
user can alter.

An edit form is used to change existing information in the
application: change a blog entry, modify your user account data, and
so on. Edit forms are shown filled-in when you open them: the fields
show the information that you are about to change, and allows you to
modify them.

When a form is submitted, a form needs to be validated: for instance
checking whether a number is in range, or a text input is not too
long, or a list is one of several allowed values. A very common
validation is to make sure a required value was filled in at all.

When a form is submitted, form data also needs to be converted: for
instance, numbers are inputed as text strings, and need to be
converted to actual numbers that the underlying application can deal
with. A checkbox may be turned into a true/false value, and a date
string needs to be parsed into a date object. Conversion needs to take
place before validation can take place.

Conversion and validation can be client-side or server-side.

Client-side validation, typically in JavaScript, lets the form give
instant feedback to the user that is fillin in the form, before the
user even submits the form. This increases the usability of the form,
as the user does not need to wait for a relatively long submit/reload
cycle in order to get this information. Client-side validation does
not ensure that the user really inputs the allowed information
however.

Server-side validation has the benefit of being secure: the server can
validate that the data entered by the client is really allowed by the
application. This is important especially if the web application faces
the public.

A traditional pattern of doing HTML forms is doing no client-side
validation at all except for what is offered by bare HTML, and doing
all the validation on the server. To display validation errors a
round-trip procedure is required, where the whole form is submitted to
the server. If conversion or validation failed, the whole form is
shown again showing validation errors, along with any values the user
previously filled in.

Advanced form patterns involve composite and repeating fields. A
composite field is a field composed out of other fields. An example of
a composite field is a date field that consists of three fields
allowing you to enter the year, month and day separately from each
other. A repeating field is a field where a list of values (sub-forms)
needs to be entered. A form where you enter the crew of a ship for
instance should allow you to enter more than one crew member, adding
as many as you need.

In a form system without client-side code, a repeating field requires
a complicated round-trip with the server. The server needs to have a
sophisticated system for decoding nested data structures from the flat
HTML form-data that’s been submitted by the client, and also a system
for generating nested forms.

If this JSON is assigned to an object form in JavaScript, this is how
we would render this form in an element somewhere on the page:

el.render(form);

The form would have one field, test, with the value Somevalue
filled in (from the data object). The form would also have a
submit button labeled Submit.

When the user changes the form, the data object will be
automatically updated.

The test field is required. This means that a validation error
will appear inline if the user attempts to submit the form without
filling in this field, and submission will not proceed. Validation is
handled on the client side.

Conversion is also performed partially on the client-side: an
integerField will convert to a JavaScript number for instance,
and a booleanField to a JavaScript true or false value.

Further conversion and validation can be performed on the server-side.
Conversion is done to cast a value into one more convenient for the
server-side: a date string may be converted into a date object, for
instance. Validation after form submission on the server side is
entirely restricted to validation for security purposes and not used
for feedback purposes: is the JSON structure received actually
legitimate considering the constraints of the form? In that case there
is either an attempted security breach or an error, and server side
form handling should not proceed. Since these situations should not
occur in normal usage, there is no mechanism for server-side
validation error reporting. (A mechanism for server-assisted
client-side inline validation is however provided: a form may have a
global validation URL that will validate the data object and
return validation errors for it in a JSON structure. This information
is then used by the client to supplement the inline validation
procedure)

When the user presses the submit button on the form, the data
object will be submitted as JSON to the control’s action URL, in
this case http://example.com/submit.

Nested and repeating structures come naturally to Obviel forms: a
nested field’s data is simply a sub-object of data, and a
repeating field’s data is an array of sub-objects.

When Obviel Forms sets an error message (either field-error or
global-error) for a field, or clears such an error message, an event
is sent to the element on which the message is set. The event names are:

field-error.obviel-forms: a field error is set

field-error-clear.obviel-forms: a field error is cleared

global-error.obviel-forms: a global error is set

global-error-clear.obviel-forms: a global error is cleared

These events bubble up the DOM, so you can bind to these events on a
higher level, such as the form or the document. The event object
passed to the handler has a target property that can be used to
retrieve the element on which the message was set.

You can override the way the error area per fields looks by
registering a view on the special obvielFormsErrorArea
iface. You need to do this after the obviel-forms file has been
included. In it you should make sure of creating two elements which
can contain text content that have the id this.obj.fieldErrorId
and this.obj.globalErrorId, so that the errors can be rendered.