Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,6 @@
Build a Symfony form dedicated to filtering an entity, then let the bundle turn it into Doctrine ORM
query builder conditions.

> `LexikFormFilterBundle` is now `SpiriitFormFilterBundle`: only the name and the GitHub organization
> changed, the code remains the same.

**📖 Full documentation: [spiriitlabs.github.io/form-filter-bundle](https://spiriitlabs.github.io/form-filter-bundle/)**

The idea is:
Expand All @@ -22,13 +19,25 @@ The idea is:
Any type works, but filtering on a type other than a `XxxFilterType::class` requires a
[custom listener](https://spiriitlabs.github.io/form-filter-bundle/features/working-with-the-bundle) to apply the filter.

## Why this bundle

- **Plain Symfony forms**: no new DSL, your filters are regular form types with validation, theming and CSRF.
- **Ready-to-use filter types**: text, number, date and date range, boolean, choice, entity, enum and more.
- **Composable conditions**: AND/OR trees, embedded filters, collections and automatic joins.
- **Fully customisable**: override any field with a closure or a dedicated listener through `apply_filter`.
- **Debuggable**: the Symfony profiler shows which form field produced which DQL condition.

## Installation

```bash
composer require spiriitlabs/form-filter-bundle
```

Requires PHP 8.1+ and Symfony 5.4+. For Symfony 2.8/3.4, use the latest `v5.*` tag.
| Requirement | Version |
|-------------|---------|
| PHP | 8.1+ |
| Symfony | 5.4, 6.4, 7.4, 8.0 |
| Doctrine ORM | 3.0+ |

## Use it in two steps

Expand Down Expand Up @@ -81,18 +90,20 @@ class DefaultController extends AbstractController

## Documentation

- [Interactive demo](https://spiriitlabs.github.io/form-filter-bundle/guide/interactive-demo): follow a filter from form to DQL
- [Installation](https://spiriitlabs.github.io/form-filter-bundle/guide/installation)
- [Basics](https://spiriitlabs.github.io/form-filter-bundle/guide/basics)
- [Configuration](https://spiriitlabs.github.io/form-filter-bundle/guide/configuration)
- [Provided filter types](https://spiriitlabs.github.io/form-filter-bundle/features/provided-types)
- [Filter state persistence](https://spiriitlabs.github.io/form-filter-bundle/features/persistence)
- [Debugging & profiler](https://spiriitlabs.github.io/form-filter-bundle/features/debugging)
- [Pagination with Pagerfanta](https://spiriitlabs.github.io/form-filter-bundle/advanced/pagerfanta)
- [Live filtering with Turbo and Stimulus](https://spiriitlabs.github.io/form-filter-bundle/advanced/turbo-stimulus)

## Community support

Please [open a question on StackOverflow](http://stackoverflow.com/questions/ask) using the
[`spiriitformfilterbundle` tag](http://stackoverflow.com/questions/tagged/spiriitformfilterbundle), the
official support platform for this bundle. GitHub issues are dedicated to bug reports and feature requests.
Found a bug or missing a feature? [Open an issue](https://github.com/SpiriitLabs/form-filter-bundle/issues).
Questions are welcome there too.

## Credits

Expand Down
1 change: 1 addition & 0 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ export default defineConfig({
items: [
{ text: 'Working with other bundles', link: '/advanced/working-with-other-bundles' },
{ text: 'Advanced usage with PagerFanta', link: '/advanced/pagerfanta' },
{ text: 'Live filtering with Turbo and Stimulus', link: '/advanced/turbo-stimulus' },
],
},
],
Expand Down
102 changes: 102 additions & 0 deletions docs/advanced/turbo-stimulus.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
description: Filter a list without reloading the page, using Symfony UX Turbo and a small Stimulus controller.
---

# Live filtering with Turbo and Stimulus

A filter form is a plain GET form, which makes it a good fit for [Symfony UX Turbo](https://symfony.com/bundles/ux-turbo/current/index.html): the results are wrapped in a Turbo Frame, the form targets that frame, and only the results are refreshed. A tiny [Stimulus](https://symfony.com/bundles/StimulusBundle/current/index.html) controller submits the form while the user types.

No JavaScript is needed for the frame itself, and without JavaScript the form still works as a regular page submission.

```bash
composer require symfony/ux-turbo symfony/stimulus-bundle
```

## The controller

The form must use the GET method so the filter ends up in the URL. Disable CSRF protection: a search form changes no state.

```php
class UserListController extends AbstractController
{
#[Route('/users', name: 'user_list')]
public function __invoke(
Request $request,
UserRepository $userRepository,
FilterBuilderUpdater $filterBuilderUpdater,
): Response {
$form = $this->createForm(UserFilterType::class, null, [
'method' => Request::METHOD_GET,
'csrf_protection' => false,
]);
$form->handleRequest($request);

$queryBuilder = $userRepository->createQueryBuilder('u');
$filterBuilderUpdater->addFilterConditions($form, $queryBuilder);

return $this->render('user/list.html.twig', [
'form' => $form,
'users' => $queryBuilder->getQuery()->getResult(),
]);
}
}
```

## The template

The form lives outside the frame, so it is never re-rendered and keeps its focus while the user types. `data-turbo-frame` makes the submission target the results frame, and `data-turbo-action="advance"` pushes the filtered URL in the browser history, so a filtered list can be bookmarked and shared.

```twig
{{ form_start(form, {attr: {
'data-controller': 'filter-form',
'data-action': 'input->filter-form#submit',
'data-turbo-frame': 'results',
'data-turbo-action': 'advance',
}}) }}
{{ form_widget(form) }}
<button type="submit">Filter</button>
{{ form_end(form) }}

<turbo-frame id="results" data-turbo-action="advance">
<ul>
{% for user in users %}
<li>{{ user.name }}</li>
{% endfor %}
</ul>
</turbo-frame>
```

Links inside the frame, such as pagination links, also navigate only the frame. The `pagerfanta()` Twig function of [PagerfantaBundle](/advanced/pagerfanta) merges the current query string into every link it generates, so the filter survives a page change. For hand-written links, do the same:

```twig
<a href="{{ path('user_list', app.request.query.all|merge({page: 2})) }}">Next</a>
```

## The Stimulus controller

Create `assets/controllers/filter_form_controller.js`. It waits for the user to stop typing before submitting the form:

```js
import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
static values = { delay: { type: Number, default: 300 } };

submit() {
clearTimeout(this.timeout);
this.timeout = setTimeout(() => this.element.requestSubmit(), this.delayValue);
}

disconnect() {
clearTimeout(this.timeout);
}
}
```

`requestSubmit()` fires a real `submit` event, which Turbo intercepts, whereas `submit()` would bypass it and reload the whole page.

To change the delay, add `'data-filter-form-delay-value': 500` to the form attributes.

## Going further

The same list can be wrapped in a [Twig component](/advanced/pagerfanta#bonus-twig-list-component) so the frame, the table and the pagination are reused across screens.
8 changes: 8 additions & 0 deletions docs/guide/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,12 @@ The bundle can be installed using Composer or the [Symfony binary](https://symfo
composer require spiriitlabs/form-filter-bundle
```

## Requirements

| Requirement | Version |
|-------------|---------|
| PHP | 8.1+ |
| Symfony | 5.4, 6.4, 7.4, 8.0 |
| Doctrine ORM | 3.0+ |

Next: [Configuration](/guide/configuration)
Loading