Announcement

Collapse
No announcement yet.

Coding Tutorial: How to create a custom field

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

  • Coding Tutorial: How to create a custom field

    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.

    Click image for larger version  Name:	label-left-lchecklist.PNG Views:	31 Size:	5.6 KB ID:	67980

    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" &lt; and &gt; )

    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"
    Last edited by telecastg; 02-28-2021, 07:19 AM.
Working...
X