Tweet
Tutorial - Control values of a multiple link depending on another multiple link
THIS TUTORIAL IS ONLY APPLICABLE TO ESPO VERSIONS BEFORE 6
Introduction
This tutorial describes the steps necessary to control the list of options displayed for a multiple link field (used when entities are related in a many-to-many relationship) based on the existing options selected for another multiple link field.
Please note that while adapting this tutorial to your application should not require extensive coding, it is not an installable extension at this point. It does require to create the front-end and back-end scripts described here, create/ modify metadata json files, and requires a basic understanding of creating entities and relationships (through the Admin panel is OK), basic javascript and PHP coding knowledge, and basic familiarity with Espo's architecture and database structure.
This tutorial is not suitable for users who might prefer not to do any customization beyond what is already available via the Administration UI.
Use case description
In this example, dealing with a property rental business, an entity called "WorkOrder" is used to control the execution of maintenance work required to satisfy a customer request.
When a "WorkOrder" is received, a Maintenance Coordinator determines the "Skill" (another entity) or list of skills required to complete the work (represented in a field "skills" of the "WorkOrder").
After those skills are selected from a list of skills that the organization has defined, then the Maintenance Coordinator needs choose from a list of service technicians ("ServiceTech" entity), one or more that posses one or more of the required skills, and assign those technicians to the work order.
For example: If a work order requires the skills "plumbing" and "painting", only those service technicians that posses plumbing or painting skills will be listed for the user to choose from.
The above entities and relationships can be defined in the Admin > Entity Manager panel are as follows:
"WorkOrder", linked to "Skill" in a many-to-many relationship
"Skill", linked to "ServiceTech" in a many-to-many relationship
When you create the above entities and relationships, Espo generates the necessary tables and the database schema will look like the diagram below:
Please note the labels in red color assigned to each table in the image above, these are names that we will use to refer to each table further in this tutorial.
Step 1
After the appropriate entities and relationships have been created, open the script custom/Espo/Custom/Resources/metadata/entityDefs/WorkOrder.json (generated by Espo when you created the entities and relationships described above), look for the section "fields" sub-section "serviceTechs" and add the line "view": "custom:views/fields/link-multiple-conditional" as shown below.
This line will tell Espo to use the custom class client/custom/src/views/fields/link-multiple-conditional.js (shown in Step 3 below) to render the field "serviceTechs" when displaying the "WorkOrder" record in detail view.
Step 2
Open the script custom/Espo/Custom/Resources/metadata/clientDefs/ServiceTech.json. (This script should have also been generated by Espo when you created the entities and relationships described above) and add the code below:
This code is telling Espo two things:
a) To use a custom view class client/custom/src/views/modals/select-records-filtered.js (shown in Step 4 below) when rendering a list of "Service Techs" to choose from in a modal view that will open when the user wants to add a Service tech to the Work Order entity.
b) To use the specifications under the section "linkFilter" to build the SQL statement that will filter the list of Service Techs available depending on the skill or skills required by the Work Order. Notice how the schema red labels used in the image above are used in this section to define the actual names and fields of the database tables.
Step 3
Create a custom field class client/custom/src/views/fields/link-multiple-conditional.js using the code below:
Note the line // console.log("custom link-multiple-conditional this.model = ",this.model); in the script above. This will display a message in the browser's console if un-commented to help with trouble shooting. If displayed it will signal that the script is being called properly so the code entered in Step 1 is working fine.
Because of the 10,000 character limit for postings in this forum, this tutorial will continue in Part 2 https://forum.espocrm.com/forum/deve...-multiple-link and Part 3 https://forum.espocrm.com/forum/deve...p/60642-part-3
Introduction
This tutorial describes the steps necessary to control the list of options displayed for a multiple link field (used when entities are related in a many-to-many relationship) based on the existing options selected for another multiple link field.
Please note that while adapting this tutorial to your application should not require extensive coding, it is not an installable extension at this point. It does require to create the front-end and back-end scripts described here, create/ modify metadata json files, and requires a basic understanding of creating entities and relationships (through the Admin panel is OK), basic javascript and PHP coding knowledge, and basic familiarity with Espo's architecture and database structure.
This tutorial is not suitable for users who might prefer not to do any customization beyond what is already available via the Administration UI.
Use case description
In this example, dealing with a property rental business, an entity called "WorkOrder" is used to control the execution of maintenance work required to satisfy a customer request.
When a "WorkOrder" is received, a Maintenance Coordinator determines the "Skill" (another entity) or list of skills required to complete the work (represented in a field "skills" of the "WorkOrder").
After those skills are selected from a list of skills that the organization has defined, then the Maintenance Coordinator needs choose from a list of service technicians ("ServiceTech" entity), one or more that posses one or more of the required skills, and assign those technicians to the work order.
For example: If a work order requires the skills "plumbing" and "painting", only those service technicians that posses plumbing or painting skills will be listed for the user to choose from.
The above entities and relationships can be defined in the Admin > Entity Manager panel are as follows:
"WorkOrder", linked to "Skill" in a many-to-many relationship
"Skill", linked to "ServiceTech" in a many-to-many relationship
When you create the above entities and relationships, Espo generates the necessary tables and the database schema will look like the diagram below:
Please note the labels in red color assigned to each table in the image above, these are names that we will use to refer to each table further in this tutorial.
Step 1
After the appropriate entities and relationships have been created, open the script custom/Espo/Custom/Resources/metadata/entityDefs/WorkOrder.json (generated by Espo when you created the entities and relationships described above), look for the section "fields" sub-section "serviceTechs" and add the line "view": "custom:views/fields/link-multiple-conditional" as shown below.
This line will tell Espo to use the custom class client/custom/src/views/fields/link-multiple-conditional.js (shown in Step 3 below) to render the field "serviceTechs" when displaying the "WorkOrder" record in detail view.
Code:
"fields": {
// there might be some other code here describing other fields
"serviceTechs": {
"type": "linkMultiple",
[COLOR=#f39c12][B]"view": "custom:views/fields/link-multiple-conditional",[/B][/COLOR]
"layoutDetailDisabled": false,
"layoutMassUpdateDisabled": false,
"importDisabled": false,
"noLoad": false,
"isCustom": true
}
// there might be some other code here describing other fields
}
Open the script custom/Espo/Custom/Resources/metadata/clientDefs/ServiceTech.json. (This script should have also been generated by Espo when you created the entities and relationships described above) and add the code below:
Code:
{
// there might be some other code here describing other client definitions
"modalViews" : {
[B][COLOR=#f39c12]"select": "custom:views/modals/select-records-filtered"[/COLOR][/B]
},
"linkFilter" : {
"[B][COLOR=#c0392b]modelTable[/COLOR][/B]": "work_order",
"[COLOR=#c0392b][B]modelCriteriaTable[/B][/COLOR]": "work_order_skill",
"[COLOR=#c0392b][B]criteriaTable[/B][/COLOR]": "skill",
"[COLOR=#c0392b][B]criteriaTargetTable[/B][/COLOR]": "skill_service_tech",
"[COLOR=#c0392b][B]targetTable[/B][/COLOR]": "service_tech",
"[COLOR=#c0392b][B]modelKey[/B][/COLOR]": "id",
"[COLOR=#c0392b][B]modelReferenceKey[/B][/COLOR]": "work_order_id",
"[COLOR=#c0392b][B]criteriaKey[/B][/COLOR]": "id",
"[COLOR=#c0392b][B]criteriaReferenceKey[/B][/COLOR]": "skill_id",
"[COLOR=#c0392b][B]targetKey[/B][/COLOR]": "id",
"[COLOR=#c0392b][B]targetReferenceKey[/B][/COLOR]": "service_tech_id"
}
}
a) To use a custom view class client/custom/src/views/modals/select-records-filtered.js (shown in Step 4 below) when rendering a list of "Service Techs" to choose from in a modal view that will open when the user wants to add a Service tech to the Work Order entity.
b) To use the specifications under the section "linkFilter" to build the SQL statement that will filter the list of Service Techs available depending on the skill or skills required by the Work Order. Notice how the schema red labels used in the image above are used in this section to define the actual names and fields of the database tables.
Step 3
Create a custom field class client/custom/src/views/fields/link-multiple-conditional.js using the code below:
Code:
Espo.define('custom:views/fields/link-multiple-conditional', 'views/fields/link-multiple', function (Dep) {
return Dep.extend({
setup: function() {
// console.log("custom link-multiple-conditional this.model = ",this.model);
this.nameHashName = this.name + 'Names';
this.idsName = this.name + 'Ids';
this.foreignScope = this.options.foreignScope || this.foreignScope || this.model.getFieldParam(this.name, 'entity') || this.model.getLinkParam(this.name, 'entity');
if ('createDisabled' in this.options) {
this.createDisabled = this.options.createDisabled;
}
var self = this;
if (this.mode == 'search') {
var nameHash = this.getSearchParamsData().nameHash || this.searchParams.nameHash || {};
var idList = this.getSearchParamsData().idList || this.searchParams.value || [];
this.nameHash = Espo.Utils.clone(nameHash);
this.ids = Espo.Utils.clone(idList);
} else {
this.copyValuesFromModel();
}
this.listenTo(this.model, 'change:' + this.idsName, function () {
this.copyValuesFromModel();
}, this);
this.sortable = this.sortable || this.params.sortable;
this.iconHtml = this.getHelper().getScopeColorIconHtml(this.foreig nScope);
if (this.mode !== 'list') {
this.addActionHandler('selectLink', function () {
// display modal list of entities that can be linked
self.notify('Loading...');
var viewName = this.getMetadata().get('clientDefs.' + this.foreignScope + '.modalViews.select') || this.selectRecordsView;
this.createView('dialog', viewName, {
scope: this.foreignScope,
parentId : this.model.id,
createButton: !this.createDisabled && this.mode !== 'search',
filters: this.getSelectFilters(),
boolFilterList: this.getSelectBoolFilterList(),
primaryFilterName: this.getSelectPrimaryFilterName(),
multiple: true,
createAttributes: (this.mode === 'edit') ? this.getCreateAttributes() : null,
mandatorySelectAttributeList: this.mandatorySelectAttributeList,
forceSelectAllAttributes: this.forceSelectAllAttributes
}, function (dialog) {
dialog.render();
self.notify(false);
this.listenToOnce(dialog, 'select', function (models) {
this.clearView('dialog');
if (Object.prototype.toString.call(models) !== '[object Array]') {
models = [models];
}
models.forEach(function (model) {
self.addLink(model.id, model.get('name'));
});
});
}, this);
});
this.events['click a[data-action="clearLink"]'] = function (e) {
var id = $(e.currentTarget).attr('data-id');
this.deleteLink(id);
};
}
}
});
});
Because of the 10,000 character limit for postings in this forum, this tutorial will continue in Part 2 https://forum.espocrm.com/forum/deve...-multiple-link and Part 3 https://forum.espocrm.com/forum/deve...p/60642-part-3
Comment