Announcement

Collapse
No announcement yet.

Reference: Espo GUI - script map guide, where can I change something ?

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

  • Reference: Espo GUI - script map guide, where can I change something ?

    The idea of this thread is to create a "road map/guide" to help developers find where GUI sections or elements are defined within Espo code so customization projects can be implemented without having to spend a lot of time "finding your way around" the code (like many of us have done) whenever possible.

    This is by no means an "official" guide, it's more of compilations of some things that I have found, so it is quite possible that some might not be exactly accurate in which case I welcome any corrections and additions.

    For starters, here is a basic map of what views control screen sections in both, the record list and detail display.

    Record List Display
    Click image for larger version  Name:	Record List View with labels.png Views:	0 Size:	35.6 KB ID:	61110

    Record Detail Display
    Click image for larger version  Name:	Record Detail View with labels.png Views:	0 Size:	57.7 KB ID:	61112
    To customize any of these sections, you need to create a script extended from these default views and then modify the custom entity's clientDefs metadata file to specify the custom views that are to be used like this:
    Code:
    {
        "views": {
            "list": "views/list", (or your custom view name),
            "detail": "views/detail" (or your custom view name)
        },
        "recordViews": {
            "list": "views/record/list", (or your custom view name)
            "detail": "views/record/detail" (or your custom view name)
        }
    }
    If you don't specify a view file, Espo uses the default views.

    I will post more "maps" as we work on our own development.

    Cheers

    Attached Files
    Last edited by telecastg; 08-01-2020, 04:06 AM.

  • #2
    Yes this is awesome!

    Comment


    • #3
      How to customize the Side Menu / Navbar

      Side Menu (or Top Menu for some themes)
      Click image for larger version  Name:	Navbar View with label.png Views:	0 Size:	39.3 KB ID:	61130

      1) Create a custom navbar view class:
      client/custom/scr/views/navbar.js
      Code:
      define('custom:views/site/navbar', 'views/site/navbar', function (Dep) {
      
          return Dep.extend({
      
              // write your custom code here, override functions, specify custom templates, etc
      
          });
      });
      2) Create a custom metadata file to let Espo know that it needs to use the custom view instead of the system default view
      custom/Espo/Custom/Resources/metadata/clientDefs/App.json
      Code:
      {
          "navbarView": "custom:views/site/navbar"
      }
      3) Clear cache and rebuild.

      Comment


      • #4
        telecastg, thank you so much for taking the time to put this together, another useful post!

        Comment


        • #5
          Yes thanks again

          Comment


          • #6
            Great stuff. Hope everyone can do their own GUI using the given guides. Appreciate if others also can post their findings to the forum.

            Comment


            • #7
              How to customize the Home view / landing page after login

              From:

              Click image for larger version  Name:	Home View.png Views:	16 Size:	38.1 KB ID:	61333
              To:
              Click image for larger version  Name:	Custom Home View.PNG Views:	14 Size:	35.0 KB ID:	61335
              The core script client/src/views/home.js allows us to call a custom view to render a custom home page as follows:

              1) Create a custom clientDefs metadata script that will tell Espo to call a custom script to render a custom home page instead of the default dashboard display
              custom/Espo/Custom/Resources/metadata/clientDefs/Home.json
              Code:
              {
                  "iconClass": "fas fa-archway",  (you can change the icon next to the "Home" menu option here)
                  "view": "custom:views/test" (specify the view that will render the custom display)  
              }
              2) Create a view script to render the custom display as "Home" page
              client/custom/src/views/test.js
              Code:
                  define('custom:views/test', 'view', function (Dep) {
              
                      return Dep.extend({
              
                          template: 'custom:test',
              
                          data: function () {
                              return {
                                  testMessage: "Welcome to Espo"
                              };
                          }
                      });
                  });
              3) Create a custom template for the view above
              client/custom/res/templates/test.tpl
              Code:
              <div class="home-content"><h1>{{{testMessage}}}</h1></div>
              4) Clear cache and rebuild.
              Attached Files
              Last edited by telecastg; Yesterday, 07:21 AM.

              Comment


              • #8
                Any idea where this file is?

                Update: I believe it is this file: https://github.com/espocrm/espocrm/b...mail/detail.js


                tag: GUI_;email; drop down
                Last edited by espcrm; 08-10-2020, 07:26 AM.

                Comment


              • #9
                How are new records created from a list display / what happens when I click the "Create" button at the top right corner in a list of records display ?
                Click image for larger version  Name:	Create Record from List Display.png Views:	0 Size:	19.6 KB ID:	61399
                1) As mentioned before, unless specified otherwise in the scope's (entity type) clientDefs metadata file, this area of the GUI is controlled by the client/src/views/list.js script.

                2) Clicking the "Create" button at client/src/views/list.js triggers the function "actionCreate" in that script.
                https://github.com/espocrm/espocrm/b...s/list.js#L415

                3) The function "actionCreate" at client/src/views/list.js then, triggers a router call to invoke "actionCreate" at client/src/controllers/record.js (same function name but in different scripts) https://github.com/espocrm/espocrm/b...record.js#L209, which is the front-end controller class for the scope, unless a different controller is specified at the scope's clientDefs like this:
                Code:
                 "controller": "(write here the name of the custom controller)",
                4) The function "actionCreate" at client/src/controllers/record.js will in turn invoke the function "create" at the same script which will actually create a new model instance and will render a form (edit view) to enter and save the new entity's values.

                5) The default edit view is client/src/views/record/edit.js https://github.com/espocrm/espocrm/b...record/edit.js, unless specified otherwise at the scope's clientDefs like this
                Code:
                 "recordViews": {
                    "edit": "(name of custom view class)",
                },

                How can I modify the record create process for an entity without modifying the core code to make my changes "upgrade safe" ?

                1) Create a custom front end controller extended from for your scope (entity) and modify the "actionCreate" function to reflect your changes. For example, create a custom front end controller for a CollectionIssue entity:
                Code:
                Espo.define('custom:controllers/collection-issue', 'controllers/record', function (Dep) {
                
                    return Dep.extend({
                
                        // customized create function
                        create: function (options) {
                            // copy the code from the prototype script (client/src/controllers/record.js) and make changes as required
                        },
                    });
                });
                2) Modify the entity's clientDefs metadata file (in this example custom/Espo/Custom/Resources/metadata/clientDefs/CollectionIssue.json)
                {
                "controller": "
                custom:controllers/collection-issue",
                }

                3) If you want to modify something in the actual form where the new entity values are entered, create a custom edit view for the entity, extended from the original client/src/views/record/edit.js script
                Code:
                Espo.define('custom:views/collection-issue/record/edit', 'views/record/edit', function (Dep) {
                
                    return Dep.extend({
                
                        // make any changes here, for example specify a custom template, add buttons to the form, etc
                
                    });
                });
                4) Let Espo know that a custom view needs to be called for editing the entity at the entity's clientDefs metadata file (in this example custom/Espo/Custom/Resources/metadata/clientDefs/CollectionIssue.json)
                {
                "recordViews": {
                "edit": "
                custom:views/collection-issue/record/edit"
                },
                }
                Last edited by telecastg; 08-10-2020, 07:59 PM.

                Comment


                • #10
                  How is a Kanban list display generated ?
                  Click image for larger version  Name:	kanban list view.png Views:	5 Size:	30.9 KB ID:	61453
                  1) The area above the record display area, as previously indicated, is controlled by default by the script client/src/views/list.js and clicking the "kanban" icon invokes the function switchViewMode() with "kanban" as parameter at this script.
                  https://github.com/espocrm/espocrm/blob/96c598d4542ce23d18937378b8ddcb83f639fa6f/client/src/views/list.js#L210

                  2) The function switchViewMode("kanban"), then invokes the function setViewMode("kanban") which then invokes another function setViewModeKanban()
                  https://github.com/espocrm/espocrm/b...s/list.js#L241

                  3) After setViewModeKanban() is finished, function switchViewMode("kanban") then calls the function loadlist() https://github.com/espocrm/espocrm/b...s/list.js#L299 which then invokes the function createListRecordView().

                  4) createListRecordView() function https://github.com/espocrm/espocrm/b...s/list.js#L316 creates the kanban display based on the view class specified in the target scope (in this example ServiceTicket) clientDefs metadata under the property "recordViews" > "kanban" or the class client/src/views/record/kanban.js https://github.com/espocrm/espocrm/b...cord/kanban.js
                  Last edited by telecastg; Today, 06:32 AM.

                  Comment

                  Working...
                  X