# Filter

## Definition

A filter is used to define the appearance of the content of the table in the list view. It allows you to configure the list of **columns to display** by default, their **order**, the **search conditions** to apply, the **sort order** and for which **type of view** you want to use it (List or Related List).

## Examples

### Default filter

```php
<?php

use Uccello\Core\Models\Filter;
use Uccello\Core\Models\Module;

...

$module = Module::where('name', 'person')->first();

Filter::create([
    'module_id' => $module->id,
    'domain_id' => null,
    'user_id' => null,
    'name' => 'filter.all',
    'type' => 'list',
    'columns' => [ 'first_name', 'last_name', 'birthday', 'city' ],
    'conditions' => null,
    'order' => null,
    'is_default' => true,
    'is_public' => false,
    'data' => [ 'readonly' => true ],
]);
```

This filter is the default one for the list view of the `Person` module. \
Its label `filter.all` will be replaced in the UI by its translation : **All**.\
It displays by default the columns `first_name`, `last_name`, `birthday` and `city`.\
As `domain_id` and `user_id` are `null`, this filter is available in all domains, for all users.\
As `readonly` is `true`, this filter cannot be deleted from the UI.

{% hint style="info" %}
If no specific filters are defined for Related List, this filter will be used by default.
{% endhint %}

### Custom filter for List View

```php
<?php

use Uccello\Core\Models\Filter;
use Uccello\Core\Models\Module;

...

$module = Module::where('name', 'person')->first();

Filter::create([
    'module_id' => $module->id,
    'domain_id' => 1,
    'user_id' => 3,
    'name' => 'People called John',
    'type' => 'list',
    'columns' => [ 'first_name', 'last_name', 'birthday' ],
    'conditions' => [ 
        "search"  => [
            "first_name" => "John"
        ]
    ],
    'order' => [ 'last_name' => 'asc' ],
    'is_default' => false,
    'is_public' => true,
    'data' => null,
]);
```

This filter is a custom one available only in the domain with the id 1.\
It is available for the user with the id 3, but as `is_public` is `true`, this filter is also visible by the others users.\
Its `name` is **People called John**. It will display like that in the UI, independently of the selected language.\
It displays by default the columns `first_name`, `last_name` and `birthday`.\
It will only display records whose `first_name` field contains **John**.\
The results will be sorted by `last_name` in ascending order.

### Custom Filter for Related List

```php
<?php

use Uccello\Core\Models\Filter;
use Uccello\Core\Models\Module;

...

$module = Module::where('name', 'person')->first();

Filter::create([
    'module_id' => $module->id,
    'domain_id' => null,
    'user_id' => null,
    'name' => 'filter.related-list',
    'type' => 'related-list',
    'columns' => [ 'first_name', 'last_name' ],
    'conditions' => null,
    'order' => [ 'last_name' => 'asc' ],
    'is_default' => false,
    'is_public' => false,
    'data' => null,
]);
```

It could be useful to create specific filters for Related List to display different columns from those in the List View. To do this you just set `related-list` for the `type` of filter.

## Properties

| Attribute       |  Type  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                   | Default |
| --------------- | :----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| **module\_id**  |   int  | Id of the module providing the filter                                                                                                                                                                                                                                                                                                                                                                                                         |         |
| **domain\_id**  |   int  | Id of the domain for which the filter is available. If `null`, the filter is available in all domains.                                                                                                                                                                                                                                                                                                                                        |  `null` |
| **user\_id**    |   int  | Id of the user for which the filter is available. If `null`, the filter is available for all users.                                                                                                                                                                                                                                                                                                                                           |  `null` |
| **name**        | string | Filter's name. It can be translated if you add the translation in the module localization file.                                                                                                                                                                                                                                                                                                                                               |         |
| **type**        | string | If you use `list`, the filter will be used for the module's list view. If you use `related-list`, the filter will be used if the module is linked by a related list to another one.                                                                                                                                                                                                                                                           |         |
| **columns**     |  array | List of columns to display by default.                                                                                                                                                                                                                                                                                                                                                                                                        |         |
| **conditions**  |  array | <p>List of conditions to apply by default. The <code>search</code> key is use to display in the list view, the search value of each column. Each uitype can define the way it will use the value to make the condition query.<br><strong>Notice:</strong> You must use the name of the field and not the name of the column in the database.<br><br>Example:</p><p>[ "search" => [ "first_name" => "John",  "last_name" => "D" ] ]</p><p></p> |  `null` |
| **order**       |  array | <p>List of sort orders to use for each column, in the <code>orderBy</code> clause of the query. <br>Use <code>asc</code> to sort in ascending order, and <code>desc</code> to sort in descending order.</p><p><strong>Notice:</strong> You must use the name of the field and not the name of the column in the database.</p><p></p><p>Example:<br>[ "first_name" => "asc", "birthday" => "desc" ]</p><p></p>                                 |  `null` |
| **is\_default** |  bool  | Defines if the filter is use as the default one for the module. Normally there should only be one by default. By in case of several are defined as default, the first one found in the database will be used.                                                                                                                                                                                                                                 | `false` |
| **is\_public**  |  bool  | Defines if the filter is shared with other users. This property is used only if `user_id` is `not null`.                                                                                                                                                                                                                                                                                                                                      | `false` |
| **data**        |  array | List of other options for the filter. By default, the only available option is `readonly`. If `readonly` is `true`, the filter cannot be deleted or modified from the UI.                                                                                                                                                                                                                                                                     |  `null` |
