diff --git a/docs/components/PLACEHOLDERS.md b/docs/components/PLACEHOLDERS.md index cb1ccff5aa..c4ae0367d1 100644 --- a/docs/components/PLACEHOLDERS.md +++ b/docs/components/PLACEHOLDERS.md @@ -14,8 +14,7 @@ The component only has 1 input and supports a *content value*. ## How it works -Based on the **id** provided to the placeholder component, it will register itself to the event coming from * -*placeholderTemplate** and will display the template corresponding to its ID in the store. +Based on the **id** provided to the placeholder component, it will register itself to the event coming from **placeholderTemplate** and will display the template corresponding to its ID in the store. > [!IMPORTANT] > It is **strongly encouraged** to use the placeholder mechanism in concert with @@ -23,8 +22,7 @@ Based on the **id** provided to the placeholder component, it will register itse ## How to define a placeholder template -The placeholder template is defined in a JSON file following this JSON -Schema [placeholder-template.schema.json](../../packages/@o3r/components/schemas/placeholder-template.schema.json). +The placeholder template is defined in a JSON file following the [JSON Schema](https://json-schema.org/) defined in [placeholder-template.schema.json](https://github.com/AmadeusITGroup/otter/blob/main/packages/%40o3r/components/schemas/placeholder-template.schema.json). Example: @@ -33,7 +31,7 @@ Example: "template": "

My fact : <%= myFact %>

", "vars": { "myFact ": { - "value": "myFact ", + "value": "myFact", "type": "fact" } } diff --git a/docs/rules-engine/how-it-works/placeholders.md b/docs/rules-engine/how-it-works/placeholders.md index d2d4c43238..a9c71c8417 100644 --- a/docs/rules-engine/how-it-works/placeholders.md +++ b/docs/rules-engine/how-it-works/placeholders.md @@ -1,18 +1,19 @@ # Placeholders ## Localization -When a placeholder content is created using the CMS, it provides the default language in assets folder : placeholders/my-placeholder-content-name/master.json +When a placeholder content is created using the CMS, it provides the default language in assets folder: placeholders/my-placeholder-content-name/master.json Then for each new locale that you want to support, you will have to create the associated placeholder that will be automatically added to placeholders/my-placeholder-content-name/[LANG]/name.json. -For more information about experience fragments, please check: [Experience fragment](https://dev.azure.com/AmadeusDigitalAirline/DES%20Platform/_wiki/wikis/DES%20Documentation/1964/Experience-Fragments-in-DES) +For more information about experience fragments, please check: [Experience fragment](https://dev.azure.com/AmadeusDigitalAirline/DES%20Platform/_wiki/wikis/DES%20Documentation/1964/Experience-Fragments-in-DES). + The dynamic part of the URL is replaced by the locale, and each locale change triggers a new call that will retrieve the associated localized template. ## Format of the placeholder file -The placeholder file that will be sent by the cms is a json that contains both the html template and the variables that will be replaced +The placeholder file that will be sent by the CMS is a JSON file that contains both the HTML template and the variables that will be replaced. -example : +example: ```json { "vars": { @@ -29,14 +30,14 @@ example : } ``` -As of today, three different types of vars are supported : -* relativeUrl : Path to a resource from the dynamicContent (more info at [Dynamic Content](../../dynamic-content/DYNAMIC_CONTENT.md)), the mediaPath will be used to create the full path -* fact : reference to a fact, that will be replaced and plugged to the fact streams (When a fact that is referenced by the template changes, it triggers a refresh) -* fullUrl : simple replace will be performed for this one +As of today, three different types of variables are supported: +* `relativeUrl`: Path to a resource from the dynamicContent (more info at [Dynamic Content](../../dynamic-content/DYNAMIC_CONTENT.md)), the mediaPath will be used to create the full path +* `fact`: reference to a fact, that will be replaced and plugged to the fact streams (when a fact that is referenced by the template changes, it triggers a refresh) +* `fullUrl`: simple replace will be performed for this one ## Technical details -Placeholders added to the application or library requires a [metadata file](../how-to-use/integration.md), that will be merged in the component metadata file by the cms-adapter and sent to the cms. -Placeholder contents are created using the admin UI and associated to a placeholder via a rules engine action : +Placeholders added to the application or library requires a [metadata file](../how-to-use/integration.md), that will be merged in the component metadata file by the cms-adapter and sent to the CMS. +Placeholder contents are created using the admin UI and associated to a placeholder via a rules engine action: ```json { "elementType": "ACTION", @@ -45,5 +46,5 @@ Placeholder contents are created using the admin UI and associated to a placehol "placeholderId": "pl2358lv-2c63-42e1-b450-6aafd91fbae8" } ``` -The service processes the action, and set the url of the template in the store. The call to retrieve the associated template is processed, the template rendered and the result is added in the store. +The service processes the action, and set the URL of the template in the store. The call to retrieve the associated template is processed, the template rendered and the result is added in the store. Each change facts referenced in the template will trigger a new render, and each language change will trigger a new call to get the associated template (except if the content is not localized). diff --git a/docs/rules-engine/how-to-use/placeholders.md b/docs/rules-engine/how-to-use/placeholders.md index b29d81789d..486215fca7 100644 --- a/docs/rules-engine/how-to-use/placeholders.md +++ b/docs/rules-engine/how-to-use/placeholders.md @@ -21,16 +21,15 @@ import {PlaceholderModule} from '@o3r/components'; export class SearchModule {} ``` -Then add the placeholder in your html with a unique id -```typescript -... +Then add the placeholder in your HTML with a unique id +```html Placeholder loading ... -... ``` The loading message is provided by projection. Feel free to provide a spinner if you need. Once your placeholder has been added, you will need to manually create the metadata file and add the path to the extract-components property in your angular.json -Metadata file example : +Metadata file example: + ```json [ { @@ -45,7 +44,8 @@ Metadata file example : } ] ``` -And then, in the angular.json : +And then, in the `angular.json` file: + ```json ... "extract-components": { @@ -59,13 +59,13 @@ And then, in the angular.json : } }, ... - -The placeholders will be merged inside the component metadata file that will be sent to the cms. ``` +The placeholders will be merged inside the component metadata file that will be sent to the CMS. + ### Inside a library component -Add the module and the placeholder to your html the same way as before but this time you need to create the metadata file in an associated package. -Metadata file example : +Add the module and the placeholder to your HTML the same way as before but this time you need to create the metadata file in an associated package. +Metadata file example: ```json [ { @@ -80,7 +80,7 @@ Metadata file example : } ] ``` -And then in the angular.json : +And then in the angular.json: ```json ... "extract-components": { @@ -96,16 +96,16 @@ And then in the angular.json : ``` ## Supported features (check how-it-works section for more details) -* Html limited to angular sanitizer supported behavior -* Urls (relative ones will be processed to add the dynamic-media-path) +* HTML limited to angular sanitizer supported behavior +* URLs (relative ones will be processed to add the `dynamic-media-path`) * Facts references ### Static localization The first choice you have when you want to localize your template is the static localization. -You need to create a localized template for each locale and provide the template URL with [LANGUAGE] (ex: assets/placeholders/[LANGUAGE]/myPlaceholder.json) +You need to create a localized template for each locale and provide the template URL with `[LANGUAGE]` (ex: *assets/placeholders/[LANGUAGE]/myPlaceholder.json*) The rules engine service will handle the replacement of [LANGUAGE] for you, and when you change language a new call will be performed to the new 'translated' URL. -Note that the URL caching mechanism is based on the url NOT 'translated', meaning that if you change from en-GB to fr-FR then you decide to switch back and all the calls will be made again. +Note that the URL caching mechanism is based on the url NOT 'translated', meaning that if you change from `en-GB` to `fr-FR` then you decide to switch back and all the calls will be made again. This behavior is based on the fact that a real user rarely goes back and forth with the language update. ### Multiple templates in same placeholder @@ -116,13 +116,13 @@ The placeholder component waits for all the calls to be resolved (not pending) t The placeholder component ignores a template if the application failed to retrieve it. ## Investigate issues -If the placeholder is not rendered properly, you can perform several check to find out the root cause, simply looking at the store state. +If the placeholder is not rendered properly, you can perform several checks to find out the root cause, simply looking at the store state. -Example : +Example: ![store-state.png](../../../.attachments/screenshots/rules-engine-debug/store_state.png) -## Reference css classes from AEM Editor -You need to reference one or several css files from your application in the cms.json : +## Reference CSS classes from AEM Editor +You need to reference one or several CSS files from your application in the `cms.json` file: ```json { "assetsFolder": "dist/assets", @@ -138,12 +138,12 @@ You need to reference one or several css files from your application in the cms. Those files will be loaded by the CMS to show the placeholder preview. Note that you could provide an empty file and update it with the dynamic content mechanism from AEM, to be able to reference the new classes afterwards. There is just no user-friendly editor available yet. -You can include this file in your application using the style loader service in your app component : +You can include this file in your application using the style loader service in your app component: ```typescript this.styleLoader.asyncLoadStyleFromDynamicContent({id: 'placeholders-styling', href: 'assets/rules/placeholders.css'}); ``` ### How to create placeholders from AEM -For this part, please refer to the Experience Fragments in DES documentation : +For this part, please refer to the Experience Fragments in DES documentation: https://dev.azure.com/AmadeusDigitalAirline/DES%20Platform/_wiki/wikis/DES%20Documentation/1964/Experience-Fragments-in-DES