diff --git a/README.md b/README.md
index 1bcbcc0..e775034 100644
--- a/README.md
+++ b/README.md
@@ -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:
@@ -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
@@ -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
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 76327d0..55bdea4 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -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' },
],
},
],
diff --git a/docs/advanced/turbo-stimulus.md b/docs/advanced/turbo-stimulus.md
new file mode 100644
index 0000000..729d174
--- /dev/null
+++ b/docs/advanced/turbo-stimulus.md
@@ -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) }}
+
+{{ form_end(form) }}
+
+
+
+ {% for user in users %}
+
{{ user.name }}
+ {% endfor %}
+
+
+```
+
+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
+Next
+```
+
+## 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.
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index bd9cc0a..7942729 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -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)