List Filters

The list filter block list is declared before defining the list columns using the filters() method. The filter field values are accessible through the value('field_key') method, which is used to generate the SQL query parameters in the model.

Let's consider the available filter field types:

Text Field (text)

$list->filters()->text(
    # unique key for input[name]
    'query',
    # field name and placeholder (if not specified in extra[attr][placeholder])
    'Search by text'
);

Example of a filter handler:

$listFilters = $list->filters();
# get the filter value for the specified field by its key
$query = $listFilters->value('query');

# generate a filter for database query
$filterDB = [];
if ( ! empty($query)) {
    $filterDB['query'] = $query;
}

In the additional parameters in the array format ['attr' => [...]], you can set field attributes - placeholder, required class or style.

# additional parameters
$list->filters()->text('field_key_1', 'Search by text', [
        'attr' => [
            'placeholder' => 'Enter a phrase to search',
            'class'       => 'bold',
            'style'       => 'background:red;',
        ]
    ]
);

You can also set additional parameters for field validation, data type, and string length.

$list->filters()->text('field_key_2', 'Search by text', [],
    [ TYPE_NOTAGS, 'len' => 150 ]
);

Dropdown Select (select)

$list->filters()->select('cat_id',
     'Categories', # field name
     [  # selection options in the format ['id' => 'title']
        'option_id_1' => 'option_title_1',
        'option_id_2' => 'option_title_2',
        ...
        'option_id_n' => 'option_title_n',
     ],
     0  # default value
);

Note that the third parameter is the selection options for the dropdown list.
They can be passed from the model method or using a callback, and the returned data should be in the format ['id' => 'title'].

Handle the filter similarly in the controller method:

$cat_id = $list->filters()->value('cat_id');
if ( ! empty($cat_id)) {
    $filterDB['cat_id'] = $cat_id;
}

Number Field (number)

$list->filters()
    ->number('viewes',              # unique key of the input[name] field
             'Page Views',          # field label
             0,                     # default value
             ['size' => 'medium'],  # $extra additional parameters
    );

You can specify the desired field size in the additional parameters by using the key 'size'.

Process the filter:

$viewes = $list->filters()->value('viewes');
if ( ! empty($viewes)) {
    $filterDB[':viewes'] = array('viewes >= :viewes', ':viewes' => $viewes)
}

Checkbox

$list->filters()
    ->checkbox('is_public', # unique key of the input[name] field
           'Public',     # field label
    );

Process the filter:

$public = $list->filters()->value('is_public');
if ( ! empty($public)) {
    $filterDB['public'] = true;
}

Date Input

$list->filters()
    ->date('from',   # unique key of the input[name] field
           'Date:',  # field label
           ['attr' =>
                [    # additional parameters
                  'placeholder' => 'from',
                ]
           ]
    )
    ->date('to', 'to')

Example of filter handler:

$listFilters = $list->filters();
$from = $listFilters->value('from');
$to = $listFilters->value('to');

# form a filter for querying the database
$filterDB = [];
    
if (!empty($from)) {
    $filterDB[':from'] = array('created >= :from', ':from' => date('Y-m-d 00:00:00', strtotime($from)));
}
if (!empty($to)) {
    $filterDB[':to'] = array('created <= :to', ':to' => date('Y-m-d 23:59:59', strtotime($to)));
}

Autocomplete Field

$list->filters()
    ->autocomplete(
        'user_id',                                  # unique key of input[name]
        'User email',                               # field name or placeholder
        false,                                      # URL of available options
        [],                                         # default suggest options
        [
             'autocomplete' => function($q) {       # callback_autocomplete to search values
                    $result = array();
                    if (! empty($q)) {
                        $filter = array(
                            ':q' => array('email LIKE :q', ':q' => '%'.$q.'%'),
                        );
                        $data = $this->model->usersByEmail($filter); # query to the model
                        foreach($data as $v) {
                            $result[] = array($v['user_id'], $v['email']);
                        }
                    }
                    return $result;
             },
            'width'=> 180
        ]
    );

To find suitable options when filling out, it is convenient to use callback_autocomplete, which takes a search string as a parameter. The callback should return an array in the format [[$id_1, $title_1], [$id_2, $title_2], ...].

To filter and select the necessary records, we get the selected option from the filter field by the key name 'user_id'.

$user_id = $this->input->postget('user_id');
if ( ! empty($user_id)) {
    $filter[':user_id'] = ['U.user_id = :user_id', ':user_id' => $user_id];
}

Tags Component Tags

As an autofill filter field, you can also search by tags if such a component is added to the object and is a feature of the record. In the callback_autocomplete for the autofill field of the form component, we call the tagsAutocomplete(query) method to search for component matches. We represent the tag matching data in the required autofill format.

$list->filters()
    ->autocomplete(
        'tags',
        'Tags',
        false,
        [],
        [
             # callback_autocomplete to generate a list of matching values:
             'autocomplete' => function($q) {
                    $result = array();
                    if (! empty($q)) {
                        $data =  $tagsComponent->tagsAutocomplete($q);
                        foreach($data as $v) {
                            $result[] = array($v['id'], $v['tag']);
                        }
                    }
                    return $result;
             },
            'width' => 180,
        ]
    );

List filtering using tabs

Tabs are specified and processed in the controller method. Let's consider a simple example of working with tabs:

$list->tabs()
    ->add(0, 'All')
    ->add(1, 'Published')
    ->add(2, 'Unpublished')

//...

# form the selection filter and sort order by tab
$filterDB = [];
switch ($list->tab()) {
    case 1: # Published
        $filterDB['enabled'] = 1;
        break;
    case 2: # Unpublished
        $filterDB['enabled'] = 0;
        break;
}