Templates

Forms can provide users with the ability to input and control complex information, and every hint that provides the user with information about what data is expected can provide significant benefits in terms of speed of correct entry. The layout of a form is one element of this, giving grouping information for related fields and prioritisation. Editor supports complex layouts through its template option, allowing you to define any DOM structure to match your form.

Editor's default layout is a simple linear display of the fields that have been defined, and while that is often good enough for forms with a limited set of inputs, if you have a large number of inputs or a complex form, you will want to be able to display the form inputs elements as you wish.

HTML template

The key to using a template for Editor is to define the HTML structure for the form in your document. This HTML should be contained within a single element (typically a div, but any could be used) and uniquely selectable using a jQuery selector (typically an id attribute is used). While this HTML is in your regular document, Editor will remove it and use that element in its own form. This is done by using the template option, which should be given as a selector for the template element.

Consider for example the case where we want to group similar fields together - this is a perfect use case for the fieldset element:

<div id="usersForm">
    <fieldset class="name">
        <legend>Name</legend>

        ... fields
    </fieldset>
    <fieldset class="office">
        <legend>Office</legend>

        ... fields
    </fieldset>
    <fieldset class="hr">
        <legend>HR info</legend>

        ... fields
    </fieldset>
</div>

Inserting fields

We need to tell Editor where to insert the fields into the template. Can be done using one of:

• Custom elements
• Data attributes (requires 1.6.2+).

Custom elements

Editor can search for HTML5 custom elements called editor-field. This element must have a name attribute that defines the field that should be shown there (matching the fields.name option defined for the field when created).

Expanding the above example we might have:

<div id="usersForm">
    <fieldset class="name">
        <legend>Name</legend>

        <editor-field name="first_name"></editor-field>
        <editor-field name="last_name"></editor-field>
    </fieldset>
    <fieldset class="office">
        <legend>Office</legend>

        <editor-field name="office"></editor-field>
        <editor-field name="extn"></editor-field>
    </fieldset>
    <fieldset class="hr">
        <legend>HR info</legend>

        <editor-field name="position"></editor-field>
        <editor-field name="salary"></editor-field>
        <editor-field name="start_date"></editor-field>
    </fieldset>
</div>

The field that Editor inserts will contain the full DOM structure for that field. Meaning that labels, messages, error messages, etc will all be shown inside the template without any additional configuration.

Data attributes

As of Editor 1.6.2 Editor can also determine where a field should be inserted into a template through the use of the data-editor-template attribute. Unlike the editor-field element the field will be inserted info the element that has this attribute, so a div is typically used for this. Using attributes can be useful if you want to be able to validate HTML strictly, without requiring any configuration for custom tags.

Reusing the above example, but this time with data-editor-template attributes we have:

<div id="usersForm">
    <fieldset class="name">
        <legend>Name</legend>

        <div data-editor-template="first_name"/>
        <div data-editor-template="last_name"/>
    </fieldset>
    <fieldset class="office">
        <legend>Office</legend>

        <div data-editor-template="office"/>
        <div data-editor-template="extn"/>
    </fieldset>
    <fieldset class="hr">
        <legend>HR info</legend>

        <div data-editor-template="position"/>
        <div data-editor-template="salary"/>
        <div data-editor-template="start_date"/>
    </fieldset>
</div>

Any HTML!

The important point to make with templates is that you are not restricted to any particular layout for your field. You could readily use Bootstrap's tabs if you wanted a tab layout, an accordion or any other layout you wish to use.

If your layout HTML requires Javascript events, make sure you add those events before initialising Editor, as Editor will remove the template element from the DOM until it is required.

CSS customisation

Alongside your custom HTML, you will very likely wish to define your own CSS to style the form. Flex box is a popular way for laying out complex elements, quickly and easily, but really its up to you how you style the form!

Lightbox customisation

When laying out complex forms, you might want to have a little more width for the form to take up in the display. The width of Editor's built in lightbox control (lightbox) can be customised using the following CSS (modified to suit your needs of course):

div.DTED_Lightbox_Wrapper {
    width: 800px;
    margin-left: -400px;
}

The full DOM structure for the lightbox is defined in the styling manual if you wish to customise it further.

Inline and bubble editing

At this time only the primary form display supports layout templates. Inline and bubble editing (inline() and bubble()) do not support template layouts as they are designed specifically to be used with only a single field in the case of inline editing and a small number of fields for bubble editing.

Example

A live example of Editor's template layout feature is available on this site, and is included in the PHP and .NET download packages if you would like to run it locally and experiment with the pre-defined code.