Version 0.14 (#29)

https://github.com/Kreyu/data-table-bundle/blob/main/CHANGELOG.md#014
Kreyu · Sep 10, 2023 · 0f1dfa8 · 0f1dfa8
1 parent 93e6a6c
commit 0f1dfa8
Show file tree

Hide file tree

Showing 397 changed files with 9,666 additions and 3,591 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+* text=auto
diff --git a/.github/workflows/retype-action.yml b/.github/workflows/retype-action.yml
diff --git a/.gitignore b/.gitignore
@@ -2,5 +2,6 @@
 /venv
 /composer.lock
 /.php-cs-fixer.cache
+/.phpunit.result.cache
 /.idea
 /.vscode
diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,29 @@
+# 0.14
+
+- **[Feature]** Data table events
+- **[Feature]** Column `priority` option to allow setting order of columns
+- **[Feature]** Column `visible` option to allow setting visibility of columns
+- **[Feature]** Column `personalizable` option to allow excluding the column from personalization
+- **[Feature]** More verbose filter type form-related options such as `form_type`, `operator_form_type`
+- **[Feature]** Ability to set hydration mode of the Doctrine ORM proxy query
+- **[Feature]** Data table builder's `setSearchHandler` method for easier search definition
+- **[Feature]** The `CollectionColumnType` default separator changed `', '` (with space after comma) instead of `','`
+- **[Feature]** Ability to create `ExportData` with exporter name string
+- **[Feature]** Ability to provide property path in the `SortingColumnData`. The data table ensures valid property path is given (backwards compatible)
+- **[Feature]** The Doctrine ORM `EntityFilterType` no longer requires `form_options.choice_value` option as the identifier field name will be retrieved from Doctrine class metadata by default
+- **[Feature]** The `DateColumnType` that works exactly like `DateTimeColumnType`, but with date-only format by default
+- **[Breaking change]** The data table type persistence subject options are removed in favor of subject provider options (see more)
+- **[Breaking change]** Optimized exporting process - introduces breaking changes (see more)
+- **[Breaking change]** The `DataTableBuilder` methods to add columns, filters, actions and exporters has changed definition - the `type` argument is now nullable to prepare for future implementation of type guessers
+- **[Bugfix]** Fixed a bug in personalization form where changing the column visibility resulted in an exception
+- **[Bugfix]** The `CollectionColumnType` now renders without spaces around separator
+- **[Bugfix]** Default export data is now properly used within the export form 
+
+Internally, the columns, filters and exporters are now utilizing the builder pattern similar to data tables.
+Please note that this is a **breaking change** for applications using internal bundle classes!
+
+For a list of all breaking changes and deprecations, see the [upgrade guide](docs/upgrade-guide/0.14.md).
+
 # 0.13
 
 - **[Feature]** Batch actions ([see more](https://data-table-bundle.swroblewski.pl/features/actions/batch-actions/))
@@ -7,3 +33,4 @@
 - **[Feature]** MoneyColumnType with optional Intl integration ([see more](https://data-table-bundle.swroblewski.pl/reference/columns/types/money/))
 
 Internally, the actions are now utilizing the builder pattern similar to data tables.
+Please note that this is a **breaking change** for applications using internal bundle classes!
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2023 Sebastian Wróblewski
+Copyright (c) 2023-present Sebastian Wróblewski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
diff --git a/assets/controllers/batch.js b/assets/controllers/batch.js
diff --git a/assets/controllers/personalization.js b/assets/controllers/personalization.js
@@ -4,13 +4,21 @@ import Sortable from 'sortablejs'
 export default class extends Controller {
     static targets = [ 'visibleColumns', 'hiddenColumns' ]
 
+    #visibleColumnsSortable = null
+    #hiddenColumnSortable = null
+
     connect() {
-        this.#initializeSortable(this.visibleColumnsTarget)
-        this.#initializeSortable(this.hiddenColumnsTarget)
+        this.#visibleColumnsSortable = this.#initializeSortable(this.visibleColumnsTarget)
+        this.#hiddenColumnSortable = this.#initializeSortable(this.hiddenColumnsTarget)
+    }
+
+    disconnect() {
+        this.#visibleColumnsSortable.destroy();
+        this.#hiddenColumnSortable.destroy();
     }
 
     #initializeSortable(target) {
-        new Sortable(target, {
+        return new Sortable(target, {
             group: 'shared',
             animation: 150,
             onAdd: event => {
@@ -19,12 +27,16 @@ export default class extends Controller {
                 input.value = event.to.dataset.visible
             },
             onChange: event => {
-                const orderInput = event.item.querySelector('[name$="[order]"]')
-                const originalOrderInput = event.originalEvent.target.querySelector('[name$="[order]"]')
+                const priorityInput = event.item.querySelector('[name$="[priority]"]')
+                const originalPriorityInput = event.originalEvent.target.querySelector('[name$="[priority]"]')
 
-                orderInput.value = event.newIndex
-                originalOrderInput.value = event.oldIndex
+                priorityInput.value = this.#calculatePriority(target, event.newIndex)
+                originalPriorityInput.value = this.#calculatePriority(target, event.oldIndex)
             }
         })
     }
+
+    #calculatePriority(target, index) {
+        return target.childElementCount - index - 1;
+    }
 }
diff --git a/assets/package.json b/assets/package.json
diff --git a/composer.json b/composer.json
@@ -23,7 +23,8 @@
         "twig/intl-extra": "^3.6"
     },
     "require-dev": {
-        "friendsofphp/php-cs-fixer": "^3.13",
+        "roave/security-advisories": "dev-latest",
+        "friendsofphp/php-cs-fixer": "^3.23",
         "kubawerlos/php-cs-fixer-custom-fixers": "^3.11",
         "symfony/maker-bundle": "^1.48",
         "symfony/security-core": "^6.2",

diff --git a/docs/basic-usage/adding-actions.md b/docs/basic-usage/adding-actions.md
@@ -122,7 +122,7 @@ For reference, see [built-in action types](../components/actions/types.md).
 Let's assume that the application has an `app_product_show` route for showing details about specific product.
 This route requires a product identifier, therefore it has to be a row action.
 
-To add batch action, use the builder's `addRowAction()` method:
+To add row action, use the builder's `addRowAction()` method:
 
 ```php # src/DataTable/Type/ProductDataTableType.php
 use App\Entity\Product;

diff --git a/docs/basic-usage/adding-columns.md b/docs/basic-usage/adding-columns.md
diff --git a/docs/basic-usage/creating-data-tables.md b/docs/basic-usage/creating-data-tables.md
diff --git a/docs/basic-usage/defining-the-filters.md b/docs/basic-usage/defining-the-filters.md
diff --git a/docs/basic-usage/disclaimer.md b/docs/basic-usage/disclaimer.md
@@ -16,20 +16,37 @@ Instead, they contain links to the reference section, where you can about each f
 The articles assume, that the project uses [Doctrine ORM](https://www.doctrine-project.org/projects/orm.html) and contains a Product entity:
 
 ```php # src/Entity/Product.php
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
 class Product
 {
+    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
     private int $id;
+
+    #[ORM\Column]
     private string $name;
+
+    #[ORM\Column]
     private \DateTimeInterface $createdAt;
 
-    public function getId(): int {}
-    public function getName(): string {}
-    public function getCreatedAt(): \DateTimeInterface {}
+    public function getId(): int 
+    {
+        return $this->id;
+    }
+
+    public function getName(): string 
+    {
+        return $this->name;
+    }
+
+    public function getCreatedAt(): \DateTimeInterface 
+    {
+        return $this->createdAt;
+    }
 }
 ```
 
-For the sake of simplicity, the Doctrine mapping is skipped in the code block above.
-
 ## Frontend
 
 The examples contain screenshots using the built-in [Tabler UI Kit](https://tabler.io/) theme. 
diff --git a/docs/basic-usage/enabling-global-search.md b/docs/basic-usage/enabling-global-search.md
@@ -12,68 +12,47 @@ Sometimes all the user needs is a single text input, to quickly search through m
 To handle that, there's a built-in special filter, which allows doing exactly that.
 The uniqueness of this filter shines in the way it is rendered - in the built-in themes, instead of showing up in the filter form, it gets displayed above, always visible, easily accessible.
 
-## Adding the search filter
+## Adding the search handler
 
-To start, define a filter of search type — its name doesn't really matter:
+To define a search handler, use the builder's `setSearchHandler()` method to provide a callable,
+which gets an instance of query, and a search string as its arguments:
 
 ```php # src/DataTable/Type/ProductDataTableType.php
 use Kreyu\Bundle\DataTableBundle\DataTableBuilderInterface;
 use Kreyu\Bundle\DataTableBundle\Type\AbstractDataTableType;
-
-class ProductDataTableType extends AbstractDataTableType
-{
-    public function buildDataTable(DataTableBuilderInterface $builder, array $options): void
-    {
-        // Columns and filters added before...
-
-        $builder
-            ->addFilter('search', SearchFilterType::class)
-        ;
-    }
-}
-```
-
-Trying to display the data table with this filter configuration will result in an error:
-
-> The required option "handler" is missing.
-
-This is because the search filter type requires a `handler` option, which contains all the logic required for the data table search capabilities.
-
-## Writing the search handler
-
-The option accepts a callable, which gets an instance of query, and a search string as its arguments:
-
-```php #12 src/DataTable/Type/ProductDataTableType.php
-use Kreyu\Bundle\DataTableBundle\DataTableBuilderInterface;
-use Kreyu\Bundle\DataTableBundle\Type\AbstractDataTableType;
 use Kreyu\Bundle\DataTableBundle\Bridge\Doctrine\Orm\Query\DoctrineOrmProxyQuery;
 
 class ProductDataTableType extends AbstractDataTableType
 {
     public function buildDataTable(DataTableBuilderInterface $builder, array $options): void
     {
-        // Columns and filters added before...
-
         $builder
-            ->addFilter('search', SearchFilterType::class, [
-                'handler' => $this->handleSearchFilter(...),
-            ])
+            ->setSearchHandler($this->handleSearchFilter(...))
         ;
     }
 
-    /**
-     * @param DoctrineOrmProxyQuery $query
-     */
-    private function handleSearchFilter(ProxyQueryInterface $query, string $search): void
+    private function handleSearchFilter(DoctrineOrmProxyQuery $query, string $search): void
     {
+        $alias = current($query->getRootAliases());
+
+        // Remember to use parameters to prevent SQL Injection!
+        // To help with that, DoctrineOrmProxyQuery has a special method "getUniqueParameterId",
+        // that will generate a unique parameter name (inside its query context), handy!
+        $parameter = $query->getUniqueParameterId(); 
+
+        $query
+            ->andWhere($query->expr()->eq("$alias.type", ":$parameter"))
+            ->setParameter($parameter, $data->getValue())
+        ;
+
         $criteria = $query->expr()->orX(
-            $query->expr()->like('product.id', ':search'),
-            $query->expr()->like('product.name', ':search'),
+            $query->expr()->like("$alias.id", ":$parameter"),
+            $query->expr()->like("$alias.name", ":$parameter"),
         );
 
         $query
             ->andWhere($criteria)
-            ->setParameter('search', '%' . $search . '%')
+            ->setParameter($parameter, "%$search%")
         ;
     }
 }

diff --git a/docs/basic-usage/enabling-persistence.md b/docs/basic-usage/enabling-persistence.md
diff --git a/docs/basic-usage/exporting-the-data.md b/docs/basic-usage/exporting-the-data.md
diff --git a/docs/basic-usage/index.yml b/docs/basic-usage/index.yml
diff --git a/docs/basic-usage/internationalization.md b/docs/basic-usage/internationalization.md
diff --git a/docs/basic-usage/persisting-applied-data.md b/docs/basic-usage/persisting-applied-data.md
diff --git a/docs/basic-usage/rendering-the-table.md b/docs/basic-usage/rendering-the-table.md
@@ -38,13 +38,13 @@ class ProductController extends AbstractController
 
 Now, create the missing template, and render the data table:
 
-{%{
+{% raw %}
 ```twig # templates/product/index.html.twig
 <div class="card">
     {{ data_table(data_table) }}
 </div>
 ```
-}%}
+{% endraw %}
 
 Voilà! :sparkles: The Twig helper function handles all the work and renders the data table.
 

diff --git a/docs/basic-usage/summary.md b/docs/basic-usage/summary.md
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,18 @@
+---
+icon: heart
+
+---
+
+# Contributing
+
+## Documentation
+
+The documentation is powered by the [Retype](https://retype.com/). The articles are stored in the `docs/` directory.
+
+To locally preview the documentation, first, install the [Retype](https://retype.com/) locally.
+The installation instructions are available in the ["Getting Started" documentation section](https://retype.com/guides/getting-started/).
+Then, to build the documentation locally (and rebuild when change is detected), run the following command:
+
+```shell
+$ retype start docs
+```
diff --git a/docs/features/actions/actions.md b/docs/features/actions/actions.md
diff --git a/docs/features/actions/batch-actions.md b/docs/features/actions/batch-actions.md
diff --git a/docs/features/actions/global-actions.md b/docs/features/actions/global-actions.md
diff --git a/docs/features/actions/index.yml b/docs/features/actions/index.yml
@@ -0,0 +1 @@
+order: B
diff --git a/docs/features/actions/row-actions.md b/docs/features/actions/row-actions.md