Announcement

Collapse
No announcement yet.

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

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

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

    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:

    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
    Code:
    "dynamicHandler": "custom:inspection-dynamic-handler",
    Last step is to clear cache and rebuid.

    The entity detail display will look like the attached screen shot.
    Last edited by telecastg; 03-29-2021, 12:59 AM. Reason: Changed link to point out to newest version of the extension

  • #2
    This is how the detail screen looks when a user is Admin

    Comment


    • espcrm
      espcrm commented
      Editing a comment
      Always cool to see a screenshot.

  • #3
    Thanks telecastg always great

    Comment


    • telecastg
      telecastg commented
      Editing a comment
      You're welcome

  • #4
    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

    Comment


    • item
      item commented
      Editing a comment
      @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

  • #5
    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
    Last edited by telecastg; 01-20-2021, 04:28 AM.

    Comment


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

      The files are no longer available in GitHub.

      Comment

    Working...
    X