Filters

Overview

Filters are a way to predefine searches on views that render a list of records such as list views, pop-up searches, and lookups. This page explains how to implement the various types of filters for record list views.

Filters contain the following properties:

Note: If a filter contains custom fields, those fields must be search-enabled in Studio > {Module Name} > Layouts > Search.

Operators

Operators, defined in ./clients/base/filters/operators/operators.php, are expressions used by a filter to represent query operators. They are constructed in the filter_definition to help generate the appropriate query syntax that is sent to the database for a specific field type. Operators can be defined on a global or module level. The accepted paths are listed below:

• ./clients/base/filters/operators/operators.php
• ./custom/clients/base/filters/operators/operators.php
• ./modules/<module>/clients/base/filters/operators.php
• ./custom/modules/<module>/clients/base/filters/operators.php

The list of stock operators is shown below:

Example

The example below defines a filter where the type field must contain the value Customer and the name field must start with the letter A.

  $filters = array(
    array(
        'type' => array(
            '$in' => array(
                'Customer',
            ),
        ),
    ),
    array(
        'name' => array(
            '$starts' => 'A',
        ),
    ),
);

Sub-Expressions

Sub-expressions group filter expressions into groupings. By default, all expressions are bound by an $and expression grouping.

Note: Sub-Expressions are only applicable to predefined filters and cannot be used for initial filters.

The example below defines a filter where the name field must begin with the letters A or C.

  $filters = array(
    '$or' => array (
        array(
            'name' => array(
                '$starts' => 'A',
            ),
        ),
        array(
            'name' => array(
                '$starts' => 'C',
            ),
        ),
    )
);

Module Expressions

Module expressions operate on modules instead of specific fields. The current module can be specified by either using the module name _this or by leaving the module name as a blank string.

The example below defines a filter where records must be favorited items.

  $filters = array(
    array(
        '$favorite' => '_this'
    ),
);

Filter Examples

Adding Predefined Filters to the List View Filter List

To add a predefined filter to the module's list view, create a new filter definition extension, which will append the filter to the module's viewdefs.

The following example will demonstrate how to add a predefined filter on the Accounts module to return all records with an account type of "Customer" and industry of "Other".

To create a predefined filter, create a display label extension in ./custom/Extension/modules/<module>/Ext/Language/. For this example, we will create:

./custom/Extension/modules/Accounts/Ext/Language/en_us.filterAccountByTypeAndIndustry.php

  <?php

$mod_strings['LBL_FILTER_ACCOUNT_BY_TYPE_AND_INDUSTRY'] = 'Customer/Other Accounts';

Next, create a custom filter extension in ./custom/Extension/modules/<module>/Ext/clients/base/filters/basic/.

For this example, we will create:

./custom/Extension/modules/Accounts/Ext/clients/base/filters/basic/filterAccountByTypeAndIndustry.php

  <?php

$viewdefs['Accounts']['base']['filter']['basic']['filters'][] = array(
    'id' => 'filterAccountByTypeAndIndustry',
    'name' => 'LBL_FILTER_ACCOUNT_BY_TYPE_AND_INDUSTRY',
    'filter_definition' => array(
        array(
            'account_type' => array(
                '$in' => array(
                    'Customer',
                ),
            ),
        ),
        array(
            'industry' => array(
                '$in' => array(
                    'Other',
                ),
            ),
        ),
    ),
    'editable' => false,
    'is_template' => false,
);

You should notice that the editable and is_template options have been set to "false". If editable is not set to "false", the filter will not be displayed in the list view filter's list.

Finally, navigate to Admin > Repair and click "Quick Repair and Rebuild" to rebuild the extensions and make the predefined filter available for users.

Adding Initial Filters to Lookup Searches

To add initial filters to record lookups and type-ahead searches, define a filter template. This will allow you to filter results for users when looking up a parent related record. The following example will demonstrate how to add an initial filter for the Account lookup on the Contacts module. This initial filter will limit records to having an account type of "Customer" and a dynamically assigned user value determined by the contact's assigned user.

To add an initial filter to the Contacts record view, create a display label for the filter in ./custom/Extension/modules/<module>/Ext/Language/. For this example , we will create:

./custom/Extension/modules/Accounts/Ext/Language/en_us.filterAccountTemplate.php

  <?php

$mod_strings['LBL_FILTER_ACCOUNT_TEMPLATE'] = 'Customer Accounts By A Dynamic User';

Next, create a custom template filter extension in ./custom/Extension/modules/<module>/Ext/clients/base/filters/basic/. For this example, create:

./custom/Extension/modules/Accounts/Ext/clients/base/filters/basic/filterAccountTemplate.php

  <?php

$viewdefs['Accounts']['base']['filter']['basic']['filters'][] = array(
    'id' => 'filterAccountTemplate',
    'name' => 'LBL_FILTER_ACCOUNT_TEMPLATE',
    'filter_definition' => array(
        array(
            'account_type' => array(
                '$in' => array(),
            ),
        ),
        array(
            'assigned_user_id' => ''
        )
    ),
    'editable' => true,
    'is_template' => true,
);

As you can see, the filter_definition contains arrays for account_type and assigned_user_id. These filter definitions will receive their values from the contact record view's metadata. You should also note that this filter has is_template and editable set to "true". This is required for initial filters.

Once the filter template is in place, modify the contact record view's metadata. To accomplish this, edit ./custom/modules/Contacts/clients/base/views/record/record.php to adjust the account_name field. If this file does not exist in your local Sugar installation, navigate to Admin > Studio > Contacts > Layouts > Record View and click "Save & Deploy" to generate it. In this file, identify the panel_body array as shown below:

  1 => 
array (
    'name' => 'panel_body',
    'label' => 'LBL_RECORD_BODY',
    'columns' => 2,
    'labelsOnTop' => true,
    'placeholders' => true,
    'newTab' => false,
    'panelDefault' => 'expanded',
    'fields' => 
    array (
        0 => 'title',
        1 => 'phone_mobile',
        2 => 'department',
        3 => 'do_not_call',
        4 => 'account_name',
        5 => 'email',
    ),
),

Next, modify the account_name field to contain the initial filter parameters.

  1 =>
array (
    'name' => 'panel_body',
    'label' => 'LBL_RECORD_BODY',
    'columns' => 2,
    'labelsOnTop' => true,
    'placeholders' => true,
    'newTab' => false,
    'panelDefault' => 'expanded',
    'fields' =>
    array (
        0 => 'title',
        1 => 'phone_mobile',
        2 => 'department',
        3 => 'do_not_call',
        4 => array (
            //field name
            'name' => 'account_name',

            //the name of the filter template
            'initial_filter' => 'filterAccountTemplate',

            //the display label for users
            'initial_filter_label' => 'LBL_FILTER_ACCOUNT_TEMPLATE',

            //the hardcoded filters to pass to the templates filter definition
            'filter_populate' => array(
                'account_type' => array('Customer')
            ),

            //the dynamic filters to pass to the templates filter definition
            //please note the index of the array will be for the field the data is being pulled from
            'filter_relate' => array(
                //'field_to_pull_data_from' => 'field_to_populate_data_to'
                'assigned_user_id' => 'assigned_user_id',
            )
        ),
        5 => 'email',
    ),
),

Finally, 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 parent account for a contact.

Adding Initial Filters to Drawers from a Controller

When creating your own views, you may need to filter a drawer called from within your custom controller. Using an initial filter, as described in the Adding Initial Filters to Lookup Searches section, we can filter a drawer with predefined values by creating a filter object and populating the config.filter_populate property as shown below:

If you've added a new button to the Contact record view that, when clicked, should display a selection-list of Accounts with the type "Customer" assigned to the user seed_sally_id, you will need to customize the following file: data/app/sugar/custom/modules/Contacts/Ext/clients/base/views/record/record.js

  //create filter
var filterOptions = new app.utils.FilterOptions()
    .config({
        'initial_filter': 'filterAccountTemplate',
        'initial_filter_label': 'LBL_FILTER_ACCOUNT_TEMPLATE',
        'filter_populate': {
            'account_type': ['Customer'],
            'assigned_user_id': 'seed_sally_id'
        }
    })
    .format();

//open drawer
app.drawer.open({
    layout: 'selection-list',
    context: {
        module: 'Accounts',
        filterOptions: filterOptions,
        parent: this.context
    }
});

To create a filtered drawer with dynamic values, create a filter object and populate the config.filter_relate property using the populateRelate method as shown below:

  //record to filter related fields by
var contact = app.data.createBean('Contacts', {
    'first_name': 'John',
    'last_name': 'Smith',		
    'assigned_user_id': 'seed_sally_id'
});

//create filter
var filterOptions = new app.utils.FilterOptions()
    .config({
        'initial_filter': 'filterAccountTemplate',
        'initial_filter_label': 'LBL_FILTER_ACCOUNT_TEMPLATE',
        'filter_populate': {
            'account_type': ['Customer'],
        },
        'filter_relate': {
            'assigned_user_id': 'assigned_user_id'
        }
    })
    .populateRelate(contact)
    .format();

//open drawer
app.drawer.open({
    layout: 'selection-list',
    context: {
        module: 'Accounts',
        filterOptions: filterOptions,
        parent: this.context
    }
});