New forms' generator

Since 1.3 release.

Overview

Having some kind of the automatic form generator makes the rapid service development easier and allows us to focus on more important things (like application's business logic) than boring building HTML form from small input bricks. However, leaving the responsibility for the form generating to some generic engine can easily cut us off from the possibilities of customizing the outlook of the form.

The previous version of the form generator (let's name it old forms) made some uncomfortable assumptions that we could not accept in the new forms. Let's take a look what the New Forms brings.

Form's layout

During the form generation process we have distinguished two major parts of the form:

container - the surrounding part of the form - the one that keeps all input together and allows us to easily change the style of all contained inputs.
element - the basic entity representing the particular field from the model

The element can now be split into four next parts:

label - short description that tells us what's the particular element is responsible of
input - the HTML input area - the place where we should enter some data/check some fields/choose something from a list
comment - some text describing the meaning of the field (if the label is not clear enough), its limitations (like minimum length of the password) or format (e.g. the date format)
error - in case of badly entered data, the descriptive error message referring to the particular field, saying what is wrong with the entered data

The last two parts (comment and error) are optional and will not be displayed if they does not contain any data.

Each form entity has its own, defined class and unique ID so it is possible to define a nice formatting style that will display the form to the user:

Part type	HTML class	ID
container	form_container	model's name
element	form_entry	model's field name
input	form_input	model's field name
comment	form_comment	model's field name ++ "_comment"
error	form_error	model's field name ++ "_error"

New Forms' types

The Old Forms generator could create only the single table that was containing the whole form inside (one row held one field). Unfortunately, it turned out that the tables are hard to maintain, it is almost impossible to suit them to our needs (CSS) and are rather heavy. Because of that, together with the New Forms we are ready to introduce the four new types of the HTML forms.

The generated forms have the following structure (the uppercased words are replaced with the proper HTML elements/text):

table

Form:

<table class="form_container" id="FORM ID">
   ELEMENTS' PLACEHOLDER
</table>

Element:

<tr>
        <th scope="row">
            <label for="ID">LABEL</label>
        </th>
        <td>
            <span class="form_input">INPUT</span>
        </td>
</tr>
<tr>
        <td>
                <span class="form_comment" id="ID_comment">COMMENT</span>
                <span class="form_error" id="ID_error">ERROR</span>
        </td>
</tr>

paragraph

Form:

<p class="form_container" id="ID">
   ELEMENTS' PLACEHOLDER
</p>

Element:

<p id="ID" class="form_entry">
     <label for="ID">LABEL
            <span class="form_error" id="ID_error">ERROR</span>
            <span class="form_comment" id="ID_comment">COMMENT</span>
     </label>
     <span class="form_input">INPUT</span>
</p>

div

Form:

<div class="form_container" id="ID">
    ELEMENTS' PLACEHOLDER
</div>

Element:

<div id="ID" class="form_entry">
     <label for="ID">LABEL
            <span class="form_error" id="ID_error">ERROR</span>
            <span class="form_comment" id="ID_comment">COMMENT</span>
     </label>
     <span class="form_input">INPUT</span>
</div>

list

Form:

<ul class="form_container" id="ID">
    ELEMENTS' PLACEHOLDER
</ul>

Element:

<li id="ID" class="form_entry">
     <label for="ID">LABEL
            <span class="form_error" id="ID_error">ERROR</span>
            <span class="form_comment" id="ID_comment">COMMENT</span>
     </label>
     <span class="form_input">INPUT</span>
</li>

Additional features

Moreover, since 1.2.1 release, it is possible to specify any of the HTML attributes for the input tag. To achieve this, the html_attrs property must be set in the model's definition:

   1 login = {string, [{description, "Login"},
   2                   {comment, "<i>The e-mail address you used during the registration</i>"},
   3                   {html_attrs, [{size, 30}, {tabindex, 1}]}]},

As we see, the LABEL placeholder is filled with description property and the COMMENT is replaced with the value of comment. Moreover, the input tag will have two additional attributes: size="30" tabindex="1" .

Using the New Forms

Using the New Forms is as easy as using the Old Forms. In order to render the HTML form on our page, we should use one of the following tag:

wpart:form

wpart:form tag creates a nice form - with the form tag, submit button and - in case of using upload basic type - adds the multipart clause to the list of form attributes.

wpart:form 's specification:

<wpart:form form_type="FORM_TYPE" action="ACTION" type="TYPE" submit_text="SUBMIT_TEXT" />

where:
FORM_TYPE = table | paragraph | div | list (default: div)
ACTION = URL for the POST request
TYPE = model's type we want to render the form for
SUBMIT_TEXT = text that should be displayed on the submit button

wpart:input

wpart:input tag creates only the container and its elements - without creating the form tag and the submit button. It is useful when we want to mix a few models in one form.

wpart:input 's specification:

<wpart:input form_type="FORM_TYPE" type="TYPE" />

where both FORM_TYPE and TYPE have the same meaning as in wpart:form

wpart:derived

wpart:derived creates a set of the element tags - without the container that surrounds them (like the set of table rows without the surrounding table).

wpart:derived 's specification:

<wpart:derived form_type="FORM_TYPE" type="TYPE" long_name="LONG_NAME" />

where both FORM_TYPE and TYPE have the same meaning as in wpart:form and
LONG_NAME = prefix that would be used for the particular element's ids (by default set to "")