Creating custom layouts with the Form Builder

Introduction

This article demonstrates how to create a more precise Form Builder layout that correctly aligns controls in rows. For example, this image shows multiple rows with three fields aligned per row.

Using standard layouts, this is not possible. Controls are associated with zones (or containers) in the layout, and these zones are filled with the controls based on their display order. This means that even if you were to create a standard 3-column layout like this:

<div>
  <div class="row">
    <div class="col-sm-4 layout-left"></div>
    <div class="col-sm-4 layout-mid"></div>
    <div class="col-sm-4 layout-right"></div>
  </div>
</div>

The layout would not let the three controls for each row line up correctly as the labels would be added to layout-left, the drop-down control to layout-mid, and the text input to layout-right.

How to manage a control's position

To manage the position of each control and make them line up correctly in rows, you need to provide the Form Builder with a custom layout. In the custom layout, you create divisions to contain the controls.

The three items you need are:

A custom layout produced in the IDE
A global CSS include added via the IDE
A form definition to reference the layout and specify the position in the layout for the controls

Custom layout in the IDE

The custom layout shown as an example in the code block below defines 5 rows and 3 columns. Perform the following steps to create the layout.

To open the IDE, click Launchpad > Open Modeller > Developer > Developer IDE

Either create a new folder or choose an existing one.
Create a new HTML file in the chosen folder by clicking the three vertical dots next to the folder name and selecting New file.
Enter a filename with an extension of html, like in the image above: AdvFormBuilder-layout.html.
Define your layout containers in the new file.
1. The overall layout is a <div> tag with a class of your layout style defined in the CSS. In this example, the class is afb-layout.
2. Each row has its own div tag with class="row".
3. Each column position is defined as a div tag.
4. Save the file.

The first row here is defined as a header row with column titles:

Title
Option
Memo

Subsequent rows are defined with container positions. E.g., layout-r1-left is the first column (left) of the first row (r1), layout-r2-mid is the second column (mid) of the second row (r2), etc.

Note: col-sm-4 refers to columns in the Bootstrap CSS framework and is beyond the scope of this article. Briefly, Bootstrap divides the page into 12 columns, and we group those into 3 groups of 4.

Example layout HTML file:

<div class="afb-layout">
    <div class="row">
        <div class="col-sm-4"><b>Title</b></div>
        <div class="col-sm-4"><b>Option</b></div>
        <div class="col-sm-4"><b>Memo</b></div>
    </div>
    <div class="row">
        <div class="col-sm-4 layout-r1-left"></div>
        <div class="col-sm-4 layout-r1-mid"></div>
        <div class="col-sm-4 layout-r1-right"></div>
    </div>
    <div class="row">
        <div class="col-sm-4 layout-r2-left"></div>
        <div class="col-sm-4 layout-r2-mid"></div>
        <div class="col-sm-4 layout-r2-right"></div>
    </div>
    <div class="row">
        <div class="col-sm-4 layout-r3-left"></div>
        <div class="col-sm-4 layout-r3-mid"></div>
        <div class="col-sm-4 layout-r3-right"></div>
    </div>
    <div class="row">
        <div class="col-sm-4 layout-r4-left"></div>
        <div class="col-sm-4 layout-r4-mid"></div>
        <div class="col-sm-4 layout-r4-right"></div>
    </div>
    <div class="row">
        <div class="col-sm-4 layout-r5-left"></div>
        <div class="col-sm-4 layout-r5-mid"></div>
        <div class="col-sm-4 layout-r5-right"></div>
    </div>
</div>

Global CSS include to fix styling issues

The CSS defines how the Form Builder renders the form in our new layout. To create the CSS file, perform the following steps:

Create a new CSS file in the same folder as the HTML file you just created by clicking the three vertical dots next to the folder name and selecting New file.
Enter a filename with an extension of css, like in the image earlier: AFB.css.
Add the following code and save the file.

div.afb-layout label
{
    display:none;
}

div.afb-layout div.form-group > .col-sm-1,
div.afb-layout div.form-group > .col-sm-2,
div.afb-layout div.form-group > .col-sm-3,
div.afb-layout div.form-group > .col-sm-4,
div.afb-layout div.form-group > .col-sm-5,
div.afb-layout div.form-group > .col-sm-6,
div.afb-layout div.form-group > .col-sm-7,
div.afb-layout div.form-group > .col-sm-8,
div.afb-layout div.form-group > .col-sm-9,
div.afb-layout div.form-group > .col-sm-10,
div.afb-layout div.form-group > .col-sm-11,
div.afb-layout div.form-group > .col-sm-12
{
    float: none;
    width: auto;
    padding: 0;
}

The defaults for how the Form Builder places labels and sizes controls make the layout look odd. This CSS fixes that but specifically targets the layout only (note the afb-layout qualifier).

This CSS is included globally via an IDE scaffolded global include manifest. In the same way as before, create a file with a json extension like in the image earlier: AFB.global.json. In the “styles” section, put the path to your CSS file. Save the file.

{
    "scripts":
    [
    ],
    "styles":
    [
        "/_ideFiles/AdvancedFormBuilder/AFB.css"
    ],
    "widgets":
    [
    ]
}

Find the path to your CSS file by clicking the 3 dots next to it in the IDE and selecting Open raw in new window.

A new browser window opens, showing the CSS file. The path you need is everything after your domain name (marked here in bold): https://training.sharedo.co.uk/_ideFiles/AdvancedFormBuilder/AFB.css

Form definition reference

Finally, you need to define a form that references this new layout. The example below:

References the new layout: /_ideFiles/AdvancedFormBuilder/AdvFormBuilder-layout.html
Adds the controls to individual cells in the layout - note the various layoutLocation attributes referencing .layout-r1-mid, layout-r2-mid, etc.

Define the form using the Form Builder: Modeller > Forms and views > Form Builder definitions

For information on how to use the Form Builder, see the article and video at Form Builder Overview.

Form Builder definition example

{
    "id": "87dd2d58-e3b4-42c9-8b88-81a4ceabe105",
    "systemName": "advanced-form-builder",
    "title": "Advanced Forms",
    "description": "An example of an advanced form with 3 columns and multiple rows.",
    "layout": "/_ideFiles/AdvancedFormBuilder/AdvFormBuilder-layout.html",
    "layoutParent": "bootstrap-edit-horizontal",
    "showTitle": true,
    "readonly": false,
    "fields": [
        {
            "id": "e2a200e4-867a-4c46-9547-64885ebbde82",
            "type": 7,
            "name": "adv-form-LabelField1",
            "title": "LabelField1",
            "description": "This is a lable for the ADV form.",
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r1-left",
            "displayOrder": 0,
            "attributes": {
                "labelText": "First choice",
                "cssClasses": ""
            }
        },
        {
            "id": "8f3e2498-1b9f-4daa-bacb-38c9bb7e4712",
            "type": 4,
            "name": "OptionSetField1",
            "title": "Option Set Field",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r1-mid",
            "displayOrder": 1,
            "attributes": {
                "optionSetName": "appointment-types",
                "allowNoSelection": true,
                "multiple": false,
                "placeholderText": "Pick an option",
                "showSelectedColour": false,
                "showSelectedIcon": false
            }
        },
        {
            "id": "8b1255e1-638f-4b93-ad20-1f6417fac786",
            "type": 12,
            "name": "adv-form-MemoField1",
            "title": "This is an example",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r1-right",
            "displayOrder": 2,
            "attributes": {
                "rows": 3,
                "richText": true,
                "maxLength": 50,
                "showMaxLengthIndicator": true,
                "requiredOnlyInPhases": "some-phase"
            }
        },
        {
            "id": "007a0baa-bb02-439a-8ea6-09ee8afc26fa",
            "type": 7,
            "name": "adv-form-LabelField2",
            "title": "LabelField2",
            "description": "This is a lable for the ADV form.",
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r2-left",
            "displayOrder": 3,
            "attributes": {
                "labelText": "Second choice",
                "cssClasses": ""
            }
        },
        {
            "id": "3876a0b2-5ec1-4cf9-ab74-f8e73f1e528c",
            "type": 4,
            "name": "OptionSetField2",
            "title": "Option Set Field",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r2-mid",
            "displayOrder": 4,
            "attributes": {
                "optionSetName": "appointment-court-types",
                "allowNoSelection": true,
                "multiple": false,
                "placeholderText": "Pick an option",
                "showSelectedColour": false,
                "showSelectedIcon": false
            }
        },
        {
            "id": "53278296-45be-47c9-a0a3-a329ab72a0c3",
            "type": 12,
            "name": "adv-form-MemoField2",
            "title": "This is an example",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r2-right",
            "displayOrder": 5,
            "attributes": {
                "rows": 3,
                "richText": true,
                "maxLength": 50,
                "showMaxLengthIndicator": true,
                "requiredOnlyInPhases": "some-phase"
            }
        },
        {
            "id": "e9e053fd-1deb-4593-ad46-1f151df0cc68",
            "type": 7,
            "name": "adv-form-LabelField3",
            "title": "LabelField3",
            "description": "This is a lable for the ADV form.",
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r3-left",
            "displayOrder": 6,
            "attributes": {
                "labelText": "Third choice",
                "cssClasses": ""
            }
        },
        {
            "id": "69f0e14e-51f2-4411-ace0-3378dba17bf8",
            "type": 4,
            "name": "OptionSetField3",
            "title": "Option Set Field",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r3-mid",
            "displayOrder": 7,
            "attributes": {
                "optionSetName": "allocation-behaviour",
                "allowNoSelection": true,
                "multiple": false,
                "placeholderText": "Pick an option",
                "showSelectedColour": false,
                "showSelectedIcon": false
            }
        },
        {
            "id": "7f677cc9-21cf-4b48-8d49-22c242b37e7c",
            "type": 12,
            "name": "adv-form-MemoField3",
            "title": "This is an example",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r3-right",
            "displayOrder": 8,
            "attributes": {
                "rows": 3,
                "richText": true,
                "maxLength": 50,
                "showMaxLengthIndicator": true,
                "requiredOnlyInPhases": "some-phase"
            }
        },
        {
            "id": "562ddb13-9ae7-4181-a990-9127069f74af",
            "type": 7,
            "name": "adv-form-LabelField4",
            "title": "LabelField4",
            "description": "This is a lable for the ADV form.",
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r4-left",
            "displayOrder": 9,
            "attributes": {
                "labelText": "Fourth choice",
                "cssClasses": ""
            }
        },
        {
            "id": "8a816a39-a448-4c10-afcd-7ff57b0425f4",
            "type": 4,
            "name": "OptionSetField4",
            "title": "Option Set Field",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r4-mid",
            "displayOrder": 10,
            "attributes": {
                "optionSetName": "aderant-action-codes",
                "allowNoSelection": true,
                "multiple": false,
                "placeholderText": "Pick an option",
                "showSelectedColour": false,
                "showSelectedIcon": false
            }
        },
        {
            "id": "4bbc9678-b5ae-4153-b1f9-bda2a9702842",
            "type": 12,
            "name": "adv-form-MemoField4",
            "title": "This is an example",
            "description": null,
            "readonly": false,
            "required": false,
            "layoutLocation": ".layout-r4-right",
            "displayOrder": 11,
            "attributes": {
                "rows": 3,
                "richText": true,
                "maxLength": 50,
                "showMaxLengthIndicator": true,
                "requiredOnlyInPhases": "some-phase"
            }
        }
    ],
    "sections": [],
    "smartVariableSystemName": null
}

Review

In this article, you learned how to create a custom layout for forms defined in the Form Builder. The layout used as the example placed three controls in a row over three columns.

The resulting form: