[Feature] Per data table theming (#24)

feature: per data table theming
Kreyu · Jun 25, 2023 · d16b5ae · d16b5ae
1 parent 0603aa4
commit d16b5ae
Show file tree

Hide file tree

Showing 14 changed files with 250 additions and 69 deletions.
diff --git a/docs/features/theming.md b/docs/features/theming.md
@@ -22,29 +22,70 @@ The default template provides minimal HTML required to properly display the data
 
 ## Selecting a theme
 
-To select a theme, provide which one to use in the bundle configuration file.
+To select a theme, use `themes` option.
+
 For example, in order to use the [Bootstrap 5](https://getbootstrap.com/docs/5.0/) theme:
 
-+++ YAML
++++ Globally (YAML)
 ```yaml # config/packages/kreyu_data_table.yaml
 kreyu_data_table:
-  themes:
-    - '@KreyuDataTable/themes/bootstrap_5.html.twig'
+  defaults:
+    themes:
+      - '@KreyuDataTable/themes/bootstrap_5.html.twig'
 ```
-+++ PHP
++++ Globally (PHP)
 ```php # config/packages/kreyu_data_table.php
 use Symfony\Config\KreyuDataTableConfig;
 
 return static function (KreyuDataTableConfig $config) {
-    $config->themes([
+    $config->defaults()->themes([
         '@KreyuDataTable/themes/bootstrap_5.html.twig',
     ]);
 };
 ```
++++ For data table type
+```php # src/DataTable/Type/ProductDataTable.php
+use Kreyu\Bundle\DataTableBundle\Type\AbstractDataTableType;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+class ProductDataTableType extends AbstractDataTableType
+{
+    public function configureOptions(OptionsResolver $resolver): void
+    {
+        $resolver->setDefaults([
+            'themes' => [
+                '@KreyuDataTable/themes/bootstrap_5.html.twig',
+            ],
+        ]);
+    }
+}
+```
++++ For specific data table
+```php # src/Controller/ProductController.php
+use App\DataTable\Type\ProductDataTableType;
+use Kreyu\Bundle\DataTableBundle\DataTableFactoryAwareTrait;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+
+class ProductController extends AbstractController
+{
+    use DataTableFactoryAwareTrait;
+
+    public function index()
+    {
+        $dataTable = $this->createDataTable(
+            type: ProductDataTableType::class, 
+            query: $query,
+            options: [
+                'themes' => [
+                    '@KreyuDataTable/themes/bootstrap_5.html.twig',
+                ],
+            ],
+        );
+    }
+}
+```
 +++
 
-For more information, see ["themes" option configuration reference](../reference/configuration.md#themes).
-
 ## Customizing existing theme
 
 To customize existing theme, you can either:
@@ -59,29 +100,70 @@ using the built-in themes as a fallback, for example:
 
 ```twig
 {# templates/data_table/theme.html.twig #}
-{% block kreyu_data_table_column_boolean %}
+{% block column_boolean_value %}
     {# ... #}
 {% endblock %}
 ```
 
-+++ YAML
++++ Globally (YAML)
 ```yaml # config/packages/kreyu_data_table.yaml
 kreyu_data_table:
-  themes:
-    - 'templates/data_table/theme.html.twig'
-    - '@KreyuDataTable/themes/bootstrap_5.html.twig'
+  defaults:
+    themes:
+      - '@KreyuDataTable/themes/bootstrap_5.html.twig'
 ```
-+++ PHP
++++ Globally (PHP)
 ```php # config/packages/kreyu_data_table.php
 use Symfony\Config\KreyuDataTableConfig;
 
 return static function (KreyuDataTableConfig $config) {
-    $config->themes([
+    $config->defaults()->themes([
         'templates/data_table/theme.html.twig',
         '@KreyuDataTable/themes/bootstrap_5.html.twig',
     ]);
 };
 ```
++++ For data table type
+```php # src/DataTable/Type/ProductDataTable.php
+use Kreyu\Bundle\DataTableBundle\Type\AbstractDataTableType;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+class ProductDataTableType extends AbstractDataTableType
+{
+    public function configureOptions(OptionsResolver $resolver): void
+    {
+        $resolver->setDefaults([
+            'themes' => [
+                'templates/data_table/theme.html.twig',
+                '@KreyuDataTable/themes/bootstrap_5.html.twig',
+            ],
+        ]);
+    }
+}
+```
++++ For specific data table
+```php # src/Controller/ProductController.php
+use App\DataTable\Type\ProductDataTableType;
+use Kreyu\Bundle\DataTableBundle\DataTableFactoryAwareTrait;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+
+class ProductController extends AbstractController
+{
+    use DataTableFactoryAwareTrait;
+
+    public function index()
+    {
+        $dataTable = $this->createDataTable(
+            type: ProductDataTableType::class, 
+            query: $query,
+            options: [
+                'themes' => [
+                    'templates/data_table/theme.html.twig',
+                    '@KreyuDataTable/themes/bootstrap_5.html.twig',
+                ],
+            ],
+        );
+    }
+}
+```
 +++
-
-For more information, see ["themes" option configuration reference](../reference/configuration.md#themes).
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
@@ -1,32 +1,9 @@
 # Configuration
 
-This bundle can be configured using the `config/packages/kreyu_data_table.yaml` file.
+This bundle can be configured using the:
 
-## Themes
-
-You can define which Twig theme to use with the data tables using the `themes` node.
-By default, the base theme is used. Because themes are built using [Twig blocks](https://twig.symfony.com/doc/3.x/tags/block.html),
-the bundle iterates through given themes, until it finds the desired block, using the first one it finds.
-
-For more information about theming, see [theming reference](theming.md).
-
-+++ YAML
-```yaml # config/packages/kreyu_data_table.yaml
-kreyu_data_table:
-  themes:
-    - '@KreyuDataTable/themes/base.html.twig'
-```
-+++ PHP
-```php # config/packages/kreyu_data_table.php
-use Symfony\Config\KreyuDataTableConfig;
-
-return static function (KreyuDataTableConfig $config) {
-    $config->themes([
-        '@KreyuDataTable/themes/base.html.twig',
-    ]);
-};
-```
-+++
+- `config/packages/kreyu_data_table.yaml` (when using YAML configuration);
+- `config/packages/kreyu_data_table.php` (when using PHP configuration);
 
 ## Data table builder defaults
 
@@ -45,6 +22,8 @@ The given values represent the default ones, unless specifically stated otherwis
 ```yaml # config/packages/kreyu_data_table.yaml
 kreyu_data_table:
   defaults:
+    themes:
+      - '@KreyuDataTable/themes/base.html.twig'
     column_factory: kreyu_data_table.column.factory
     request_handler: kreyu_data_table.request_handler.http_foundation
     sorting:
@@ -93,6 +72,9 @@ return static function (KreyuDataTableConfig $config) {
     $defaults = $config->defaults();
 
     $defaults
+        ->themes([
+            '@KreyuDataTable/themes/base.html.twig'
+        ])
         ->columnFactory('kreyu_data_table.column.factory')
         ->requestHandler('kreyu_data_table.request_handler.http_foundation')
     ;

diff --git a/docs/reference/twig.md b/docs/reference/twig.md
@@ -78,21 +78,21 @@ based on the column configuration (e.g. to display formatted `name` of the `Proj
 
 ### `data_table_filters_form`
 
-**With arguments**: `data_table_filters_form(form)`
+**With arguments**: `data_table_filters_form(form, variables)`
 
 Renders the filters form. Accepts both the `FormInterface` and `FormView`.
 If given value is instance of `FormInterface`, the `createView()` method will be called.
 
 ### `data_table_personalization_form`
 
-**With arguments**: `data_table_personalization_form(form)`
+**With arguments**: `data_table_personalization_form(form, variables)`
 
 Renders the personalization form. Accepts both the `FormInterface` and `FormView`.
 If given value is instance of `FormInterface`, the `createView()` method will be called.
 
 ### `data_table_export_form`
 
-**With arguments**: `data_table_export_form(form)`
+**With arguments**: `data_table_export_form(form, variables)`
 
 Renders the export form. Accepts both the `FormInterface` and `FormView`.
 If given value is instance of `FormInterface`, the `createView()` method will be called.
@@ -117,6 +117,7 @@ The following variables are common to every data table type:
 
 | Variable                         | Usage                                                                                                                                  |
 |----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| `themes`                         | Themes to apply for the data table.                                                                                                    |
 | `name`                           | Name of the data table.                                                                                                                |
 | `title`                          | Title of the data table                                                                                                                |
 | `title_translation_parameters`   | Parameters used in title translation.                                                                                                  |

diff --git a/src/Action/ActionView.php b/src/Action/ActionView.php
@@ -17,4 +17,13 @@ public function __construct(
         public DataTableView|ColumnValueView $parent,
     ) {
     }
+
+    public function getDataTable(): DataTableView
+    {
+        if ($this->parent instanceof ColumnValueView) {
+            return $this->parent->parent->parent;
+        }
+
+        return $this->parent;
+    }
 }
diff --git a/src/Column/ColumnHeaderView.php b/src/Column/ColumnHeaderView.php
@@ -4,6 +4,7 @@
 
 namespace Kreyu\Bundle\DataTableBundle\Column;
 
+use Kreyu\Bundle\DataTableBundle\DataTableView;
 use Kreyu\Bundle\DataTableBundle\HeaderRowView;
 
 class ColumnHeaderView
@@ -16,4 +17,9 @@ public function __construct(
         public HeaderRowView $parent,
     ) {
     }
+
+    public function getDataTable(): DataTableView
+    {
+        return $this->parent->parent;
+    }
 }
diff --git a/src/Column/ColumnValueView.php b/src/Column/ColumnValueView.php
@@ -4,6 +4,7 @@
 
 namespace Kreyu\Bundle\DataTableBundle\Column;
 
+use Kreyu\Bundle\DataTableBundle\DataTableView;
 use Kreyu\Bundle\DataTableBundle\ValueRowView;
 
 class ColumnValueView
@@ -19,4 +20,9 @@ public function __construct(
         public ValueRowView $parent,
     ) {
     }
+
+    public function getDataTable(): DataTableView
+    {
+        return $this->parent->parent;
+    }
 }
diff --git a/src/DataTableBuilder.php b/src/DataTableBuilder.php
@@ -47,6 +47,13 @@ class DataTableBuilder implements DataTableBuilderInterface
      */
     private array $options;
 
+    /**
+     * Stores an array of themes to used to render the data table.
+     *
+     * @var array<string>
+     */
+    private array $themes;
+
     /**
      * User-friendly title used to describe a data table.
      */
@@ -315,6 +322,34 @@ public function setOptions(array $options): static
         return $this;
     }
 
+    public function getThemes(): array
+    {
+        return $this->themes;
+    }
+
+    public function setThemes(array $themes): static
+    {
+        $this->themes = $themes;
+
+        return $this;
+    }
+
+    public function addTheme(string $theme): static
+    {
+        $this->themes[] = $theme;
+
+        return $this;
+    }
+
+    public function removeTheme(string $theme): static
+    {
+        if (false !== $key = array_search($theme, $this->themes, true)) {
+            unset($this->themes[$key]);
+        }
+
+        return $this;
+    }
+
     public function getTitle(): null|string|TranslatableMessage
     {
         return $this->title;

diff --git a/src/DataTableConfigBuilderInterface.php b/src/DataTableConfigBuilderInterface.php
@@ -32,6 +32,12 @@ public function setType(ResolvedDataTableTypeInterface $type): static;
 
     public function setOptions(array $options): static;
 
+    public function setThemes(array $themes): static;
+
+    public function addTheme(string $theme): static;
+
+    public function removeTheme(string $theme): static;
+
     public function setTitle(null|string|TranslatableMessage $title): static;
 
     public function setTitleTranslationParameters(array $titleTranslationParameters): static;

diff --git a/src/DataTableConfigInterface.php b/src/DataTableConfigInterface.php
@@ -42,6 +42,8 @@ public function getType(): ResolvedDataTableTypeInterface;
 
     public function getOptions(): array;
 
+    public function getThemes(): array;
+
     public function getTitle(): null|string|TranslatableMessage;
 
     public function getTitleTranslationParameters(): array;