Editor’s Note: This articles details another new developer features that is coming coming in SugarCRM 6.2, now in beta. In this article, senior software engineer Collin Lee illustrates the enhancements made to the global search to enable searching into custom modules.
Beginning with SugarCRM 6.2 we have added global search support for custom modules. The administrator may now configure which custom modules to run global searches against. To enable a custom module for global search go to the Admin->Global Search section. A list of Enabled Modules and Disabled Modules will be presented. Drag the custom module from the Disabled Modules list into the Enabled Modules list to allow global searching for the custom module. You may also reorder the Enabled Modules lists to control the ordering of displayed results with the topmost entry appearing first and so on.
After you click save, the list of global site search preferences will be saved to the file located in cache/modules/unified_search_modules_display.php. There is another file cache/modules/unified_search_modules.php that store the metadata for the fields to search against as well as the query operators to use (see “Under the Hood” section for more information about this file).
With the global search for the custom module enabled, you must then enable your user specific global search preferences. Run a global search and then click on the Show All button. A full screen for the user’s global search preferences will appear. Next to the Search button, you will see the Advanced label along with a collapsible arrow. Click on the arrow to reveal the enabled and disabled modules for the user.
Make the necessary adjustments for the user’s global search preferences and save the changes by clicking on the Search button. The next time you run a global search, the matching selected enabled module entries should appear in the global search results list.
Custom modules have default settings for which fields we allow global searches to run against. The following table lists the object type and the fields that the global search will query against. This means that custom modules built using the object type will automatically inherit default global search support for certain fields.
|Object||Global Search Field(s)||Notes|
|Company||name, phone_fax, phone_office, phone_alternate, email_addresses|
|Issue||*number, name||The *number column is prefixed by the package and module name (ex: custom Issue module named MyIssue in package abc will have column named abc_myissue_number)|
|Person||first_name, last_name, phone_home, phone_mobile, phone_work, phone_other, phone_fax, assistant, assistant_phone, email_addresses|
In addition, you may enable global searching on other fields with a few upgrade safe customizations. This could be the case for custom modules created and deployed prior to 6.2. Here are the steps:
1) Create or edit file custom/Extension/modules/YOUR_CUSTOM_MODULE/Ext/Vardefs/vardefs.php and add the unified_search attributes to the fields you wish to run global search on:
] = true;
] = true;
] = true;
2) Create or edit the file custom/modules/YOUR_CUSTOM_MODULE/metadata/SearchFields.php. If you are creating this file, you may simply copy the modules/YOUR_CUSTOM_MODULE/metadata/SearchFields.php file into the custom/modules/YOUR_CUSTOM_MODULE/metadata directory. Add your field to the search definitions:
‘NAME_OF_FIELD_TO_SEARCH’ => array( ‘query_type’=>’default’)
In most cases, the array( ‘query_type’=>’default’) entry should suffice. For more complex search operations involving related tables, etc., please consult developer/forum posts on customizing search fields. One example is this article: http://www.eontek.rs/sugarcrm/customize-search-fields-and-add-new-ones-in-sugarcrm
3) Run Admin->Repair or manually remove the file cache/modules/unified_search_modules.php. The next time you run a global search, the file will be rebuilt using your new customization settings.
4) Go to Admin->Global Search and drag the custom module you have added to the global search file into the Enabled Modules list.
*NOTE* – As of SugarCRM 6.2 Beta, we do not create default indexes for the global search fields. As such, you may need to consult with your database administrator to create the optimal database indexes for your specific customizations.
Under The Hood
This next section provides a technical overview of how the global search operates.
Before queries are run against the database tables, the system must decide which modules and fields to search against. The cache/modules/unified_search_modules.php is a file that is created in the buildCache method of UnifiedSearchAdvanced.php. The file is built via scanning all modules that have a SearchFields.php file. Then checks are made to see whether or not global search is enabled for the module or whether the module is a custom module. Should either case be true, then the SearchFields.php file is scanned to determine if any of the fields specified there are enabled for global search. When all the modules have been scanned, the results are stored into the cache/modules/unified_search_modules.php file. This file specifies all the possible modules that support global search and is the default list of modules that global search runs against.
Should the system administrator use the Admin->Global Search link to modify and save the list of the enabled modules to run global search against, then the cache/modules/unified_search_modules_display.php file is created to capture these changes. The system users then have the option to choose which modules in the cache/modules/unified_search_modules_display.php to run global search against. These user specific global search preferences are stored in the user_preferences database table.
The following diagram is a flowchart of how the global search currently works. The flowchart starts in the top left corner where processing begins by looping through each module that the user has specified to run global search against. The system checks to see if there is a user preference setting for the user running the global search. Should no user preference be set, then the global search uses the default modules specified in the cache/modules/unified_search_modules.php file (remember this is the file that is automatically created based on scanning the module’s vardefs and $searchFields variables) and applies any filters specified in the cache/modules/unified_search_modules_display.php file to remove modules that the system administrator has disabled for global search. The flowchart code may be found in the _performSearch method of the SugarSpot.php file.
The gist of the diagram is that the global search runs through a series of steps and checks to see which fields and modules it should create a query to search against. Should fields not be searched against because they were explicitly disabled for global search or if the combination of field type and search term are invalid (e.g. the case of a non-numerical field against an integer type field) then the field is unset from global search. It is only when there are qualifying fields to run a global search against that a query is executed and the results stored. At the end of processing all the modules, the final results are returned and displayed to the user.