Applying Initial Filter For Relate Fields and Relationship fields In Sugar 7.x

In this article I will be explaining how to add Initial filters for Relate fields in Sugar 7.x.
Initial Filters are used to set a filter automatically whenever you open a Look-up Search to select a record in Sugar.This will make the job of selecting the record(s) more easier to the user as the system will automatically filter out the records which are not required.

Note: Here is the documentation provided by Sugar for creating initial filter for look up search.But this approach will work only for standard relationship relate field (eg. Filtering contacts based on selected account) and the filter populate option can be used only with hard-coded values.But the following approach will help you to pass dynamic value to filter_populate parameter and you will be able to use the same for custom relationship relate fields also.And this approach will work for record,list and sub-panel list views.

Applying Initial Filter for Relate fields and Relationship fields
Let’s start with an example.Imagine you are going to provide SugarCRM for a an Educational Institute.They have multiple branches and each branch has separate predefined set of courses.A new student is coming to join for a course at one of their branches.Let’s call this activity as Student Enrollment.So here while creating an Enrollment the user will first select a Branch (Standard Accounts Module) then a Course.While selecting the course he/she would like to see only the courses which are offered by the selected branch.This we can achieve very easily with the help of initial filters.

Step 1
First we need to create a filter template for courses which will filter out only the courses of selected branch.To do this we will create a new file in the following path.Let’s name this template as FilterCoursesTemplate.

custom/Extension/modules/Courses/Ext/clients/base/filters/basic/FilterCoursesTemplate.php

Now add the following line of code to the file FilterCoursesTemplate.php

	<?php
	$viewdefs['Courses']['base']['filter']['basic']['filters'][] = array(
	'id' => 'FilterCoursesTemplate',
	'name' => 'LBL_FILTER_COURSES_TEMPLATE',
	'filter_definition' => array(
	array(
	'accounts_courses_accounts_ida' => array(
	'$equals' => ' ',
	),
	),
	),
	'editable' => true,
	'is_template' => true,
	);

view raw FilterCoursesTemplate.php hosted with ❤ by GitHub

Note:
1. Courses  is the module which we are filtering.
2. accounts_courses_accounts_ida: Relationship id between branches and courses. (this can be found in the relationship table between Branches and Courses)
3.The filter id and file-name should match each other
Step 2

Now we need to give a display label for our template we have created in Step 1.To do this add a new file in the following path with the below code.

custom/Extension/modules/Courses/Ext/Language/en_us.filterCourseTemplate.php

	<?php
	$mod_strings['LBL_FILTER_COURSES_TEMPLATE'] = 'Courses Offered by the Selected Branch';

view raw course_filter_label.php hosted with ❤ by GitHub

Step 3

We are ready with our filter template.Now we need to pass this template as filter options into  the look up search when user try to select a Course by clicking the Search for more button.For that we will create a new controller file for relate field and will extend it from parent controller.

Create a new JavaScript file in the following path and add the below code into it.

custom/modules/Enrollments/clients/base/fields/relate/relate.js

	({
	extendsFrom: 'RelateField',
	initialize: function(options) {
	this._super('initialize', [options]);
	},
	openSelectDrawer: function() {
	var filterOptions = new app.utils.FilterOptions()
	.config({
	'initial_filter': 'FilterCoursesTemplate',
	'initial_filter_label': 'LBL_FILTER_COURSES_TEMPLATE',
	'filter_populate': {
	'accounts_courses_accounts_ida': this.model.get('accounts_enrollments_accounts_ida'),
	}
	})
	.format();
	//this custom code will effect for all relate fields in Enrollment module.But we need initial filter only for Courses relate field.
	filterOptions = (this.getSearchModule() == "Courses") ? filterOptions : this.getFilterOptions();
	app.drawer.open({
	layout: 'selection-list',
	context: {
	module: this.getSearchModule(),
	fields: this.getSearchFields(),
	filterOptions: filterOptions,
	}
	}, _.bind(this.setValue, this));
	},
	})

view raw relate.js hosted with ❤ by GitHub

Note:

1. Enrollment is the module for which we are going to use filter.

2.accounts_enrollments_accounts_ida: Relationship id between branches and enrollments (this you can find in the  relationship table between Branches and enrollments modules.)

3.Here we are overriding the standard openSelectDrawer method .

Step 4

Now navigate to Admin > Repair and click “Quick Repair and Rebuild”. This will rebuild the extensions and make the initial filter available for users when selecting a course for a student enrollment.

Here we go!!
This customization will work if the user edit the record from record view,list view and sub-panel list view.Also while creating the record.And this is purely upgrade safe.

In next article I will explain how to apply initial filter while linking a record in sub-panel with the “Link Existing Records” button.

Please feel free to write your comments and feedback.

Thanks
Shijin Krishna