From 04ad976f8dacdd4c8353bd5f7c7b7708f7f145ae Mon Sep 17 00:00:00 2001 From: Jonathan Lelievre Date: Mon, 4 Feb 2019 18:54:04 +0100 Subject: [PATCH] Add PositionUpdater component doc, and update columns references docs --- .../grid/columns-reference/_index.md | 31 ++- .../grid/columns-reference/action.md | 24 +- .../grid/columns-reference/badge.md | 35 +++ .../grid/columns-reference/bulk-action.md | 21 +- .../components/grid/columns-reference/data.md | 11 +- .../grid/columns-reference/datetime.md | 26 +- .../employee-name-with-avatar.md | 18 +- .../grid/columns-reference/image.md | 32 +++ .../components/grid/columns-reference/link.md | 38 +++ .../grid/columns-reference/position.md | 62 +++++ .../grid/columns-reference/severity-level.md | 26 +- .../grid/columns-reference/toggle.md | 38 +++ .../components/grid/tutorials/_index.md | 2 +- .../components/position-updater/_index.md | 236 ++++++++++++++++++ 14 files changed, 523 insertions(+), 77 deletions(-) create mode 100644 src/content/1.7/development/components/grid/columns-reference/badge.md create mode 100644 src/content/1.7/development/components/grid/columns-reference/image.md create mode 100644 src/content/1.7/development/components/grid/columns-reference/link.md create mode 100644 src/content/1.7/development/components/grid/columns-reference/position.md create mode 100644 src/content/1.7/development/components/grid/columns-reference/toggle.md create mode 100644 src/content/1.7/development/components/position-updater/_index.md diff --git a/src/content/1.7/development/components/grid/columns-reference/_index.md b/src/content/1.7/development/components/grid/columns-reference/_index.md index 7d8b8b5cfb..de5bf51a66 100644 --- a/src/content/1.7/development/components/grid/columns-reference/_index.md +++ b/src/content/1.7/development/components/grid/columns-reference/_index.md @@ -4,38 +4,51 @@ menuTitle: Column Types reference weight: 10 --- -## Column Types reference +# Column Types reference +{{< minver v="1.7.5" title="true" >}} Most important Grid definition part is defining columns. PrestaShop already comes with a list of predefined columns that you can use in your own Grids. -### Supported Types +## Supported Types -#### Basic columns +### Basic columns * [DataColumn][data-column-reference] +* [DateTimeColumn][datetime-column-reference] +* [ImageColumn][image-column-reference] +* [ToggleColumn][toggle-column-reference] +* [BadgeColumn][badge-column-reference] {{< minver v="1.7.6" >}} +* [LinkColumn][link-column-reference] {{< minver v="1.7.6" >}} -#### Common columns +### Action columns * [ActionColumn][action-column-reference] * [BulkActionColumn][bulk-action-column-reference] -* [DateTimeColumn][datetime-column-reference] +* [PositionColumn][position-column-reference] -#### Employee columns +### Employee columns * [EmployeeNameWithAvatarColumn][employee-name-wit-avatar-column-reference] -#### Status columns +### Status columns * [SeverityLevelColumn][severity-column-reference] [data-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/data.md" >}} +[datetime-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/datetime.md" >}} +[image-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/image.md" >}} +[toggle-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/toggle.md" >}} +[badge-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/badge.md" >}} +[link-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/link.md" >}} + [action-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/action.md" >}} [bulk-action-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/bulk-action.md" >}} -[datetime-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/datetime.md" >}} +[position-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/position.md" >}} + [employee-name-wit-avatar-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/employee-name-with-avatar.md" >}} [severity-column-reference]: {{< ref "/1.7/development/components/grid/columns-reference/severity-level.md" >}} -## Use case exemple +## Use case example ```php }} -This type of column allows to add actions to your Grid rows. +This type of column allows to add actions to your Grid rows. The action target the corresponding row. +For more info about possible actions see [Actions reference][actions-reference]. ## Available options -### field - -**actions:** `array|null` **default:** `null` - -Record field name which will be used as bulk action checkbox value. +| Properties | Type | Expected value | +| ----------- | ----- | --------------------------------------------------------- | +| **actions** | array | **default:** `null` List of actions assigned to each row. | ## Example usage @@ -22,9 +22,9 @@ Record field name which will be used as bulk action checkbox value. use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\ActionColumn; use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; -$productColumn = new ActionColumn('actions'); -$productColumn->setName('Actions'); -$productColumn->setOptions([ +$actionColumn = new ActionColumn('actions'); +$actionColumn->setName('Actions'); +$actionColumn->setOptions([ 'actions' => [ ->add((new LinkRowAction('delete')) ->setIcon('delete') @@ -39,5 +39,7 @@ $productColumn->setOptions([ ]); $columns = new ColumnCollection(); -$columns->add($productColumn); +$columns->add($actionColumn); ``` + +[actions-reference]: {{< ref "/1.7/development/components/grid/actions-reference/_index.md" >}} diff --git a/src/content/1.7/development/components/grid/columns-reference/badge.md b/src/content/1.7/development/components/grid/columns-reference/badge.md new file mode 100644 index 0000000000..94731768a3 --- /dev/null +++ b/src/content/1.7/development/components/grid/columns-reference/badge.md @@ -0,0 +1,35 @@ +--- +title: BadgeColumn reference +menuTitle: BadgeColumn +weight: 10 +--- + +# BadgeColumn Type +{{< minver v="1.7.6" title="true" >}} + +This basic BadgeColumn displays a raw field data in Grid, associated with a badge. + +## Available options + +| Properties | Type | Expected value | +| -------------- | ------ | ---------------------------------------------------------------------------------- | +| **field** | string | **required** Record field name which column displays. | +| **badge_type** | string | **default:** `success` Indicates which field of the row contains the image source. (*Allowed values:* `success, info, danger, warning`) | + +## Example usage + +```php +use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\BadgeColumn; +use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; + +$badgeColumn = new BadgeColumn('total_spent'); +$badgeColumn->setName('Sales'); +$badgeColumn->setOptions([ + 'field' => 'total_spent', + 'badge_type' => 'success', + 'empty_value' => '--', +]); + +$columns = new ColumnCollection(); +$columns->add($badgeColumn); +``` \ No newline at end of file diff --git a/src/content/1.7/development/components/grid/columns-reference/bulk-action.md b/src/content/1.7/development/components/grid/columns-reference/bulk-action.md index b65e8fd842..f1ad2ec28c 100644 --- a/src/content/1.7/development/components/grid/columns-reference/bulk-action.md +++ b/src/content/1.7/development/components/grid/columns-reference/bulk-action.md @@ -1,20 +1,19 @@ --- title: BulkActionColumn reference menuTitle: BulkActionColumn -weight: 60 +weight: 20 --- # BulkActionColumn Type +{{< minver v="1.7.5" title="true" >}} -This type of column allows to add bulk action checkboxes to your Grid. +This type of column allows to add bulk action checkboxes to your Grid. This only add the checkbox in the grid, you can then manage bulk actions via javascript. ## Available options -### field - -**bulk_field:** `string` **required** - -Record field name which will be used as bulk action checkbox value. +| Properties | Type | Expected value | +| -------------- | ------ | --------------------------------------------------------------------------------- | +| **bulk_field** | string | **required:** Record field name which will be used as bulk action checkbox value. | ## Example usage @@ -22,12 +21,12 @@ Record field name which will be used as bulk action checkbox value. use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\BulkActionColumn; use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; -$productColumn = new BulkActionColumn('bulk_action'); -$productColumn->setName(''); // it is common set empty name for bulk action columns -$productColumn->setOptions([ +$bulkActionColumn = new BulkActionColumn('bulk_action'); +$bulkActionColumn->setName(''); // it is common set empty name for bulk action columns +$bulkActionColumn->setOptions([ 'bulk_field' => 'id_product', ]); $columns = new ColumnCollection(); -$columns->add($productColumn); +$columns->add($bulkActionColumn); ``` \ No newline at end of file diff --git a/src/content/1.7/development/components/grid/columns-reference/data.md b/src/content/1.7/development/components/grid/columns-reference/data.md index 62ef82f263..1623bfb66d 100644 --- a/src/content/1.7/development/components/grid/columns-reference/data.md +++ b/src/content/1.7/development/components/grid/columns-reference/data.md @@ -1,20 +1,19 @@ --- title: DataColumn reference menuTitle: DataColumn -weight: 60 +weight: 10 --- # DataColumn Type +{{< minver v="1.7.5" title="true" >}} The most basic column is DataColumn. It is used to display raw field data in Grid. ## Available options -### field - -**type:** `string` **required** - -Record field name which column displays. +| Properties | Type | Expected value | +| ---------- | ------ | ----------------------------------------------------- | +| **field** | string | **required** Record field name which column displays. | ## Example usage diff --git a/src/content/1.7/development/components/grid/columns-reference/datetime.md b/src/content/1.7/development/components/grid/columns-reference/datetime.md index 70f24be403..c86cab3fe4 100644 --- a/src/content/1.7/development/components/grid/columns-reference/datetime.md +++ b/src/content/1.7/development/components/grid/columns-reference/datetime.md @@ -1,27 +1,21 @@ --- title: DateTimeColumn reference menuTitle: DateTimeColumn -weight: 70 +weight: 10 --- # DateTimeColumn Type +{{< minver v="1.7.5" title="true" >}} You can use this column type in your Grid to format datetime values. It is common to get datetime value (e.g. Created at, Updated at & etc.) from database and format them before displaying. ## Available options -### field - -**type:** `string` **required** - -Field name which has datetime value. - -### format - -**type:** `string` **default:** `Y-m-d H:i:s` - -Format to use when formatting datetime. +| Properties | Type | Expected value | +| ----------- | ------ | ------------------------------------------------------------------ | +| **field** | string | **required** Record field name which column displays. | +| **format** | string | **default:** `Y-m-d H:i:s` Format to use when formatting datetime. | ## Example usage @@ -29,13 +23,13 @@ Format to use when formatting datetime. use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\DateTimeColumn; use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; -$column = new DateTimeColumn('datetime'); -$column->setName('Created at'); -$column->setOptions([ +$dateTimeColumn = new DateTimeColumn('datetime'); +$dateTimeColumn->setName('Created at'); +$dateTimeColumn->setOptions([ 'field' => 'date_add', // field name that has datetime value 'format' => 'Y/d/m H:i:s', // define custom format for datetime ]); $columns = new ColumnCollection(); -$columns->add($column); +$columns->add($dateTimeColumn); ``` \ No newline at end of file diff --git a/src/content/1.7/development/components/grid/columns-reference/employee-name-with-avatar.md b/src/content/1.7/development/components/grid/columns-reference/employee-name-with-avatar.md index 240128db95..52fb56734c 100644 --- a/src/content/1.7/development/components/grid/columns-reference/employee-name-with-avatar.md +++ b/src/content/1.7/development/components/grid/columns-reference/employee-name-with-avatar.md @@ -1,10 +1,11 @@ --- title: EmployeeNameWithAvatarColumn reference menuTitle: EmployeeNameWithAvatarColumn -weight: 70 +weight: 60 --- # EmployeeNameWithAvatarColumn Type +{{< minver v="1.7.5" title="true" >}} It is special type of column that allows you to add employee name with avatar column to your Grid. You can see how it looks be default: @@ -13,6 +14,10 @@ You can see how it looks be default: ## Available options +| Properties | Type | Expected value | +| ---------- | ------ | ------------------------------------ | +| **field** | string | **required** Employee's name field. | + ### field **type:** `string` **required** @@ -25,13 +30,12 @@ Employee's name field. use PrestaShop\PrestaShop\Core\Grid\Column\Type\Employee\EmployeeNameWithAvatarColumn; use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; -$column = new EmployeeNameWithAvatarColumn('severity'); -$column->setName('Severity (1-4)'); -$column->setOptions([ - 'field' => 'severity', - 'with_message' => true, // enable severity messages +$employeeColumn = new EmployeeNameWithAvatarColumn('employee'); +$employeeColumn->setName('Employee'); +$employeeColumn->setOptions([ + 'field' => 'employee', ]); $columns = new ColumnCollection(); -$columns->add($column); +$columns->add($employeeColumn); ``` diff --git a/src/content/1.7/development/components/grid/columns-reference/image.md b/src/content/1.7/development/components/grid/columns-reference/image.md new file mode 100644 index 0000000000..f02cddfcfb --- /dev/null +++ b/src/content/1.7/development/components/grid/columns-reference/image.md @@ -0,0 +1,32 @@ +--- +title: ImageColumn reference +menuTitle: ImageColumn +weight: 10 +--- + +# ImageColumn Type +{{< minver v="1.7.6" title="true" >}} + +This column is used to display an image from a row. You need to specify which field of the row contains the image source. + +## Available options + +| Properties | Type | Expected value | +| ------------- | ------ | ----------------------------------------------------------------------- | +| **src_field** | string | **required** Indicates which field of the row contains the image source | + +## Example usage + +```php +use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\ImageColumn; +use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; + +$imageColumn = new ImageColumn('flag'); +$imageColumn->setName('Flag'); +$imageColumn->setOptions([ + 'src_field' => 'flag', +]); + +$columns = new ColumnCollection(); +$columns->add($imageColumn); +``` \ No newline at end of file diff --git a/src/content/1.7/development/components/grid/columns-reference/link.md b/src/content/1.7/development/components/grid/columns-reference/link.md new file mode 100644 index 0000000000..1838d47f92 --- /dev/null +++ b/src/content/1.7/development/components/grid/columns-reference/link.md @@ -0,0 +1,38 @@ +--- +title: LinkColumn reference +menuTitle: LinkColumn +weight: 10 +--- + +# LinkColumn Type +{{< minver v="1.7.6" title="true" >}} + +This LinkColumn displays a raw field data encapsulated in a link (very useful to add an edition link on a name for example). + +## Available options + +| Properties | Type | Expected value | +| -------------- | ------ | ---------------------------------------------------------------------------------- | +| **field** | string | **required** Record field name which column displays. | +| **route** | string | **required** Route used to generated link url. | +| **route_param_name** | string | **required** Parameter name used by the route to generate the url. | +| **route_param_field** | string | **required** Record field containing the route parameter. | + +## Example usage + +```php +use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\LinkColumn; +use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; + +$linkColumn = new LinkColumn('total_spent'); +$linkColumn->setName('Sales'); +$linkColumn->setOptions([ + 'field' => 'name', + 'route' => 'admin_category_edit', + 'route_param_name' => 'categoryId', + 'route_param_field' => 'id_category', +]); + +$columns = new ColumnCollection(); +$columns->add($linkColumn); +``` \ No newline at end of file diff --git a/src/content/1.7/development/components/grid/columns-reference/position.md b/src/content/1.7/development/components/grid/columns-reference/position.md new file mode 100644 index 0000000000..c79f02ab8f --- /dev/null +++ b/src/content/1.7/development/components/grid/columns-reference/position.md @@ -0,0 +1,62 @@ +--- +title: PositionColumn reference +menuTitle: PositionColumn +weight: 20 +--- + +# PositionColumn Type +{{< minver v="1.7.5" title="true" >}} + +This type of columns allows you to define rows position using a drag and drop feature. Besides this column definition +you need to use our javascript `PositionExtension` and prepare a route to manage the positions update. To help you create +this controller you can use our [PositionUpdater][position-updater-reference] component. + +## Available options + +| Properties | Type | Expected value | +| ------------ | ------ | ------------------------------------------------------------------------------------------ | +| **id_field** | string | **required** Record field containing its id. | +| **position_field** | string | **required** Record field containing its position. | +| **update_route** | string | **required** Route called to update records position. | +| **update_method** | string | **default:** `GET` Method used to call the update route. | +| **record_route_params** | array | **default:** `[]` Associative array to inject record fields in the update route. | + +## Example usage + +```php +use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\PositionColumn; +use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; + +$positionColumn = new PositionColumn('position'); +$positionColumn->setName('Position'); +$positionColumn->setOptions([ + 'id_field' => 'id_link_block', + 'position_field' => 'position', + 'update_route' => 'admin_link_block_update_positions', + 'update_method' => 'POST', + 'record_route_params' => [ + 'id_hook' => 'hookId', + ], +]); + +$columns = new ColumnCollection(); +$columns->add($positionColumn); +``` + +```js +import Grid from '../../components/grid/grid'; +import PositionExtension from "../../components/grid/extension/position-extension"; + +const $ = window.$; + +$(() => { + let gridDivs = document.querySelectorAll('.js-grid'); + gridDivs.forEach((gridDiv) => { + const grid = new Grid(gridDiv.dataset.gridId); + grid.addExtension(new PositionExtension()); + }); +}); +``` + +[actions-reference]: {{< ref "/1.7/development/components/grid/actions-reference/_index.md" >}} +[position-updater-reference]: {{< ref "/1.7/development/components/position-updater/_index.md" >}} diff --git a/src/content/1.7/development/components/grid/columns-reference/severity-level.md b/src/content/1.7/development/components/grid/columns-reference/severity-level.md index f391ae6d4f..f671035d62 100644 --- a/src/content/1.7/development/components/grid/columns-reference/severity-level.md +++ b/src/content/1.7/development/components/grid/columns-reference/severity-level.md @@ -1,26 +1,20 @@ --- title: SeverityLevelColumn reference menuTitle: SeverityLevelColumn -weight: 60 +weight: 70 --- # SeverityLevelColumn Type +{{< minver v="1.7.5" title="true" >}} Use this column to display severity level in your Grid. ## Available options -### field - -**type:** `string` **required** - -Record field name which is used as severity level. - -### with_message - -**type:** `bool` **default:** `false` - -Whether to show severity level message in addition with numeric severity level value. +| Properties | Type | Expected value | +| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------- | +| **field** | string | **required** Record field name which is used as severity level. | +| **with_message** | bool | **default:** `false` Whether to show severity level message in addition with numeric severity level value. | ## Example usage @@ -28,13 +22,13 @@ Whether to show severity level message in addition with numeric severity level v use PrestaShop\PrestaShop\Core\Grid\Column\Type\Status\SeverityLevelColumn; use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; -$column = new SeverityLevelColumn('severity'); -$column->setName('Severity (1-4)'); -$column->setOptions([ +$severityColumn = new SeverityLevelColumn('severity'); +$severityColumn->setName('Severity (1-4)'); +$severityColumn->setOptions([ 'field' => 'severity', 'with_message' => true, // enable severity messages ]); $columns = new ColumnCollection(); -$columns->add($column); +$columns->add($severityColumn); ``` \ No newline at end of file diff --git a/src/content/1.7/development/components/grid/columns-reference/toggle.md b/src/content/1.7/development/components/grid/columns-reference/toggle.md new file mode 100644 index 0000000000..30180756d6 --- /dev/null +++ b/src/content/1.7/development/components/grid/columns-reference/toggle.md @@ -0,0 +1,38 @@ +--- +title: ToggleColumn reference +menuTitle: ToggleColumn +weight: 10 +--- + +# ToggleColumn Type +{{< minver v="1.7.5" title="true" >}} + +This ToggleColumn is used to display booleans, it will display an icon instead of the value. If user clicks on it, this triggers a toggle of the boolean value. + +## Available options + +| Properties | Type | Expected value | +| -------------- | ------ | ---------------------------------------------------------------------------------- | +| **field** | string | **required** Record field name which column displays. | +| **primary_field** | string | **required** Record field name which column displays. | +| **route** | string | **required** Route used to generated link url. | +| **route_param_name** | string | **required** Parameter name used by the route to generate the url. | + +## Example usage + +```php +use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\ToggleColumn; +use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; + +$toggleColumn = new ToggleColumn('active'); +$toggleColumn->setName('Enabled'); +$toggleColumn->setOptions([ + 'field' => 'active', + 'primary_field' => 'id_customer', + 'route' => 'admin_customers_toggle_status', + 'route_param_name' => 'customerId', +]); + +$columns = new ColumnCollection(); +$columns->add($toggleColumn); +``` \ No newline at end of file diff --git a/src/content/1.7/development/components/grid/tutorials/_index.md b/src/content/1.7/development/components/grid/tutorials/_index.md index d3d2c90813..bc8b07f3b4 100644 --- a/src/content/1.7/development/components/grid/tutorials/_index.md +++ b/src/content/1.7/development/components/grid/tutorials/_index.md @@ -1,4 +1,4 @@ --- title: Tutorials -weight: 9 +weight: 15 --- \ No newline at end of file diff --git a/src/content/1.7/development/components/position-updater/_index.md b/src/content/1.7/development/components/position-updater/_index.md new file mode 100644 index 0000000000..db6ad731cf --- /dev/null +++ b/src/content/1.7/development/components/position-updater/_index.md @@ -0,0 +1,236 @@ +--- +title: The Position Updater component +menuTitle: Position Updater +weight: 2 +--- + +# The Position updater component +{{< minver v="1.7.5" title="true" >}} + +## Introduction + +Order elements position is a common use case in any CMS or a shop back-office. You may need to order, categories, products, modules or adds. +The use cases are endless. Which is why we developed a generic component to help you manage your position updates quickly and efficiently. +Combined with our Grid component this will help you build entity lists more easily. This component will be divided into ... components: + +* `PositionDefinition`: it defined the basic information to compute and update the position( table, id field, position field, ...) +* `PositionUpdate`: this object contains all the atomic modifications that needs to be done on your list (symbolized by `PositionModification` objects) +* `PositionUpdateFactory`: this service allows you to build a `PositionUpdate` easily base on your `PositionDefinition` and basic modification data +* `GridPositionUpdater`: it is the main part of the component which gives you interfaces to perform position modifications + +## PositionDefinition + +The first thing, and nearly only thing, you need to create is you `PositionDefinition` which will hold the basic structure to manage the positions in your list. +To allow our component to automatically compute position updates we need a few data: + +* **table**: which table is being ordered and contains the position (`ps_category`, `ps_product`, ...) +* **idField**: what is the name of the field containing the id of this table (`id_category`, `id_product`) +* **positionField**: what is the name of the field containing the position in this table (`position`, `pos`, `rank`, ...) +* **parentIdField** (optional): in some cases the position depends on a parent context and your table will contains different positions based on a different parent (`id_category`, `id_parent`, ...) + +### Manual definition + +You can define this `PositionDefinition` manually: + +```php +use PrestaShop\PrestaShop\Core\Grid\Position\PositionDefinition; + +$positionDefinition = new PositionDefinition( + 'product', + 'id_product', + 'position', + 'id_category_default' +); +``` + +### Service definition + +Or you can define a service to avoid duplicating your code: + +```yaml +services: + _defaults: + public: true + + prestashop.product.grid.position_definition: + class: 'PrestaShop\PrestaShop\Core\Grid\Position\PositionDefinition' + arguments: + - 'product' + - 'id_product' + - 'position' + - 'id_category_default' +``` + +## Building your PositionUpdate + +The good news is that you now made the hardest part, all other computing and request will now be managed by our component. +The only thing you have to do now is provide the updates you want to apply to your list positions. We provide a default `PositionUpdateFactory` +to help you build your update, it is defined as a Symfony service accessible via `prestashop.core.grid.position.position_update_factory`. + +```php +use PrestaShop\PrestaShop\Core\Grid\Position\PositionUpdateFactory; +use PrestaShop\PrestaShop\Core\Grid\Position\PositionDefinition; +use PrestaShop\PrestaShop\Core\Grid\Position\PositionUpdate; +use PrestaShop\PrestaShop\Core\Grid\Position\Exception\PositionDataException; + +$positionsData = [ + 'positions' => [ + [ + 'rowId' => 12, + 'oldPosition' => 0, + 'newPosition' => 1, + ], + [ + 'rowId' => 15, + 'oldPosition' => 5, + 'newPosition' => 3, + ] + ], + 'parentId' => $categoryId, +]; + +/** @var PositionDefinition $positionDefinition */ +$positionDefinition = $this->get('prestashop.product.grid.position_definition'); + +/** @var PositionUpdateFactory $positionUpdateFactory */ +$positionUpdateFactory = $this->get('prestashop.core.grid.position.position_update_factory'); + +try { + /** @var PositionUpdate $positionUpdate */ + $positionUpdate = $positionUpdateFactory->buildPositionUpdate($positionsData, $positionDefinition); +} catch (PositionDataException $e) { + //An exception is thrown if the input data doesn't respect the expected format + $errors = [$e->toArray()]; + $this->flashErrors($errors); +} +``` + +{{% notice note %}} +The format of the input data is not random nor fixed, it actually matches the definition of our `PositionUpdateFactory` which you can see in the service definition: + +```yaml + # In src/PrestaShopBundle/Resources/config/services/core/grid.yml + ... + # Grid position updater + prestashop.core.grid.position.position_update_factory: + class: 'PrestaShop\PrestaShop\Core\Grid\Position\PositionUpdateFactory' + arguments: + - 'positions' + - 'rowId' + - 'oldPosition' + - 'newPosition' + - 'parentId' +``` +If you need this component to match another input format you can instanciate your own factory with the appropriate settings. +{{% /notice %}} + + +## Update your positions + +Now that you built your `PositionUpdate` object all you need to do is perform the modification, to do this you can use +the `GridPositionUpdater` service which id is `PrestaShop\PrestaShop\Core\Grid\Position\GridPositionUpdater` + +```php +use PrestaShop\PrestaShop\Core\Grid\Position\PositionUpdate; +use PrestaShop\PrestaShop\Core\Grid\Position\GridPositionUpdaterInterface; +use PrestaShop\PrestaShop\Core\Grid\Position\Exception\PositionUpdateException; + +/** @var PositionUpdate $positionUpdate */ +$positionUpdate = buildPositionUpdate(); + +/** @var GridPositionUpdaterInterface $updater */ +$updater = $this->get('prestashop.core.grid.position.doctrine_grid_position_updater'); +try { + $updater->update($positionUpdate); + $this->clearModuleCache(); + $this->addFlash('success', $this->trans('Successful update.', 'Admin.Notifications.Success')); +} catch (PositionUpdateException $e) { + $errors = [$e->toArray()]; + $this->flashErrors($errors); +} +``` + +## Example + +This is a example to sum up what you just learnt, here is a simple controller used in a grid in the [ps_linklist](https://github.com/PrestaShop/ps_linklist) module. + +```yaml +# Route definition for the controller +admin_link_block_update_positions: + path: /link-widget/update-positions/{hookId} + methods: [POST] + defaults: + _controller: 'PrestaShop\Module\LinkList\Controller\Admin\Improve\Design\LinkBlockController::updatePositionsAction' + _legacy_controller: AdminLinkWidget + requirements: + hookId: \d+ +``` + +```php +namespace PrestaShop\Module\LinkList\Controller\Admin\Improve\Design; + +use PrestaShop\PrestaShop\Core\Grid\Position\Exception\PositionDataException; +use PrestaShop\PrestaShop\Core\Grid\Position\Exception\PositionUpdateException; +use PrestaShop\PrestaShop\Core\Grid\Position\GridPositionUpdaterInterface; +use PrestaShop\PrestaShop\Core\Grid\Position\PositionUpdateFactory; +use PrestaShop\PrestaShop\Core\Grid\Position\PositionDefinition; +use PrestaShop\PrestaShop\Core\Grid\Position\PositionUpdate; +use PrestaShopBundle\Controller\Admin\FrameworkBundleAdminController; +use PrestaShopBundle\Security\Annotation\AdminSecurity; +use PrestaShopBundle\Security\Annotation\ModuleActivated; +use Symfony\Component\HttpFoundation\RedirectResponse; +use Symfony\Component\HttpFoundation\Request; +use Symfony\Component\HttpFoundation\Response; + +/** + * Class LinkBlockController. + * + * @ModuleActivated(moduleName="ps_linklist", redirectRoute="admin_module_manage") + */ +class LinkBlockController extends FrameworkBundleAdminController { + /** + * @AdminSecurity("is_granted('update', request.get('_legacy_controller'))", message="Access denied.") + * + * @param Request $request + * @param int $hookId + * + * @throws \Exception + * + * @return RedirectResponse + */ + public function updatePositionsAction(Request $request, $hookId) + { + $positionsData = [ + 'positions' => $request->request->get('positions', null), + 'parentId' => $hookId, + ]; + + /** @var PositionDefinition $positionDefinition */ + $positionDefinition = $this->get('prestashop.module.link_block.grid.position_definition'); + /** @var PositionUpdateFactory $positionUpdateFactory */ + $positionUpdateFactory = $this->get('prestashop.core.grid.position.position_update_factory'); + try { + /** @var PositionUpdate $positionUpdate */ + $positionUpdate = $positionUpdateFactory->buildPositionUpdate($positionsData, $positionDefinition); + } catch (PositionDataException $e) { + $errors = [$e->toArray()]; + $this->flashErrors($errors); + + return $this->redirectToRoute('admin_link_block_list'); + } + + /** @var GridPositionUpdaterInterface $updater */ + $updater = $this->get('prestashop.core.grid.position.doctrine_grid_position_updater'); + try { + $updater->update($positionUpdate); + $this->clearModuleCache(); + $this->addFlash('success', $this->trans('Successful update.', 'Admin.Notifications.Success')); + } catch (PositionUpdateException $e) { + $errors = [$e->toArray()]; + $this->flashErrors($errors); + } + + return $this->redirectToRoute('admin_link_block_list'); + } +} +``` \ No newline at end of file