feat: update configuration doc #1672
Conversation
github-actions
bot
added
documentation
| @@ -43,18 +48,19 @@ For an up-to-date documentation, run `ng help @o3r/components:extractor` | |||
| }, | |||
| ``` | |||
|
|
|||
| __Note:__ This options will not search for the duplicate configurations in libraries. | |||
| > [!NOTE] | |||
There was a problem hiding this comment.
Sounds a bit more like a warning
| > [!NOTE] | |
| > [!WARNING] |
There was a problem hiding this comment.
| @@ -1,18 +1,23 @@ | |||
| # Configuration | |||
There was a problem hiding this comment.
This file is missing documentation regarding the O3rConfig decorator
There was a problem hiding this comment.
|
I did not realize that there were already updates on this documentation in another PR: #1583 I also tried to resolve the comments from the other PR (which I will copy paste into the code to make it simpler to review). |
docs/configuration/OVERVIEW.md
Outdated
| form fields from an Angular material input element ...) | ||
| - A common configuration is defined in every library. The application common configuration (__global config__) will be | ||
| the result of the __merge of all common__ configurations. | ||
| - The __common configuration__ is the one used in multiple components. It can be a date format, a price display, an input |
There was a problem hiding this comment.
comment from @cpaulve-1A:
I would put emphasis on the "common configuration" via bold text and put the inside of the parenthesis in a separate.
The type of input is really unclear and would leave out this example if we don't make it cleare. (I finally got the idea that it might be the presentation of the angular inputs)
https://github.com/AmadeusITGroup/otter/pull/1583/files#r1555909792
docs/configuration/OVERVIEW.md
Outdated
| __Pre-bootstrap configuration__ | ||
|
|
||
| - Defined in one interface extending the __AppBuildConfiguration__ from __@o3r/core__ in order to be identified by the extractor. | ||
| - Used for configurations needed before loading the Angular application component. They will be |
There was a problem hiding this comment.
comment from @pginoux-1A:
It's not injected by the CMS, there is no runtime interactions with the CMS, it's used as an edition panel for the customization and the files are exported in the dynamic content folder afterwards. We should advertise that this part is linked to a piece of code server side that updates the index.html and what requires to be added with an example
https://github.com/AmadeusITGroup/otter/pull/1583/files#r1557804902
sdo-1A
force-pushed
the
doc/config
branch
2 times, most recently
from
a3dca3d
to
87d0b96
Compare
docs/configuration/OVERVIEW.md
Outdated
|
|
||
| - Each __component type__ can have a customized config (compliant with the store model). This custom config can be | ||
| - Each __configurable component__ can have a customized configuration (compliant with the store model). This custom configuration can be |
There was a problem hiding this comment.
This is a bit strange to phrase it this way and call it store configuration in the rest of the documentation.
Maybe we could call it runtime configuration and only mention the store as a way to store this configuration instead of making it seems like the update of the store is the purpose of the configuration (not just the way the configuration is stored in the application).
sdo-1A
force-pushed
the
doc/config
branch
2 times, most recently
from
e88256f
to
5c020fc
Compare
| * If the __component extractor__ is run on an application with components from an Otter library, the `libraries` option can be used to concatenate the metadata files generated for the application with the ones from the specified libraries. | ||
| The extractor will search for the component configuration and style metadata files in the `node_modules` package of each configured library. | ||
| The name of the metadata files to search for is defined for each library in the `cmsMetadata` property defined in their respective `package.json` files. | ||
| * Here is an example of an `angular.json` file: |
There was a problem hiding this comment.
it looks weird to have an example of angular.json after a whole paragraph about package.json
There was a problem hiding this comment.
Would you suggest rephrasing or to remove the example?
| - the second priority is the priority by component type set in the store | ||
| - the lowest priority is the default config set on component (in the config.ts file of the component) | ||
| - The highest priority is the one passed as input from a parent component | ||
| - The second priority is the priority by component ID set dynamically |
There was a problem hiding this comment.
I'm not sure to understand this part
also, is it not already kind of covered by the schema in the Component configuration types section ?
There was a problem hiding this comment.
This corresponds to the customized configuration, I can rephrase if the sentence is not clear enough
And yes, this is copied in the key takeaways section of the documentation
| To extract the configuration metadata from an application/library the _component extractor_ will be used. It extracts the list of all the config interfaces defined in a library or application. The output is a json file `component.config.metadata.json` containing an array of all the components configurations (app configs, pages, components). | ||
| It will also generate the component classes and types metadata from an Otter library/application, outputting them in a json file `component.class.metadata.json`. | ||
| The component extractor is used to extract the configuration metadata from an application or a library. It extracts the list of all the config interfaces defined | ||
| in a library or an application. The output is a JSON file `component.config.metadata.json` containing an array of all the component configurations (app configurations, pages, components). |
There was a problem hiding this comment.
component.config.metadata.json is the default name, it can be changed
| To extract the configuration metadata from an application/library the _component extractor_ will be used. It extracts the list of all the config interfaces defined in a library or application. The output is a json file `component.config.metadata.json` containing an array of all the components configurations (app configs, pages, components). | ||
| It will also generate the component classes and types metadata from an Otter library/application, outputting them in a json file `component.class.metadata.json`. | ||
| The component extractor is used to extract the configuration metadata from an application or a library. It extracts the list of all the config interfaces defined | ||
| in a library or an application. The output is a JSON file `component.config.metadata.json` containing an array of all the component configurations (app configurations, pages, components). |
There was a problem hiding this comment.
Not sure to understand the parentheses content.
Is part of the "Component Configurations"? but in this case, not sure we should indicate "app configurations". Or is the different types of configurations? If so a link to describe the different type of configs can help and maybe it would be more readable written in that way: app, pages and components configurations without being between parentheses
| ``` | ||
| // in angular.json | ||
| * If the __component extractor__ is run on an application with components from an Otter library, the `libraries` option can be used to concatenate the metadata files generated for the application with the ones from the specified libraries. | ||
| The extractor will search for the component configuration and style metadata files in the `node_modules` package of each configured library. |
There was a problem hiding this comment.
Do not explicitly speak about node_modules, we should prefer dependencies to indicate the support of non-NPM clients
docs/configuration/OVERVIEW.md
Outdated
|
|
||
| ``` | ||
|
|
||
| store config | ||
| dynamic config |
There was a problem hiding this comment.
Not sure the term is correct as they are all "dynamic config".
Maybe we can use "customized configuration"?
But a link scribing the different configuration process (or giving an example of it) can help :S
docs/configuration/OVERVIEW.md
Outdated
| }; | ||
| ``` | ||
|
|
||
| ### Component file (*.component.ts) | ||
| > [!WARNING] | ||
| > Default configuration needs to be written AFTER the interface declaration and contain no variable references. |
There was a problem hiding this comment.
| > Default configuration needs to be written AFTER the interface declaration and contain no variable references. | |
| > Default configuration const needs to be explicitly typed with the configuration interface and contain no variable references. |
There was a problem hiding this comment.
Can be a good practice to add a list of relative packages (link to their readme.md) in the end of the documentation to facilitate the navigation
sdo-1A
force-pushed
the
doc/config
branch
2 times, most recently
from
1aba2ee
to
d3eecd0
Compare
|
|
||
| > __WARNING__ the field name 'id' should not be used in the configuration, as we created a unique one for the entity configuration store | ||
| > [!WARNING] | ||
| > The field name `id` should not be used in the configuration, as we use this field in our internal implementation. |
There was a problem hiding this comment.
You may create a linter rule for that ! :)
docs/configuration/OVERVIEW.md
Outdated
|
|
||
| - At __library__ level we have the config for components (__blocks, components, elements__). | ||
| - At __library__ level, we have the configuration for `Block` and `ExposedComponent`, see [available component types](https://github.com/AmadeusITGroup/otter/blob/main/docs/components/INTRODUCTION.md#component-type). |
There was a problem hiding this comment.
You can define component in your application also
docs/configuration/OVERVIEW.md
Outdated
| injected by the CMS in the index.html body tag data-bootstrapconfig as a data attribute | ||
| - Defined in one interface extending the __AppBuildConfiguration__ from __@o3r/core__ in order to be identified by the extractor. | ||
| - Used for configurations needed before loading the Angular application component. It is up to the server to specify the body tag | ||
| `data-dynamiccontentpath` as a data attribute inside the `index.html` so the application can get the latest version of the dynamic |
There was a problem hiding this comment.
I'm not sure dynamiccontentpath as something related to the configuration
| 1) inline definition (see above `myUnionTypeField`) | ||
| 2) reference to a union type that is defined in the same configuration file (see above `myReferencedUnionTypeField` and `Position`). | ||
|
|
||
| ### Configuration tags |
There was a problem hiding this comment.
Maybe we can add that we expose a linter for that docs/linter/eslint-plugin/rules/o3r-categories-tags.md
There was a problem hiding this comment.
And a vscode extension for autocomplete
| } | ||
| ``` | ||
|
|
||
| ### Configuration categories |
There was a problem hiding this comment.
Maybe we can add that we expose a linter for that docs/linter/eslint-plugin/rules/o3r-widget-tags.md
There was a problem hiding this comment.
And a vscode extension for autocomplete
Proposed change
Update documentation on configuration