Filtering Records

Learn how to filter records found in a list.

October CMS provides features for filtering database records. For behaviors that support filters, you can define a filter option to enable the feature. Scopes are often stored in the model configuration directory as scopes.yaml.

# Configuring a Behavior

The List Controller and Relation Controller backend behaviors can be filtered by adding a filter property to the configuration. When defined, the available filters are shown above the list.

# ===================================
#  List Behavior Config
# ===================================

# ...

# Displays the list filter
filter: $/october/test/models/user/scopes.yaml

# Defining Filter Scopes

Similarly filters are driven by their own configuration file that contain filter scopes. Each scope is an aspect by which the list can be filtered. The next example shows a typical contents of the filter definition file.

# ===================================
# Filter Scope Definitions
# ===================================

scopes:

    category:
        label: Category
        modelClass: Acme\Blog\Models\Category
        conditions: category_id in (:value)
        nameFrom: name

    status:
        label: Status
        type: group
        conditions: status in (:value)
        options:
            pending: Pending
            active: Active
            closed: Closed

    published:
        label: Hide published
        type: checkbox
        default: 1
        conditions: is_published <> true

    approved:
        label: Approved
        type: switch
        default: 2
        conditions:
            - is_approved <> true
            - is_approved = true

    created_at:
        label: Date
        type: date
        conditions:
            after: created_at >= ':value'
            between: created_at >= ':after' AND created_at <= ':before'

# Scope Properties

For each scope you can specify these properties (where applicable).

Property	Description
label	a name when displaying the filter scope to the user.
type	defines how this scope should be , see filter scope definitions. Default: `group`.
conditions	enables or disables condition functions or specifies a raw where query statement to apply to each condition, see the scope type definition for details.
modelScope	specifies a query scope method defined in the list model to apply to the list query. The first argument will contain the query object (as per a regular scope method) and the second argument will contain the filtered value(s).
options	options to use if filtering by multiple items, this option can specify an array or a method name in the `modelClass` model.
emptyOption	an optional label for an intentional empty selection.
default	supply a default value for the filter, as either array, string or integer depending on the filter value.
permissions	the permissions that the current backend user must have in order for the filter scope to be used. Supports either a string for a single permission or an array of permissions of which only one is needed to grant access.
dependsOn	a string or an array of other scope names that this scope depends on. When the other scopes are modified, this scope will reset.
nameFrom	a model attribute name used for displaying the filter label. Default: `name`.
valueFrom	defines a model attribute to use for the source value. Default comes from the scope name.

# Filter Dependencies

Filter scopes can declare dependencies on other scopes by defining the dependsOn property, which provide a server-side solution for updating scopes when their dependencies are modified. When the scopes that are declared as dependencies change, the defining scope will reset and update dynamically. This provides an opportunity to change the available options to be provided to the scope.

country:
    label: Country
    type: group
    conditions: country_id in (:value)
    modelClass: October\Test\Models\Location
    options: getCountryOptions

city:
    label: City
    type: group
    conditions: city_id in (:value)
    modelClass: October\Test\Models\Location
    options: getCityOptions
    dependsOn: country

In the above example, the city scope will refresh when the country scope has changed. Any scope that defines the dependsOn property will be passed all current scope objects for the Filter widget, including their current values, as an array that is keyed by the scope names.

public function getCountryOptions()
{
    return Country::lists('name', 'id');
}

public function getCityOptions($scopes = null)
{
    if (!empty($scopes['country']->value)) {
        return City::whereIn('country_id', $scopes['country']->value)->lists('name', 'id');
    }
    else {
        return City::lists('name', 'id');
    }
}

You can filter the filter scope definitions by overriding the filterScopes method inside the Model used. This allows you to manipulate visibility and other scope properties based on other scope values. The method takes two arguments $scopes will represent an object of the scopes already defined by the scope configuration and $context represents the active filter context.

public function filterScopes($scopes, $context = null)
{
    if ($scopes->disable_roles->value) {
        $scopes->roles->hidden = true;
    }
}

The above logic will hide the roles scope if the disable_roles value is checked. The logic will be applied when the filter first loads and also when updated by a scope dependency. For example, here is the associated filter scope definitions.

disable_roles:
    type: checkbox
    label: Disable Roles

roles:
    type: text
    label: Role
    dependsOn: disable_roles

← Sorting Records Filter Widgets →