Merge pull request #1040 from akeneo/DXIM-rework_ui_ext_doc

DXIM rework ui ext page

Author: JulienVerbrugge

content/extensions/ui-extensions.md

@@ -174,106 +174,77 @@ To delete a UI extension, you must have a valid PIM API token and the UUID of th
 --header "Authorization: Bearer $PIM_API_TOKEN"
 ```
 
-## Concepts
-
-### Type
+## Types
 
 UI extensions are categorized by type, which determines their capabilities. Select the type that best suits your requirements:
 + action
 + iframe
 + link
 
-#### Link
+### Link
 A **link** UI extension is crafted to open your external content in a new tab.
 
-#### Iframe
-An **iframe** UI extension allows to open your external content inside the PIM thanks to an iframe.
+To create a `link` UI extension, mandatory fields are `name`, `position`, `type`, and `configuration`. Inside `configuration`, mandatory options are `default_label` and `url`.
 
-An iframe (inline frame) is an HTML element that allows you to embed another HTML document within the current document. It is commonly used to display content from another source, such as a webpage, video, or interactive content, without leaving the current page.
+#### Url Placeholders
+The Url of a **link** UI extension can be based on the context thanks to a placeholder pattern.
 
-For more detailed information, you can refer to the [Mozilla Developer Network (MDN) documentation on iframes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).
+For example, you can configure a UI extension with the following url `https://www.google.com/search?q=%name%&tbm=shop&gl=us`. When the link is clicked, `%name%` will be replaced with the context attribute values.
 
-To configure an `iframe` UI extension, mandatory fields are `name`, `position`, `type`, and `configuration`. Inside `configuration`, mandatory options are `default_label`, `secret` and `url`.
+Valid placeholders attributes are:
+- `uuid` (for products), `code` (for product models) and other attribute of type `identifier`
+- all `text` attributes. Links will use the value related to the current locale or channel.
 
-**Ensuring security of embedded iframes**
+You can add a placeholder anywhere in your url as soon as they're surrounded by `%` symbol.
 
-* Properly configure [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers to control the sources from which content can be loaded.
+Examples:
+- `https://www.google.com/search?q=%name%`
+- `https://yourwebsite.com/%sku%`
+- `%base_url%/sub-url`
 
 ::: warning
- Please note that if these headers are misconfigured, iframe functionality may not work as intended.
+If the URL begins with a placeholder, we won't verify its validity. The link might not work when used.
 :::
 
-* Add a secret to your extension. This secret will be used to generate a JWT token when the iframe is loaded by the PIM system.
-
-**Receiving the JWT Token via ```postMessage```**
-
-First, from your iframe, you must request for the JWT by doing a PostMessage with a payload containing ```type: 'request_jwt'```
-
-Example :
-```js
-    window.parent.postMessage(
-      {
-        type: 'request_jwt'
-      },
-      "*"
-    );
-```
-
- the PIM will then answer with a postMessage containing the JWT token. The message will be structured as follows:
-
-```json
-{
-  "type": "JWT_TOKEN",
-  "token": "jwt_value"
-}
-```
-
-* The JWT token in the token field is generated using SHA256 encryption based on the secret you provided.
-
-For more information on how JWT tokens are structured and used, you can refer to the associated [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519).
-
-**JWT Token Structure**
-
-The JWT token consists of three main parts: the header, the body (payload), and the signature.
+### Iframe
+An **iframe** UI extension allows to open your external content inside the PIM thanks to an iframe.
 
-*Header*
+An iframe (inline frame) is an HTML element that allows you to embed another HTML document within the current document. It is commonly used to display content from another source, such as a webpage, video, or interactive content, without leaving the current page.
 
-* The header typically contains information about the token type and the signing algorithm. In this case, it will look like:
+For more detailed information, you can refer to the [Mozilla Developer Network (MDN) documentation on iframes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).
 
-```json
-{
-  "typ": "JWT",
-  "alg": "HS256"
-}
-```
+To configure an `iframe` UI extension, mandatory fields are `name`, `position`, `type`, and `configuration`. Inside `configuration`, mandatory options are `default_label`, `secret` and `url`.
 
-*Payload*
+::: warning
+**Important security notice**
 
-* The payload contains the claims. The JWT token’s will look like this:
+For sensitive data, we recommend implementing [security measures](#ensuring-security-of-embedded-iframes) to protect your information.
+:::
 
-```json
-{
-  "jti": "c1b6b9f1-8486-4f9e-9f96-8d1b40fccb65",
-  "iat": 1743410036.116152,
-  "exp": 1743413636.116162,
-  "userId": "1"
-}
-```
+#### Default query parameters
+To help identify the  **iframe** caller (insecure) and context, several parameters are sent by default as SearchParameters in the GET query.
 
-* ```jti``` The unique identifier for the token.
-* ```iat``` The issued at time.
-* ```exp``` The expiration time of the token.
-* ```userId``` The PIM user identifier (in this case, ```1```).
+For example, when `url` is `https://customerwebsite.com/iframe/`, the called URL is `https://customerwebite.com/iframe/?position=pim.product.tab&user[username]=julia`
 
-*A signature*
+For all positions, parameters relative to the connected user and the extension position are sent:
+- `user[username]`
+- `user[email]`
+- `user[ui_locale]`
+- `user[catalog_locale]` except for `pim.product-grid.action-bar`
+- `user[catalog_scope]` except for `pim.product-grid.action-bar`
+- `position`
 
-* The signature is used to verify that the token is valid and has not been tampered with. It is generated by combining the encoded header and payload, and then signing them with the secret key. The resulting signature might look like:  
-```9WBB7ayP8UnFrOlMrI9NzTj3kxaiXOWJzElyacEKt48```
+For `pim.product.tab` position, these parameters are sent:
+- `product[uuid]`
+- `product[identifier]`
 
-**Verifying the Signature**
+For `pim.product-model.tab` and `pim.sub-product-model.header` position, this parameter is sent:
+- `product[code]`
 
-To ensure that the JWT token was issued by Akeneo, you can verify the signature by re-encoding the header and payload and then signing them using the same secret key. This will allow you to confirm that the token is valid and has not been altered.
+For `pim.category.tab` position, this parameter is sent:
+- `category[code]`
 
+#### Get PIM data from the iframe
 
 **PostMessage**
 
@@ -337,8 +308,88 @@ Example :
 ```
 After receiving this *event*, the PIM will send a PostMessage *event*, similar to the one sent after the iframe loading.
 
+#### Ensuring security of embedded iframes
+
+To help ensuring the security of iframes we recommand using these two solutions:
+
+* Properly configure [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers to control the sources from which content can be loaded.
 
-#### Action
+::: warning
+ Please note that if these headers are misconfigured, iframe functionality may not work as intended.
+:::
+
+* Use your extension secret and ```postMessage``` to get and verify the signature of a JW token. This secret will be used to generate a JWT token when the iframe is loaded by the PIM system.
+
+**Get a JW Token via ```postMessage```**
+
+First, from your iframe, you must request for the JWT by doing a PostMessage with a payload containing ```type: 'request_jwt'```
+
+Example :
+```js
+    window.parent.postMessage(
+      {
+        type: 'request_jwt'
+      },
+      "*"
+    );
+```
+
+ the PIM will then answer with a postMessage containing the JWT token. The message will be structured as follows:
+
+```json
+{
+  "type": "JWT_TOKEN",
+  "token": "jwt_value"
+}
+```
+
+* The JWT token in the token field is generated using SHA256 encryption based on the secret you provided.
+
+For more information on how JWT tokens are structured and used, you can refer to the associated [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519).
+
+**JWT Token Structure**
+
+The JWT token consists of three main parts: the header, the body (payload), and the signature.
+
+*Header*
+
+* The header typically contains information about the token type and the signing algorithm. In this case, it will look like:
+
+```json
+{
+  "typ": "JWT",
+  "alg": "HS256"
+}
+```
+
+*Payload*
+
+* The payload contains the claims. The JWT token’s will look like this:
+
+```json
+{
+  "jti": "c1b6b9f1-8486-4f9e-9f96-8d1b40fccb65",
+  "iat": 1743410036.116152,
+  "exp": 1743413636.116162,
+  "userId": "1"
+}
+```
+
+* ```jti``` The unique identifier for the token.
+* ```iat``` The issued at time.
+* ```exp``` The expiration time of the token.
+* ```userId``` The PIM user identifier (in this case, ```1```).
+
+*A signature*
+
+* The signature is used to verify that the token is valid and has not been tampered with. It is generated by combining the encoded header and payload, and then signing them with the secret key. The resulting signature might look like:  
+```9WBB7ayP8UnFrOlMrI9NzTj3kxaiXOWJzElyacEKt48```
+
+**Verifying the Signature**
+
+To ensure that the JWT token was issued by Akeneo, you can verify the signature by re-encoding the header and payload and then signing them using the same secret key. This will allow you to confirm that the token is valid and has not been altered.
+
+### Action
 An **action** UI extension is designed to perform external tasks in the background. Please note the following key points regarding its functionality:
 
 + **Single execution**: An action cannot be executed multiple times simultaneously. This ensures that tasks are processed in a controlled manner.
@@ -351,7 +402,6 @@ An **action** UI extension is designed to perform external tasks in the backgrou
 Here is a diagram illustrating the workflow:
 [![action-extension-schema.png](../img/extensions/ui-extensions/action-extension-schema.png)](../img/extensions/ui-extensions/action-extension-schema.png)
 
-
 Data sent within the POST body, formatted in JSON, contains :
 - A `data` object with different fields depending on the [position](#position).
 - A `context` object containing the configured `locale` and `channel`.
@@ -416,9 +466,9 @@ Examples :
 }
 ```
 
-### Position
+## Positions
 
-**Extension Position**
+**Extension Positions**
 
 Extension position determines where your extension appears within the Akeneo PIM interface. You can select from a variety of available positions, which vary depending on the specific extension type.
 
@@ -434,10 +484,9 @@ Extension position determines where your extension appears within the Akeneo PIM
 * Consider the impact of the position on the overall user experience within the PIM.
 
 
-#### The following position can be added: 
+### Positions list 
 
 ![PIM Header.png](../img/extensions/ui-extensions/pim-header-with-extension.png)
-
 #### pim.product.header
 This position refers to the header of a simple product or a variant edit page.
 
@@ -448,7 +497,6 @@ This position refers to the header of a root model edit page.
 This position refers to the header of a sub model edit page.
 
 ![PIM Tab.png](../img/extensions/ui-extensions/pim-product-with-tab-extension.png)
-
 #### pim.product.tab
 This position refers to the left panel of a simple product or a variant edit page.
 
@@ -462,7 +510,6 @@ This position refers to the left panel of a sub model edit page.
 This position refers to the horizontal list of tabs on a category edit page.
 
 ![PIM Product Grid.png](../img/extensions/ui-extensions/pim-product-grid-with-bulk-trigger-action.png)
-
 #### pim.product-grid.action-bar
 This position refers to the list of commands availables after selecting some products on the product grid.
 
@@ -473,64 +520,7 @@ This position refers to the list of commands availables after selecting some pro
 #### pim.activity.navigation.tab
 This position refers to the activity PIM menu, adding UI extensions in this position will create a new section in the activity sub-navigation.
 
-### Url
-All types of UI extensions must have a configured URL. However, the parameters that are sent—or can be sent—vary depending on the specific type of extension.
-#### Query parameters placeholders
-For [link](#link) UI extension, you can ask for specific values to construct the urls thanks to a specific placeholder pattern. 
-
-For example, you can configure a UI extension with the following url `https://www.google.com/search?q=%name%&tbm=shop&gl=us`, then we will dynamically put the value of the attribute code `name` when the user will click on the button.
-
-Valid placeholders attributes are:
-- `uuid` (for products), `code` (for product models) and other attribute of type `identifier`
-- all text attributes. Links will use the value related to the current locale or channel.
-
-You can add a placeholder anywhere in your url as soon as they're surrounded by `%` symbol.
-
-Examples:
-- `https://www.google.com/search?q=%name%`
-- `https://yourwebsite.com/%sku%`
-- `%base_url%/sub-url`
-
-::: warning
-If the URL begins with a placeholder, we won't verify its validity. The link might not work when used.
-:::
-
-#### Default query parameters
-For an [iframe](#iframe) UI extension, several parameters are sent by default as SearchParameters in a GET query, so the server knows who is the connected user (insecure) and in which context the iframe is opened.
-
-For example, when `url` is `https://customerwebsite.com/iframe/`, the called URL is `https://customerwebite.com/iframe/?paramA=valueA&paramB=valueB`
-
-For all positions, parameters relative to the connected user and the extension position are sent:
-- `user[username]`
-- `user[email]`
-- `user[ui_locale]`
-- `user[catalog_locale]` except for `pim.product-grid.action-bar`
-- `user[catalog_scope]` except for `pim.product-grid.action-bar`
-- `position`
-
-::: warning
-**Important security notice**
-
-When using iframes, please be aware of the following:
-
-+ **Data confidentiality**: We do not implement any security measures to verify the identity of the caller accessing the URL.
-
-+ **Access control**: Anyone with access to this link can view the content of the webpage, regardless of the parameters included.
-
-For sensitive data, we recommend implementing additional security measures to protect your information.
-:::
-
-For `pim.product.tab` position, these parameters are sent:
-- `product[uuid]`
-- `product[identifier]`
-
-For `pim.product-model.tab` and `pim.sub-product-model.header` position, this parameter is sent:
-- `product[code]`
-
-For `pim.category.tab` position, this parameter is sent:
-- `category[code]`
-
-## Available types by position
+### Available types by position
 Each position supports a specific subset of available types. The table below outlines the compatible types for all positions.
 
 | Positions                    | Action | Iframe | Link  |