NXDOC-2411: how to configure bulk edit

src/nxdoc/web-ui/web-ui-tutorials/how-to-create-bulk-edit-form-studio.md

@@ -0,0 +1,89 @@
+---
+title: 'HOWTO: Create a Bulk Edit Form Using Nuxeo Studio'
+review:
+    comment: ''
+    date: '2021-12-21'
+    status: ok
+toc: true
+details:
+    howto:
+        excerpt: Learn how to create a bulk edit form using Nuxeo Studio Designer
+        level: Intermediate
+        tool: null
+        topics: 'Web UI, Studio Designer, UIElements, Bulk'
+labels:
+    - tutorial
+tree_item_index: 497
+---
+
+{{! excerpt}}
+In this tutorial you will learn how to create a form to edit metadata on a large set of documents.
+{{! /excerpt}}
+
+## Requirements
+
+{{#> callout type='info'}}
+This capability is available since LTS 2021 with Web UI 3.0.9.
+{{/callout}}
+
+- A [Contract document type]({{page version='' space='nxdoc' page='web-ui-document-layouts'}}#create-a-contract-document-type) created in Nuxeo Modeler.
+- The Nuxeo [Web UI addon](https://connect.nuxeo.com/nuxeo/site/marketplace/package/nuxeo-web-ui) installed on your instance.
+- In Studio Modeler > **Settings** > **Application Definition**, make sure that **Nuxeo Web UI** is in the **Packages to Install** list.
+- Activate the `Select All and Bulk Actions` feature by adding the `nuxeo.selection.selectAllEnabled=true` property in your [nuxeo.conf]({{page page="configuration-parameters-index-nuxeoconf"}}) file.
+
+## Create the Structure
+
+- In Studio Designer, click on the **RESOURCES** tab.
+- Select the `UI` folder and click on the `create` button at the bottom of the screen.
+- Create a new folder and name it `bulk`.
+
+## Create a Bulk Edit Layout
+
+To make things faster, we will reuse the same form as the one used for the edit layout of the Contract document type.
+
+- From the **RESOURCES** tab, open the **document** > **contract** folder and open the `nuxeo-contract-edit-layout.html` file.
+- Copy the content of the layout (Ctrl/Cmd + A then Ctrl/Cmd + C).
+- Select the `bulk` folder you created previously and click on the `create` button at the bottom of the screen.
+- Create a new `empty file` and name it `nuxeo-bulk-edit-contracts-layout`.
+- Inside, paste the content of the contract edit layout.
+- In your bulk edit layout, replace the name of the layout you copied (`nuxeo-contract-edit-layout`) with the current one (`nuxeo-bulk-edit-contracts-layout`).
+- Save your configuration.
+
+{{#> callout type='info'}}
+Your bulk edit layouts need to be placed in the dedicated `bulk` folder, and follow a naming convention introduced to prevent collision. Make sure they are always named `nuxeo-bulk-[your-layout-name]-layout`.
+{{/callout}}
+
+## Bind the Bulk Edit Layout to a Button
+
+Now that your layout is ready, you will need to bind it to a button.
+
+- From the **RESOURCES** tab, open the `nuxeo-[studio-project-id]-custom-bundle.html` file.
+
+{{#> callout type='info'}}
+If the file doesn't exist yet, open the `nuxeo-[studio-project-id]-bundle.html` file first and you will be prompted for the custom bundle file to be generated.
+{{/callout}}
+
+- Inside the file, add the following contribution to bind your layout to a button:
+
+```
+<!-- Contribution for bulk editing contracts in every context (no filtering) -->
+<nuxeo-slot-content name="bulkEditContractsButton" slot="RESULTS_SELECTION_ACTIONS" order="1">
+  <template>
+    <nuxeo-edit-documents-button icon="nuxeo:edit" label="Bulk Edit Contracts" documents="[[selection]]" layout="edit-contracts"></nuxeo-edit-documents-button>
+  </template>
+</nuxeo-slot-content>
+```
+
+{{#> callout type='tip'}}
+In this example, we are displaying our button in every situation. Feel free to [add filters to this contribution]({{page space='studio' page='javascript-expression-examples'}}) to refine when the button should be displayed.
+{{/callout}}
+
+- Save your configuration. Your bulk edit form is ready to be used.
+
+{{#> callout type='info'}}
+You only need to mention the unique part of the layout name in the `layout` property of the `nuxeo-edit-documents-button` element. It applies the naming convention automatically.
+{{/callout}}
+
+## Testing the Result
+
+From any [Folderish]({{page page="available-facets"}}#folderish) document (e.g. a `Folder`, a `Workspace`) or in the results of a search, select one or several documents you want to validate. Click on your brand new button in the toolbar on top of the screen to open your bulk edit form. Select the properties to replace and the value to set, and click save to launch the action.

src/nxdoc/web-ui/web-ui-tutorials/web-ui-bulk-actions.md

@@ -2,7 +2,7 @@
 title: 'Bulk Actions in Web UI'
 review:
     comment: ''
-    date: '2021-09-07'
+    date: '2021-12-21'
     status: ok
 toc: true
 labels:
@@ -22,6 +22,8 @@ Bulk actions were introduced to LTS 2021 with Web UI 3.0.6. To prevent bringing
 nuxeo.selection.selectAllEnabled=true
 ```
 
+Bulk edit was introduced to LTS 2021 with Web UI 3.0.9. No additional property is needed to enable it, as it relies on configuration done through Studio. See [how to create a bulk edit form]({{page page='how-to-create-bulk-edit-form-studio'}}) for additional information.
+
 ## Using Bulk Actions
 
 Once enabled, users can select all documents in a result listing and execute an action on them. A selection can be done while browsing content and in the context of search results. It is possible to select all documents after using filters as well to fine-tune the results first. Note that adding filters, changing the display or the sort order for the results causes the current selection to be lost: this results in sending a different query to the server and we cannot keep track of the difference between the two without hurting performance.
@@ -60,6 +62,10 @@ The following default actions are **NOT** available as bulk actions:
 - Add to clipboard. This action is handled on the client side and does not make use of the [bulk action framework]({{page page='bulk-action-framework'}}). If you want to integrate an action that allows you to do this at scale, you can take inspiration from our [copy / move cookbook](https://github.com/nuxeo/nuxeo-studio-community-cookbook/tree/master/modules/nuxeo/copy-move) entry and adapt it, knowing that you can [create your custom bulk actions using Nuxeo Studio]({{page page='how-to-create-bulk-actions-studio'}}).
 - Move Document Up and Down (in the context of ordered folders). This would only cause useless processing since moving all documents up or down would yield the same result.
 
+You can create additional bulk actions using Nuxeo Studio as well:
+- [Creating Bulk Actions Using Nuxeo Studio]({{page page='how-to-create-bulk-actions-studio'}})
+- [Creating Bulk Edit Forms Using Nuxeo Studio]({{page page='how-to-create-bulk-edit-form-studio'}})
+
 ### Bulk Actions Notifications Management
 
 When launching a bulk action, a notification is updated regularly in Web UI, providing its current state and allowing the user to abort it.
@@ -95,4 +101,24 @@ To avoid cluttering the UI when executing many bulk actions in parallel, three (
 
 ## Configuring a Custom Bulk Action
 
-Custom bulk actions can be configured using Nuxeo Studio. For more information, please refer to our tutorial: [create your custom bulk actions using Nuxeo Studio]({{page page='how-to-create-bulk-actions-studio'}}).
+Custom bulk actions and bulk edit forms can be configured using Nuxeo Studio. For more information, please refer to our tutorials:
+- [create your custom bulk actions using Nuxeo Studio]({{page page='how-to-create-bulk-actions-studio'}}).
+- [create your custom bulk edit forms using Nuxeo Studio]({{page page='how-to-create-bulk-edit-form-studio'}}).
+
+## Questions and Answers
+
+### In Which Context Can Users Trigger Bulk Actions ?
+
+They can be launched from any results listing, e.g. when browsing a document or when doing a search.
+
+### Can I Have Multiple Bulk Edit Forms / Multiple Bulk Actions ?
+
+You can configure as many bulk actions and bulk edit forms as you desire.
+
+### On How Many Documents Can I Launch a Bulk Action?
+
+Bulk actions were tested on sets of 150 000 documents; however there is no limit implemented in the software currently. We recommend being thoughtful when designing your bulk actions (how many documents can be impacted, how many of them could run in parallel) and considering your architecture needs.
+
+### How do I Deal With Errors?
+
+When an error happens, the user receives a notification once the action completes. It is possible for them to copy the error message and the bulk command id in order to contact an administrator. An administrator can have a detailed look at the situation by looking at the information related to this bulk command id.