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

[telecastg]

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


Record Detail Display

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:

{
    "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.

For an example of how views other than default are used, see the Contact clientDefs metadata file
https://github.com/espocrm/espocrm/b...ontact.json#L4

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

Cheers

Update: The top part of the screen, where the search box and notification icon are, is actually controlled by client/src/views/site/navbar.js, see below how that script can be customized "upgrade safe".

Update: To see a more detailed breakdown of the view classes involved in a "detail" display see this post: https://forum.espocrm.com/forum/deve...-s-detail-view

[crmclients]

Yes this is awesome!

[telecastg]

How to customize the Side Menu / Navbar

Side Menu (or Top Menu for some themes)


1) Create a custom navbar view class:
client/custom/scr/views/navbar.js

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

{
    "navbarView": "custom:views/site/navbar"
}

3) Clear cache and rebuild.

[Paulina]

Hi, I created custom navbar view class in client/custom/scr/views/navbar.js and I have one event which I want to execute on Icon click. It is working fine but then I cant log out from the system. Do you have any ideas why?

define('custom:views/site/navbar', 'views/site/navbar', function(Dep) {
    return Dep.extend({
        afterRender: function() {
            Dep.prototype.afterRender.call(this);

            this.$navbar.find('ul.nav.navbar-nav.navbar-right').append(
                '<a style="cursor: pointer;" class="top-nav-envelope"><i class="fas fa-envelope"></i></a>'
            );
        },

		setup: function() {
            Dep.prototype.setup.call(this);

        },

        events: {
            'click a[class="top-nav-envelope"]': function(e) {
                this.notify('Loading...');

            },
        }


    });


});

[Redwood]

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

[crmclients]

Yes thanks again

[Nishan Perera]

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

[telecastg]

How to customize the Home view / landing page after login

From:

To:

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

{
    "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

    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

<div class="home-content"><h1>{{{testMessage}}}</h1></div>

4) Clear cache and rebuild.

[esforim]

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

[telecastg]

Yes, here's the bookmark for the function that generates the dropdown:

https://github.com/espocrm/espocrm/blob/master/client/src/views/email/detail.js#L58

[telecastg]

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 ?

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:

 "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

 "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:

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

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"
},
}

How to remove the Create button in list display ?
Open the entity's clientDefs metadata file (in this case custom/Custom/Espo/Custom/Resources/clientDefs/CollectionIssue.json) and set the "createDisabled" flag to "true"

{
    "createDisabled" : true
}

[telecastg]

How is a Kanban list display generated ?

Clicking on the "Kanban" icon invokes the function setViewMode() with "kanban" as parameter at the script client/src/views/record/search.js which triggers the general program flow below:

Script	Function	Reference
client/src/views/record/search.js	setViewMode()	https://github.com/espocrm/espocrm/b...search.js#L195
client/src/views/list.js	switchViewMode('kanban')	https://github.com/espocrm/espocrm/b...s/list.js#L210
	setViewMode("kanban")	https://github.com/espocrm/espocrm/b...s/list.js#L219
	setViewModeKanban()	https://github.com/espocrm/espocrm/b...s/list.js#L241
application/Espo/Resources/routes.json		https://github.com/espocrm/espocrm/b...utes.json#L127
application/Espo/Core/Controllers/Record.php	getActionListKanban()	https://github.com/espocrm/espocrm/b...ecord.php#L156
application/Espo/Services/Record.php	getListKanban()	https://github.com/espocrm/espocrm/b...cord.php#L1226
client/src/views/list.js	loadlist()	https://github.com/espocrm/espocrm/b...s/list.js#L299
	createListRecordView()	https://github.com/espocrm/espocrm/b...s/list.js#L316
client/src/views/record/kanban.js	init()	https://github.com/espocrm/espocrm/b...kanban.js#L119
	setup()	https://github.com/espocrm/espocrm/b...kanban.js#L142
	buildRows()	https://github.com/espocrm/espocrm/b...kanban.js#L404
	getListLayout()	https://github.com/espocrm/espocrm/b...kanban.js#L381
	getSelectAttributeList()	https://github.com/espocrm/espocrm/b...kanban.js#L381
client/src/views/record/list.js	getSelectAttributeList()	https://github.com/espocrm/espocrm/b.../list.js#L1202
	fetchAttributeListFromLayout()	https://github.com/espocrm/espocrm/b.../list.js#L1222
client/src/collection.js	fetch()	https://github.com/espocrm/espocrm/b...ection.js#L140
client/src/views/record/kanban.js	data()	https://github.com/espocrm/espocrm/b...kanban.js#L102
	afterRender()	https://github.com/espocrm/espocrm/b...kanban.js#L225
	initSortable()	https://github.com/espocrm/espocrm/b...kanban.js#L307
	initStikableHeader()	https://github.com/espocrm/espocrm/b...kanban.js#L245

[telecastg]

How is a subscription created when I click the "Follow" button at the top right corner of a record detail display ?



Clicking the button above triggers the function actionFollow() at the script client/src/views/detail.js which makes an Ajax call to create a "Subscription" record that links the User with the Entity.

actionFollow: function () {
    this.disableMenuItem('follow');

    Espo.Ajax.putRequest(this.model.name + '/' + this.model.id + '/subscription')
    .then(function () {
        this.removeMenuItem('follow', true);
        this.model.set('isFollowed', true);
    }.bind(this))
    .fail(function () {
        this.enableMenuItem('follow');
    }.bind(this));
},

[telecastg]

How is the the "Home" Dashboard created ?

Clicking on the "Home" menu option triggers the following general program flow:

The controller class dashboard.js is invoked and this class invokes then the view class dashboard.js

The view gets a list of dashlets (by name) and how are they configured (layout) according to the user preferences, if allowed in the system settings, or as specified by the administrator.

For each dashlet contained in the list above, the dashboard view class gets the dashlet specifications from the dashlet metadata file (for example: custom/Espo/Custom/Resources/metadata/dashlets/RentalProspects.json) and then creates a view for each dashlet panel using the client/src/views/dashlet.js class.

The actual content inside the dashlet panel is rendered by the view class specified in the dashlet metadata. For example for a list of entities, the default view class is: client/src/views/dashlets/abstract/record-list.js

Script	Function	Reference
client/src/controllers/dashboard.js	index()	https://github.com/espocrm/espocrm/b...shboard.js#L33
client/src/views/dashboard.js	setup()	https://github.com/espocrm/espocrm/b...hboard.js#L177
	setupCurrentTabLayout()	https://github.com/espocrm/espocrm/b...hboard.js#L120
	data()	https://github.com/espocrm/espocrm/b...hboard.js#L106
	afterRender()	https://github.com/espocrm/espocrm/b...hboard.js#L213
	initGridstack()	https://github.com/espocrm/espocrm/b...hboard.js#L287
	prepareGridstackItem()	https://github.com/espocrm/espocrm/b...hboard.js#L378
	createDashletView()	https://github.com/espocrm/espocrm/b...hboard.js#L492
client/src/views/dashlet.js	setup()	https://github.com/espocrm/espocrm/b...dashlet.js#L74
	getTitle()	https://github.com/espocrm/espocrm/b...ashlet.js#L145

[esforim]

Any idea where which file to update these Label color/type? I want to be more colorful.

[telecastg]

The styles enumerated are usually defined by the Bootstrap theme.

You could create custom css classes with a different color scheme and apply those custom classes instead of the pre-defined above to the enum options.

This is the code that manages the enum field option styles https://github.com/espocrm/espocrm/b...h-style.js#L38

However, making any changes to this script would not be upgrade safe. I haven't customized anything in the Admin module so I can't tell if its possible to use custom scripts to substitute admin namespace scripts.

[telecastg]

How is a record list display generated when I click on its navbar (side menu) option ?

When a navbar menu option is clicked, Espo checks the core "application/Espo/Resources/routes.json" script values:
https://github.com/espocrm/espocrm/b...es/routes.json (or potential custom values in custom routes.json scripts, if specified) and invokes the front-end controller and function requested.

The front-end controller is by default client/src/controllers/record.js or can overridden in the entity's clientDefs metadata file, and will follow the general program flow below:

Script	function	Reference
application/Espo/Resources/routes.json		https://github.com/espocrm/espocrm/b...utes.json#L256
client/src/controllers/record.js	initialize()	https://github.com/espocrm/espocrm/b.../record.js#L44
	beforeList()	https://github.com/espocrm/espocrm/b.../record.js#L54
	checkAccess()	https://github.com/espocrm/espocrm/b.../record.js#L37
	actionList()	https://github.com/espocrm/espocrm/b.../record.js#L58
	getCollection()	https://github.com/espocrm/espocrm/b...record.js#L300
client/src/collection.js	initialize()	https://github.com/espocrm/espocrm/b...lection.js#L53
	setOrder()	https://github.com/espocrm/espocrm/b...ection.js#L205
	getWhere()	https://github.com/espocrm/espocrm/b...ection.js#L184
	fetch()	https://github.com/espocrm/espocrm/b...ection.js#L140
application/Espo/Core/Controllers/Record.php	actionList()	https://github.com/espocrm/espocrm/b...ecord.php#L117
	fetchListParamsFromRequest()	https://github.com/espocrm/espocrm/b...ecord.php#L182
application/Espo/Core/Utils/ControllerUtil.php	fetchListParamsFromRequest()	https://github.com/espocrm/espocrm/b...erUtil.php#L34
application/Espo/Services/Record.php	find()	https://github.com/espocrm/espocrm/b...cord.php#L1172
client/src/collection.js	parse()	https://github.com/espocrm/espocrm/b...ection.js#L128
client/src/controllers/record.js	getViewName()	https://github.com/espocrm/espocrm/b.../record.js#L50
client/src/views/list.js	setup()	https://github.com/espocrm/espocrm/b...ws/list.js#L69
	setViewMode()	https://github.com/espocrm/espocrm/b...s/list.js#L219
	loadList()	https://github.com/espocrm/espocrm/b...s/list.js#L299
	createListRecordView()	https://github.com/espocrm/espocrm/b...s/list.js#L316
client/src/controller.js	main()	https://github.com/espocrm/espocrm/b...roller.js#L254

[tothewine]

Great job here telecastg ! This is a very useful reference for modding espo. You are doing God's work!!!

[telecastg]

Thanks tothewine :-)