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 and uniquely selectable using a CSS selector (for ease an id attribute often used):

• template (since 3.0) - the template element is ideal for this use case as the browser will not display the template, so you won't see a flash of unstyled content as the page is initialised. The contents of the template are cloned and used as the template for the form.
• Any other element (typically a div will be used though). This element will be detached from the DOM when Editor is initialised, and then used as the form template (i.e. it is not cloned, the original element is used).

To tell Editor where to find your template, use the template option set to be a selector that will pick the template from the document.

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

<template id="usersForm">
    <div>
        <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>
</template>

To initialise Editor with this template you would use:

const editor = new DataTable.Editor({
    template: '#usersForm',
    // ... fields, etc
});

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 demo packages if you would like to run it locally and experiment with the pre-defined code.