0.4.0 (#13)

Refactored data table view hierarchy, columns and filters. 
Added an option to enable action confirmation modal.
Added an option to define header and value rows html attributes.

docs/philosophy/understanding-types-api.md

@@ -34,12 +34,12 @@ The type-specific options are defined in the `configureOptions()` method, using
 ### Type inheritance
 
 Similar to the form types, the type inheritance should be handled using the `getParent()` method.
-For example, while a `NumericColumnType` technically extends the `TextColumnType`, it should **NOT** extend its class:
+For example, while a `PhoneColumnType` technically extends the `TextColumnType`, it should **NOT** extend its class:
 
 !!! failure "Do NOT use PHP class inheritance!"
 
     ```php
-    class NumericColumnType extends TextColumnType
+    class PhoneColumnType extends TextColumnType
     {
     }
     ```
@@ -49,7 +49,7 @@ Instead, it should return the FQCN of the parent type in the `getParent()` metho
 !!! success "Extend abstract type and use `getParent()` method instead!"
 
     ```php
-    class NumericColumnType implements AbstractColumnType
+    class PhoneColumnType implements AbstractColumnType
     {
         public function getParent(): string
         {
@@ -59,7 +59,7 @@ Instead, it should return the FQCN of the parent type in the `getParent()` metho
     ```
 
 The difference is about the extensions - considering the example above, while using the PHP inheritance, 
-a column type extensions that extend the `TextColumnType` won't be applied to the `NumericColumnType`.
+a column type extensions that extend the `TextColumnType` won't be applied to the `PhoneColumnType`.
 
 ## Type extension definition
 
@@ -79,18 +79,18 @@ which already implements the interface and provides some utilities.
 ### Type extension targets
 
 Each type extension class defines a list of types that it extends inside its static `getExtendedTypes()` method.
-For example, if you wish to create an extension that extends a `NumericColumnType`, consider following configuration:
+For example, if you wish to create an extension that extends a `PhoneColumnType`, consider following configuration:
 
 ```php
-use Kreyu\Bundle\DataTableBundle\Column\Type\NumericColumnType;
+use App\DataTable\Column\Type\PhoneColumnType;
 use Kreyu\Bundle\DataTableBundle\Column\Extension\ColumnTypeExtension;
 
-class NumericColumnTypeExtension extends AbstractColumnTypeExtension
+class PhoneColumnTypeExtension extends AbstractColumnTypeExtension
 {
     public static function getExtendedTypes(): iterable
     {
-        return [NumericColumnType::class];
-    } 
+        return [PhoneColumnType::class];
+    }
 }
 ```
 

docs/philosophy/understanding-views-api.md

@@ -0,0 +1,124 @@
+# Understanding the Views API
+
+Similar to Symfony Forms, this bundle uses a View classes, that can be used to render the data table.
+
+```
+DataTableView
+├── HeaderRowView
+│   ├── ColumnHeaderView
+│   ├── ColumnHeaderView
+│   └── ...
+├── ValueRowView
+│   ├── ColumnValueView
+│   ├── ColumnValueView
+│   └── ...
+└── ValueRowView
+    ├── ColumnValueView
+    ├── ColumnValueView
+    └── ...
+```
+
+The `DataTableView` is the root of the view hierarchy. 
+It contains a collection of `HeaderRowView` and `ValueRowView` instances. 
+Each of these views contains a collection of `ColumnHeaderView` and `ColumnValueView` instances.
+
+## `HeaderRowView`
+
+The `HeaderRowView` represents a row of headers. It contains two additional properties:
+
+`parent`
+
+:   Holds a reference to a `DataTableView`, which represents the whole data table.
+
+`children`
+
+:   Holds collection of `ColumnHeaderView` instances, so you can use it to render row columns.
+    Instead of accessing the `children` property, you can iterate on the `HeaderRowView` directly:
+
+    ```twig
+    {% for row in header_rows %}
+        {% for column in row %}
+            {# ... #}
+        {% endfor %}
+    {% endfor %}
+    ```
+
+
+## `ValueRowView`
+
+The `ValueRowView` represents a row of data. It contains five additional properties:
+
+`parent`
+
+:   Holds a reference to a `DataTableView`, which represents the whole data table.
+
+`children`
+
+:   Holds collection of `ColumnValueView` instances, so you can use it to render row columns.
+    Instead of accessing the `children` property, you can iterate on the `ValueRowView` directly:
+
+    ```twig
+    {% for row in value_rows %}
+        {% for column in row %}
+            {# ... #}
+        {% endfor %}
+    {% endfor %}
+    ```
+
+`index`
+
+:   Holds the index of a current row, so you can use it to render a row number:
+
+    ```twig
+    {% for row in value_rows %}
+        {{ row.index }}
+    {% endfor %}
+    ```
+
+`data`
+
+:   Holds the data of a current row, so you can use it to access the data of a row:
+
+    ```twig
+    {% for row in value_rows %}
+        {{ row.data.id }}
+    {% endfor %}
+    ```
+
+`origin`
+
+:   Holds a reference to a `ValueRowView` that was used as an origin of the virtual value row.
+    Virtual value rows are used internally in a [CollectionColumnType](../reference/column-types/collection-column-type.md),
+    where each entry contains its own `ValueRowView` with scoped data and indexes.
+
+## `ColumnHeaderView`
+
+The `ColumnHeaderView` represents a header of a column. It contains one additional property:
+
+`parent`
+
+:   Holds a reference to a `HeaderRowView`, which represents the row of data table headers.
+
+
+## `ColumnValueView`
+
+The `ColumnHeaderView` represents a header of a column. It contains three additional properties:
+
+`parent`
+
+:   Holds a reference to a `ValueRowView`, which represents the row of data table headers.
+    It can be used to retrieve, for example, an index or data of a row that the column belongs to.
+
+`data`
+
+:   Holds the norm data of a column. In most cases, this property will equal the `value` property,
+    but in some cases, it will be different. For example, if a column represents an object value,
+    the `value` property will contain a string representation of the object, while the `data` property
+    will contain the object itself.
+
+`value`
+
+:   Holds the string representation of a column value. In most cases, this property will equal the `data` property,
+    but in some cases, it will be different. For example, if a column has a callable `formatter` specified,
+    the `value` property will contain the result of the callable, while the `data` property will contain
+    the original value.

docs/reference/columns/creating_custom_column_type.md

@@ -136,13 +136,17 @@ class QuantityColumnType extends AbstractColumnType
 
 These are the most important methods that a column type class can define:
 
-`buildView()`
+`buildHeaderView()`
 
-:   It sets any extra variables you'll need when rendering the column in a template.
+:   It sets any extra variables you'll need when rendering the column header in a template.
+
+`buildValueView()`
+
+:   It sets any extra variables you'll need when rendering the column value in a template.
 
 `configureOptions()`
 
-:   It defines the options configurable when using the column type, which are also the options that can be used in `buildView()` method.
+:   It defines the options configurable when using the column type, which are also the options that can be used in `buildHeaderView()` and `buildValueView()` methods.
     Options are inherited from parent types and parent type extensions, but you can create any custom option you need.
 
 `getParent()`
@@ -277,7 +281,7 @@ You can also pass your own variables, which can be based on the options defined
 namespace App\DataTable\Column\Type;
 
 use Kreyu\Bundle\DataTableBundle\Column\ColumnInterface;
-use Kreyu\Bundle\DataTableBundle\Column\ColumnView;
+use Kreyu\Bundle\DataTableBundle\Column\ColumnValueView;
 use Kreyu\Bundle\DataTableBundle\Column\Type\AbstractColumnType;
 use Kreyu\Bundle\DataTableBundle\Column\Type\LinkColumnType;
 use Symfony\Component\OptionsResolver\OptionsResolver;
@@ -289,7 +293,7 @@ class QuantityColumnType extends AbstractColumnType
     {
     }
 
-    public function buildView(ColumnView $view, ColumnInterface $column, array $options): void
+    public function buildValueView(ColumnValueView $view, ColumnInterface $column, array $options): void
     {    
         // pass the custom options directly to the template
         $view->vars['decimals'] = $options['decimals'];
@@ -311,14 +315,14 @@ class QuantityColumnType extends AbstractColumnType
 }
 ```
 
-The variables added in `buildView()` are available in the column type template as any other regular Twig variable:
+The variables added in `buildValueView()` are available in the column type template as any other regular Twig variable:
 
 {% raw %}
 ```twig
 {# templates/data_table/theme.html.twig #}
 {% extends '@KreyuDataTable/themes/bootstrap_5.html.twig' %}
 
-{% block data_table_quantity %}
+{% block kreyu_data_table_column_quantity %}
     {% if converted_value is not null %}
         {{- converted_value|number_format(decimals, decimal_separator, thousands_separator) -}}
     {% endif %}

docs/reference/twig.md

@@ -38,13 +38,13 @@ Renders the HTML of the data table.
 
 Renders the HTML of the data table action bar, which includes filtration, exporting and personalization features.
 
-### `data_table_headers_row(headers_row_view, variables)`
+### `data_table_header_row(header_row_view, variables)`
 
-Renders the headers row of the data table.
+Renders the header row of the data table.
 
-### `data_table_values_row(values_row_view, variables)`
+### `data_table_value_row(value_row_view, variables)`
 
-Renders the values row of the data table.
+Renders the value row of the data table.
 
 ### `data_table_column_label(column_view, variables)`
 
@@ -107,8 +107,8 @@ The following variables are common to every data table type.
 | `filtration_form`                | Holds an instance of the filtration form view.                                                                                         |
 | `personalization_form`           | Holds an instance of the personalization form view.                                                                                    |
 | `export_form`                    | Holds an instance of the export form view.                                                                                             |
-| `headers_row`                    | Holds an instance of the headers row view.                                                                                             |
-| `values_rows`                    | List of value rows views.                                                                                                              |
+| `header_row`                     | Holds an instance of the header row view.                                                                                              |
+| `value_rows`                     | Holds a collection of the value rows views.                                                                                            |
 | `pagination`                     | Holds an instance of the pagination view.                                                                                              |
 | `has_active_filters`             | Contains information whether the data table has at least one filter active.                                                            |
 | `label_translation_domain`       | Contains a translation domain used to translate column & filter labels, unless specified manually on the column or filter              |

mkdocs.yml

@@ -37,6 +37,7 @@ nav:
       - 'Usage': 'getting-started/usage.md'
     - 'Philosophy':
       - 'Understanding the Types API': 'philosophy/understanding-types-api.md'
+      - 'Understanding the Views API': 'philosophy/understanding-views-api.md'
   - 'Reference':
     - 'Columns':
       - 'reference/columns/index.md'

src/Action/Action.php

@@ -5,12 +5,11 @@
 namespace Kreyu\Bundle\DataTableBundle\Action;
 
 use Kreyu\Bundle\DataTableBundle\Action\Type\ResolvedActionTypeInterface;
+use Kreyu\Bundle\DataTableBundle\Column\ColumnValueView;
 use Kreyu\Bundle\DataTableBundle\DataTableView;
 
 class Action implements ActionInterface
 {
-    private mixed $data = null;
-
     public function __construct(
         private string $name,
         private ResolvedActionTypeInterface $type,
@@ -33,17 +32,7 @@ public function getOptions(): array
         return $this->options;
     }
 
-    public function getData(): mixed
-    {
-        return $this->data;
-    }
-
-    public function setData(mixed $data): void
-    {
-        $this->data = $data;
-    }
-
-    public function createView(DataTableView $parent = null): ActionView
+    public function createView(DataTableView|ColumnValueView $parent): ActionView
     {
         $view = $this->type->createView($this, $parent);
 

src/Action/ActionInterface.php

@@ -5,6 +5,7 @@
 namespace Kreyu\Bundle\DataTableBundle\Action;
 
 use Kreyu\Bundle\DataTableBundle\Action\Type\ResolvedActionTypeInterface;
+use Kreyu\Bundle\DataTableBundle\Column\ColumnValueView;
 use Kreyu\Bundle\DataTableBundle\DataTableView;
 
 interface ActionInterface
@@ -15,9 +16,5 @@ public function getType(): ResolvedActionTypeInterface;
 
     public function getOptions(): array;
 
-    public function getData(): mixed;
-
-    public function setData(mixed $data): void;
-
-    public function createView(DataTableView $parent = null): ActionView;
+    public function createView(DataTableView|ColumnValueView $parent): ActionView;
 }

src/Action/ActionView.php

@@ -4,14 +4,17 @@
 
 namespace Kreyu\Bundle\DataTableBundle\Action;
 
+use Kreyu\Bundle\DataTableBundle\Column\ColumnValueView;
 use Kreyu\Bundle\DataTableBundle\DataTableView;
 
 class ActionView
 {
-    public array $vars = [];
+    public array $vars = [
+        'attr' => [],
+    ];
 
     public function __construct(
-        public ?DataTableView $parent = null,
+        public DataTableView|ColumnValueView $parent,
     ) {
     }
 }