Coding Tutorial: How to create a custom field

**telecastg** · 02-22-2021, 08:35 PM

This tutorial will describe how to modify an existing field type (checklist) so the label appears to the left of the checkbox instead of to the right.

In order to keep our code better organized, instead of using the "Custom" namespace we will encapsulate the new field type in a "MyFields" Module.

We will name this field "label-left-checklist" and our modules namespaces will be "MyFields" for back-end code and "my-fields" for front-end code.

Step 1:
Create the new field metadata definition, copying the code from the original checklist field but specifying our own front-end view class (see Step 2) that will render the field.
application/Espo/Modules/MyFields/Resources/metadata/fields/label-left-checklist.json

Code:

{
     "view":"my-fields:views/fields/label-left-checklist",

    "params": [
        {
            "name": "required",
            "type": "bool",
            "default": false
        },
        {
            "name": "options",
            "type": "array",
            "view": "views/admin/field-manager/fields/options",
            "noEmptyString": true,
            "required": true
        },
        {
            "name":"isSorted",
            "type":"bool"
        },
        {
            "name": "translation",
            "type": "varchar",
            "hidden": true
        },
        {
            "name": "maxCount",
            "type": "int",
            "min": 1
        },
        {
            "name": "audited",
            "type": "bool"
        },
        {
            "name": "readOnly",
            "type": "bool"
        }
    ],
    "validationList": [
        "array",
        "required",
        "maxCount"
    ],
    "mandatoryValidationList": [
        "array"
    ],
    "filter": true,
    "notCreatable": false,
    "notSortable": true,
    "fieldDefs": {
        "type":"jsonArray",
        "storeArrayValues": true
    },
    "translatedOptions": true,
    "dynamicLogicOptions": true,
    "personalData": true
}

Step 2:
Create the new field class view class, extended from the original field view class, defining a new field type property and calling for custom templates
client/modules/my-fields/src/views/fields/label-left-checklist.js

Code:

define('my-fields:views/fields/label-left-checklist', ['views/fields/checklist'], function (Dep) {

    return Dep.extend({

        type: "label-left-checklist",

        detailTemplate: 'my-fields:fields/label-left-checklist/detail',

        editTemplate: 'my-fields:fields/label-left-checklist/edit'

    });
});

Step 3:
Create the custom templates that will be used to display the field in the "detail" and "edit" modes. IF YOU CUT AND PASTE THE FOLLOWING CODE PLEASE NOTE THAT THE EXTRA SPACES BETWEEN < AND > CHARACTERS SHOULD BE ELIMINATED (I only had to put them because the forum's markdown converts the characters to "HTML safe" < and > )

client/modules/my-fields/res/templates/fields/label-left-checklist/detail.tpl
Copy the code from the original template (client/res/templates/fields/checklist/detail.tpl), reversing the display of the checkbox and the label elements

Code:

{{#each optionDataList}}
    < div class="checklist-item-container" >
         < span style="display:inline-block;width:85%;" >
            < label for="{{id}}" class="checklist-label" > {{label}} < / label >
        < / span>
        < span style="display:inline-block;width:10%;" >
            < input type="checkbox" data-name="{{dataName}}" id="{{id}}" {{#if isChecked}} checked{{/if}} disabled="disabled" >
        < / span >
    < / div >
{{/each}}
{{#unless optionDataList.length}}{{translate 'None'}}{{/unless}}

client/modules/my-fields/res/templates/fields/label-left-checklist/edit.tpl
Copy the code from the original template (client/res/templates/fields/checklist/edit.tpl), reversing the display of the checkbox and the label elements

Code:

{{#each optionDataList}}
    < div class="checklist-item-container" >
        < span style="display:inline-block;width:85%;" >
            < label for="{{id}}" class="checklist-label" > {{label}} < / label >
        < / span>
        < span style="display:inline-block;width:10%;" >
            < input type="checkbox" data-name="{{dataName}}" id="{{id}}" {{#if isChecked}} checked{{/if}} >
        < / span>
    < / div >
{{/each}}
{{#unless optionDataList.length}}{{translate 'None'}}{{/unless}}

Step 4:
Create a language file to make your custom field name "human friendly" for display in the Admin module in your preferred language (In this case we will make the json script for en_US)
application/Espo/Modules/MyFields/Resources/i18n/en_US/Admin.json

Code:

{
    "fieldTypes": {
        "label-left-checklist": "Label Left Checklist"
    }
}

Step 5:
Clear cache and rebuild Admin > Rebuild

Now you will be able to add this field for any entity through the Admin GUI

If you want to substitute an existing "checklist" field with this field, go to the target entity's entityDefs metadata file and change the "type" from "checklist" to "left-label-checklist"