Add docs for dropdown-related action types

Kreyu · Jan 12, 2025 · b6ab102 · b6ab102
1 parent 753e28b
commit b6ab102
Show file tree

Hide file tree

Showing 4 changed files with 177 additions and 0 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -134,6 +134,12 @@ export default defineConfig({
                 { text: 'Link', link: '/reference/types/action/link' },
                 { text: 'Button', link: '/reference/types/action/button' },
                 { text: 'Form', link: '/reference/types/action/form' },
+                {
+                  text: 'Dropdown', link: '/reference/types/action/dropdown',
+                  items: [
+                    { text: 'LinkDropdownItem', link: '/reference/types/action/link-dropdown-item' },
+                  ],
+                },
                 { text: 'Action', link: '/reference/types/action/action' },
               ],
             },

diff --git a/docs/src/docs/components/actions.md b/docs/src/docs/components/actions.md
@@ -569,3 +569,32 @@ If `FormActionType` is used, the scripts will append hidden inputs with selected
 <input type="hidden" name="product_id[]" value="1">
 <input type="hidden" name="category_id[]" value="4">
 ```
+
+## Dropdown actions
+
+In some cases, it may be useful to group multiple actions under a single dropdown.
+
+To do so, define an action using the [`DropdownActionType`](../../reference/types/action/dropdown.md) type:
+Then, define child actions under its `actions` array. Each child action can be created using the builder's `createAction`, `createRowAction` or `createBatchAction` method, depending on the context:
+
+```php
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\DropdownActionType;
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\LinkDropdownItemActionType;
+
+$builder
+    ->addRowAction('advanced', DropdownActionType::class, [
+        'actions' => [
+            $builder->createRowAction('update', LinkDropdownItemActionType::class, [
+                'href' => fn (Post $post) => $this->urlGenerator->generate('post_delete', [
+                    'id' => $post->getId(),
+                ]),            
+            ]),
+        ],
+    ])
+;
+```
+
+> [!TIP]
+> Although any action type can be used, rendering forms and buttons inside a dropdown may look weird.
+> Therefore, it is recommended to use [`LinkDropdownItemActionType`](../../reference/types/action/link-dropdown-item.md) for dropdown items,
+> so it will be rendered properly as a simple link.
diff --git a/docs/src/reference/types/action/dropdown.md b/docs/src/reference/types/action/dropdown.md
@@ -0,0 +1,61 @@
+<script setup>
+    import ActionTypeOptions from "./options/action.md";
+</script>
+
+# DropdownActionType
+
+The [`DropdownActionType`](https://github.com/Kreyu/data-table-bundle/blob/main/src/Action/Type/DropdownActionType.php) represents an action rendered as a dropdown, where each item corresponds to separate action.
+
+## Options
+
+### `actions`
+
+- **type**: `array` or `callable` (if using as a row action)
+- **default**: `[]`
+
+An array of actions that will be rendered as dropdown items.
+Each action can be created using `createAction`, `createRowAction` or `createBatchAction` method, depending on the context:
+
+```php
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\DropdownActionType;
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\LinkDropdownItemActionType;
+
+$builder
+    ->addAction('advanced', DropdownActionType::class, [
+        'actions' => [
+            $builder->createAction('update', LinkDropdownItemActionType::class, [
+                'href' => '#'            
+            ]),
+        ],
+    ])
+;
+```
+
+When using the `DropdownActionType` as a [row action](../../../docs/components/actions.md), you can provide a callable
+that will receive the row data as an argument and should return an array of actions.
+
+```php
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\DropdownActionType;
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\LinkDropdownItemActionType;
+
+$builder
+    ->addRowAction('advanced', DropdownActionType::class, [
+        'actions' => fn (Post $post) => [
+            $builder->createRowAction('update', LinkDropdownItemActionType::class, [
+                'href' => $this->urlGenerator->generate('post_update', [
+                    'id' => $post->getId(),
+                ]),
+            ]),
+        ],
+    ])
+;
+```
+
+> [!TIP]
+> Although any action type can be used, rendering forms and buttons inside a dropdown may look weird.
+> Therefore, it is recommended to use [`LinkDropdownItemActionType`](link-dropdown-item.md) for dropdown items,
+> so it will be rendered properly as a simple link.
+
+## Inherited options
+
+<ActionTypeOptions/>
diff --git a/docs/src/reference/types/action/link-dropdown-item.md b/docs/src/reference/types/action/link-dropdown-item.md
@@ -0,0 +1,81 @@
+<script setup>
+    import ActionTypeOptions from "./options/action.md";
+</script>
+
+# LinkDropdownItemActionType
+
+The [`LinkDropdownItemActionType`](https://github.com/Kreyu/data-table-bundle/blob/main/src/Action/Type/Dropdown/LinkDropdownItemActionType.php) 
+represents an action rendered as dropdown item with a simple link.  It is meant to be used as a child of the [`DropdownActionType`](dropdown.md).
+
+## Options
+
+### `href`
+
+- **type**: `string` or `callable` (if using as a row action)
+- **default**: `'#'`
+
+A value used as an action link [href attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href).
+
+```php
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\DropdownActionType;
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\LinkDropdownItemActionType;
+
+$builder
+    ->addAction('advanced', DropdownActionType::class, [
+        'actions' => [
+            $builder->createAction('update', LinkDropdownItemActionType::class, [
+                'href' => fn (Post $post) => $this->urlGenerator->generate('post_update', [
+                    'id' => $post->getId(),
+                ]),           
+            ]),
+        ],
+    ])
+;
+```
+
+When using the `LinkDropdownItemActionType` as a [row action](../../../docs/components/actions.md), you can provide a callable
+that will receive the row data as an argument and should return an array of actions.
+
+```php
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\DropdownActionType;
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\LinkDropdownItemActionType;
+
+$builder
+    ->addRowAction('advanced', DropdownActionType::class, [
+        'actions' => [
+            $builder->createRowAction('update', LinkDropdownItemActionType::class, [
+                'href' => fn (Post $post) => $this->urlGenerator->generate('post_update', [
+                    'id' => $post->getId(),
+                ]),            
+            ]),
+        ],
+    ])
+;
+```
+
+### `target`
+
+- **type**: `string` or `callable`
+- **default**: `'_self'`
+
+Sets the value that will be used as an anchor [target attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target).
+
+```php
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\DropdownActionType;
+use Kreyu\Bundle\DataTableBundle\Action\Type\Dropdown\LinkDropdownItemActionType;
+
+$builder
+    ->addAction('preview', DropdownActionType::class, [
+        'actions' => [
+            $builder->createAction('render', LinkDropdownItemActionType::class, [
+                'href' => '#',
+                'target' => '_blank',
+            ]),
+        ],
+    ])
+;
+```
+
+## Inherited options
+
+<ActionTypeOptions/>