Tutorial - Change field colors, values and attributes with custom logic conditions

[telecastg]

This tutorial describes how to use the free plug-in dynamic-control to take advantage of Espo's dynamic handler class to write code in one script that can specify highly customized conditions to change fields visibility, read-only value, is-required value, enum options, background and text color, field value, etc in one script.

The example used for this tutorial is an entity called "Inspection" which represents an inspection event for rental properties that are contractually subject to be inspected periodically.

The inspection entity has 3 fields that we want to manipulate in its detail (form) display as follows:

1. Field "status" - enum class field:
GUI specifications:
If the user is Admin, options available are ("Open", "Resolved" and "Canceled")
If the user is not Admin, options available are only ("Open" and "Resolved")
Is read-only for everyone except for users that are Admin or users that have the role "Maintenance Coordinator"

2. Field "toDoList" - dynamic checklist class field: (custom field, free plug in can be downloaded here: https://github.com/telecastg/dynamic...st-for-espocrm )
GUI specifications:
Is read-only if "status" = "Resolved";
Is only visible for users that are Admin or that belong to team "Maintenance"

3. Field "type" - enum class field:
Options are ("Annual", "New Tenancy", "Second", "Third")
GUI specifications:
Background and text colors vary depending on the field value as follows:
Option value = "Annual", background = green, text = black
Option value = "New Tenancy", background = yellow, text = black
Option value = "Second", background = orange, text = black
Option value = "Third", background = red, text = white

To achieve this we need first to download the dynamic-control plugin https://github.com/telecastg/dynamic...ol-for-espocrm

Then create script client/custom/scr/inspection-dynamic-handler.js with this code:

define('custom:inspection-dynamic-handler', ['dynamic-control:enhanced-dynamic-handler'], function (Dep) {

  return Dep.extend({

    init: function () {
      // this dynamic logic implementation will use User attributes as conditions to trigger effects
      this.applyUserAttributes = true;
      // this dynamic logic implementation will include changes to a field css if conditions are met
      this.applyCssDirectives = true;
      // run the prototype init() function which will invoke the controlFields function on initial rendering
      Dep.prototype.init.call(this);
      // run the controlFields() funtion every time the model is updated
      var self = this;
      this.recordView.listenTo(this.model, 'change', function () {
        self.controlFields();
      }, this);
      // it is also possible to invoke the controlFields method when a particular field changes like this:
      // this.recordView.listenTo(this.model, 'change:status', this.statusControlField.bind(this));
    },

    controlFields: function () {
      // regulate the appearance and properties of the 'status' field
      this.statusControlField();
      // regulate the appearance and properties of the 'toDoList' field
      this.toDoListControlField();
      // regulate the appearance and properties of the 'type' field
      this.typeControlField();
    },

    statusControlField: function () {
      // make the "status" field readonly unless the User is admin or has the role "Maintenance Coordinator"
      // properties isUserAdmin and userRoles were defined in the protoype class enhanced-dynamic-handler
      if(!this.isUserAdmin && !~this.userRoles.indexOf('MaintenanceCoordinator') ) {
        this.recordView.setFieldReadOnly('status');
      }
      // limit the enum choices for the "status" field to "Open" or "Resolved" if the user is not admin
      if(!this.isUserAdmin) {
        this.recordView.setFieldOptionList('status', ['Open', 'Resolved']);
      } else {
        this.recordView.setFieldOptionList('status', ['Open', 'Resolved', 'Canceled']);
      }
    },

    toDoListControlField: function() {
      // make the 'toDoList' field readonly if:
      // the 'status' is 'Canceled' or 'Resolved' or the user is a portal user
      if(this.model.get('status') === 'Canceled' || this.model.get('status') === 'Resolved' || this.isUserPortal) {
        this.recordView.setFieldReadOnly('toDoList');
      } else {
        this.recordView.setFieldNotReadOnly('toDoList');
      }
    },

    typeControlField: function() {
      // set the 'type' field backgound and text colors according to its value
      // type = 'Annual', background color = green, text color = black
      // type = 'New Tenancy', background color = yellow, text color = black
      // type = 'Second', background color = orange, text color = black
      // type = 'Third', background color = red, text color = white
      var cssParam = '';
      if(this.model.get('type') === 'Annual') {
        cssParam = 'background-color:#91ff01;';
      } else if(this.model.get('type') === 'New Tenancy') {
        cssParam = 'background-color:yellow;';
      } else if(this.model.get('type') === 'Second') {
        cssParam = 'background-color:orange;';
      } else if(this.model.get('type') === 'Third') {
        cssParam = 'background-color:red;color:white;';
      }
      // use the prototype setFieldCss method to change the backgorund and text color of the field
      if(cssParam) {
        this.setFieldCss('type',cssParam);
      }
    }
});
});

The next step is to let Espo know that we want to use the custom dynamic-handler script for the "Inspection" entity and we do that in the "Inspection" clientDefs metadata script:
custom/Espo/Custom/Resources/metadata/clientDefs/Inspection.json

"dynamicHandler": "custom:inspection-dynamic-handler",

Last step is to clear cache and rebuid.

The entity detail display will look like the attached screen shot.

[telecastg]

This is how the detail screen looks when a user is Admin

[esforim]

Always cool to see a screenshot.

[item]

Thanks telecastg always great

[telecastg]

You're welcome

[telecastg]

New version of the enhanced-dynamic-logic free plug in released includes the ability to enable or disable inline edit for any field based on logical conditions written in the entity's dynamic-handler.

https://github.com/telecastg/enhance...ic-for-espocrm

https://github.com/espocrm/documenta...mic-handler.md

[item]

@telecast "enable or disable inline edit for any field based on logical conditions" .. it's crazy man .. you have just send a skud missile here

Respect

[telecastg]

Renamed plug-in released, performing the same actions described here (enhanced dynamic handler) and compatible with Espo 6+

https://github.com/telecastg/dynamic...ol-for-espocrm

[telecastg]

UPDATE: Unfortunately this extension has become obsolete due to the extensive code refactoring in Espo 7+

The files are no longer available in GitHub.

[dodom2]

telecastg have you had any luck with any recent espo versions? We're looking to implement several rules and would like to highlight the field based on logic. Thanks!

[telecastg]

Hello @dodom2,

You can modify any field appearance programmatically using the dynamic handler class

https://docs.espocrm.com/development/dynamic-handler/