Table of contents

# Api

Either you can add filter to existing column by defining column and filter separately:

$grid->addColumnText('name', 'Name');
$grid->addFilterText('name', 'Name');
1
2

Or you can add a filter directly to column definition:

$grid->addColumnText('name', 'Name')
	->setFilterText();
1
2

There are several filter classes and they all have some common behaviour and properties. Let's start with parameters, I will take a FiterText as an example.

/**
 * $key, $name, $columns
 */
$grid->addFilterText('name', 'Name');

/**
 * Equivalent
 */
$grid->addFilterText('name', 'Name', 'name');

/**
 * Same functionality - search in column 'name'
 */
$grid->addFilterText('x_foo', 'Name', 'name');
1
2
3
4
5
6
7
8
9
10
11
12
13
14

FilterText is a little bit different than other filters. It can search in multiple columns. Here's how you do that:

$grid->addFilterText('name', 'Search', ['name', 'surname', 'company', 'address']);
1

# Placeholder

$grid->addFilterText('all', 'Search:', ['name', 'id'])
	->setPlaceholder('Search...');
1
2

# Custom where condition

$grid->addFilterText('custom', 'Custom search:', 'name')
	->setCondition(function(Dibi\Fluent $fluent, $value) {
		/**
		 * The data source is here DibiFluent
		 * No matter what data source you are using,
		 * prepared data source will be passed as the first parameter of your callback function
		 *
		 * If you are using `NextrasDataSource` (DbalCollection),
		 * functions as `findBy` don't work. You need to use `$collection->getQueryBuilder->...` syntax.
		 * See https://github.com/contributte/datagrid/pull/298 for detailed information.
		 */
		$fluent->where('id > ?', strlen($value));
	});
1
2
3
4
5
6
7
8
9
10
11
12
13

# Templates:

Filters can also have their own templates:

$grid->addFilterText('name', 'Name:')
	->setTemplate(__DIR__ . '/templates/filter_name.latte');
1
2

There is how the default FilterText template looks like:

{**
 * @param Filter                         $filter
 * @param Nette\Forms\Controls\TextInput $input
 *}

<div class="row">
	{label $input class =>; 'col-sm-3 control-label' /}
	<div class="col-sm-9">
		{input $input, class => 'form-control input-sm', data-autosubmit => true}
	</div>
</div>

1
2
3
4
5
6
7
8
9
10
11
12

# Filter blocks

User can define filter template via {block} macro:

$grid->setTemplateFile(__DIR__ . '/my-grid-template.latte');
$grid->addFilterText('name', 'Name:');
1
2

And the my-grid-template.latte:

{block filter-name}
{input $input}

1
2
3

Arguments $filter (Filter class instance), $input (filter form input) and $outer (true or false) are passed to the block. You can inspire yourself with native filter templates, for example text filter template can be found int vendor/ublaboo/datagrid/src/templates/datagrid_filter_text.latte.

# Filter type blocks

Macro

# Removing filter

You can remove filter from grid like so:

$grid->addFilterText('foo', 'Name', 'name');
$grid->removeFilter('foo');
1
2

# FilterText

By default, when you type "foo bar", FilterText will split input words into n single phrases (... OR (<column> LIKE "%foo%") OR (<column> LIKE "%bar%")). That behaviour can be overridden:

$grid->addFilterText('name', 'Name')
	->setSplitWordsSearch(false);
1
2

# FilterSelect

FilterSelect has one more parameter - options:

$grid->addFilterSelect('status', 'Status:', ['' => 'All', 1 => 'On', 2 => 'Off']);

/**
 * Equivalent
 */
$grid->addFilterSelect('status', 'Status:', ['' => 'All', 1 => 'On', 2 => 'Off'], 'status');
1
2
3
4
5
6

Again, you can use custom condition callback, the same in all other filters.

# FilterMultiSelect

Api of FilterMultiSelect is the same as of FilterSelect

$grid->addFilterMultiSelect('status', 'Status:', [1 => 'On', 2 => 'Off', 2 => 'Another option']);
1

Keep in mind that FilterMultiSelect uses bootstrap-select JS library. Read more on Introduction.

# FilterDate

$grid->addFilterDate('created', 'User registerd on');
1

This filter also has some special features. First, it shows datepicker. Second, You can set date format. Sadly, JavaScript has different date formatting modifiers, so you have to set them both at once:

/**
 * This is default formatting
 * $php_format, $js_format
 */
$grid->addFilterDate('created', 'User registerd on')
	->setFormat('j. n. Y', 'd. m. yyyy');
1
2
3
4
5
6

# FilterRange

This filter renders two inputs: From and To. If you want to set inputs placeholders, you have to set both in an array.

$grid->addFilterRange('price_range', 'Price:', 'price');
1

# FilterDateRange

FilterDateRange is similar:

$grid->addFilterDateRange('date_created', 'User registered:');
1

# Default filter values

Datagrid filters can have contain default filter values. Once user changes the filter, default values are not longer applied to the filter. Example usage:

$grid->setDefaultFilter(['status' => 1, 'name' => 'Joe']);
1

Notice! Values of FilterRange, FilterDateRange and FilterMultiSelect must be of type array:

$grid->addFilterMultiSelect('status', 'Status:', [
	0 => 'Offline',
	1 => 'Online',
	2 => 'Standby'
]);

$grid->addFilterRange('age', 'Age');

$grid->setDefaultFilter(['status' => [1], 'age' => ['from' => 18]]);
1
2
3
4
5
6
7
8
9

# Resetting filter to default values

By default, once you reset the filter, default fitler values are applied. If you don't want to apply them after resetting the filter, pass false as a second parameter to DataGrid::setDefaultFilter():

$grid->setDefaultFilter('id' => 10, false);
1

# Filters rendering

Note that if you are rendering filter in datagrid table, you have to choose identical keys for column and filter:

$grid->addColumnText('name', 'Name');
$grid->addFilterText('name', 'Name');

/**
 * This filter won't show up, because it has different key name
 */
$grid->addFilterText('search', 'Name', 'name');
1
2
3
4
5
6
7

# Outer filters rendering

You can set outer filters rendering:

$grid->setOuterFilterRendering(); // - that is true. Or $grid->setOuterFilterRendering(false);
1

# Session - remeber state

Grid refreshes its state on several levels. One could be session. It is by defaut turned on, but can be disabled:

$grid->setRememberState(false); // Or turned on again: $grid->setRememberState(true);
1

If you want to keep hideable columns in session even when rememebr state is turned off, use second argument:

$grid->setRememberState(false, true);
1

# Session - filters / filter values changed

When you set some filters and user do some filtering, values are stored in session. After that, when filters are changed (maybe some select options are removed, etc), datagrid would throw an exception, because it can not find particular filters / filter values that are still stored in session. You can supress those exception:

$grid->setStrictSessionFilterValues(false);
1

# URL refreshing - history API

Second, grid refreshes URL via history API. So when you refresh, there is always current url. That can be also disabled:

$grid->setRefreshUrl(false); // Or enabled again: $grid->setRefreshUrl(true);
1

# Auto submit

DataGrid filter is submitted automatically after keypress (there is of course a little delay). If you want to disable that feature and use customizable submit button instead, use this code:

$grid->setAutoSubmit(false);
1