Filters #

Field Filters #

Entries can be filtered by a custom field value.

->filters([
    $co->createFieldFilter('topics'),

    $co->createFieldFilter('assignedTo')       
        ->label('Responsible')
        ->orderBy('lastName, firstName')
        ->userSelectize(),
    
    $co->createFieldFilter('workflowStatus')
     
])

Currently supported:

• Entries fields
• Users fields
• Option fields (Dropdown)

For entries fields you can specify the direction of the relationship:

->direction('out')

• both (default): all relationships
• in: Incoming relationships, from the point of view of the selected element.
• out: Outgoing relationships, from the point of view of the selected element.

Matrix subfields can also be used as filters:

 $co->createFieldFilter('streaming.streamingProvider')->orderBy('title')
 $co->createFieldFilter('streaming.digitalMedium.streamingProvider')->orderBy('title')                        

Specify fields in the form matrixFieldHandle.blockTypeHandle.subFieldHandle.

If there is only one block type, you can use matrixFieldHandle.subFieldHandle

You can use the useSelectize or useElementSelect settings (see below) for a better user experience.

Using element select modals (experimental) #

Instead of using a select box you can use Crafts element select modals to pick your filter element.

$co->createFieldFilter('assignedTo')
    ->useElementSelect(),

Allow selection of multiple elements:

$co->createFieldFilter('topics')
    ->useElementSelect()
    ->multiSelectOperator('and')    
    ->selectLimit(10),

• The operator or (default) will find entries that have a relation to at least one selected element.
• The operator and will find entries that have relations to all selected elements.

There is also a shortcut for this:

$co->createElementSelectFilter('topics'),

// handle, direction, select multiple elements, operator
$co->createElementSelectFilter('cast.persons', 'in', true, 'and')

$co->createElementSelectFilter('assignedTo', multipleSelect: true, operator: 'and'),

Status filter #

Filter by workflow/entry status.

$co->createStatusFilter()->label('Workflow')

Options are defined in the statusFilterOptions plugin setting.

Custom filters #

Additional custom filters can be defined via a custom filter class:

 $co->createCustomFilter(CriticalReviewsFilter::class)
    ->label('Critical Reviews')
    ->handle('criticalreviews')
    ->options([
        ['label' => 'Overdue', 'value' => 'overdue'],
        ['label' => 'Next week', 'value' => 'nextweek'],
    ])

Filter class example. #

<?php

namespace modules\contentoverview\filters;

use craft\elements\db\ElementQueryInterface;
use wsydney76\contentoverview\models\filters\CustomFilter;
use wsydney76\contentoverview\models\Section;

class CriticalReviewsFilter extends CustomFilter
{
    public function modifyQuery(Section $sectionConfig, array $filter, ElementQueryInterface $query)
    {
        switch ($filter['value']) {
            case 'overdue':
            {
                $query
                    ->workflowStatus('inReview')
                    ->dueDate('< now');
                break;
            }
            case 'nextweek':
            {
                // ...               
            }
        }
    }

}

Specify the modifyQuery function and update the $query parameter.

The $filter parameter will contain handle and value:

[
    'handle' => 'criticalreviews'
    'value' => 'overdue'
]

If additional parameters are fix, you can hardcode them in your class:

$co->createCustomFilter(CriticalReviewsFilter::class);

public string $handle = 'criticalreviews';
public string $label = 'Critical Reviews';
public array|Collection $options = [
    ['label' => 'Overdue', 'value' => 'overdue'],
    ['label' => 'Next week', 'value' => 'nextweek'],
];

Options and the executed query can also be handled via events.

Filter settings #

handle #

• Type: string

A unique handle. The field handle for field filters is set by createFieldFilter($handle)

->handle('criticalreviews')

label #

• Type: string

The label used for the select box. Defaults to field name for field filters.

->label('Critical Reviews')

options #

The options used for the select box. Only relevant for custom filters.

• Type: array|Collection

->options([
        ['label' => 'Overdue', 'value' => 'overdue'],
        ['label' => 'Next week', 'value' => 'nextweek'],
    ])

useSelectize #

• Type: bool
• Default: false

Filters by default use a standard select input. For longer lists of options you may want to switch to a selectize input that allows searching.

->useSelectize()

Selectize inputs have a slightly different visual appearance than standard selects, so it is not a very good idea to mix them.

useElementSelect #

• Type: bool
• Default: false

Entries/users field filters only.

Use Crafts element select modal to select elements.

selectLimit #

• Type: int
• Default: 1

->selectLimit(5)

Limit of elements that can be selected in an element select. If multiple elements are selected, this will result in an OR condition.

multiSelectOperator #

• Type: string
• Default: or

->multiSelectOperator('and')

Operator if multiple filter elements are selected.

direction #

• Type: string
• Default: both

->direction('in')

Direction used for the relatedTo query param.

• both (default): all relationships
• in: Incoming relationships, from the point of view of the selected element.
• out: Outgoing relationships, from the point of view of the selected element.

userGroups #

• Type: string|array

Users field filters only, if useElementSelect is not set. The user group(s) from which the user options will be selected.

->userGroups(['contentEditors', 'festivalAdmin'])

Filter position #

Multiple filters can take up a lot of space if used together with search, so you can push them below or on top of the search in your section config:

// Section config
->filtersPosition('bottom') // top|bottom