-
Notifications
You must be signed in to change notification settings - Fork 34
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: update configuration doc #1672
base: main
Are you sure you want to change the base?
Conversation
☁️ Nx Cloud ReportCI is running/has finished running commands for commit 9b25f62. As they complete they will appear below. Click to see the status, the terminal output, and the build insights. 📂 See all runs for this CI Pipeline Execution ✅ Successfully ran 1 targetSent with 💌 from NxCloud. |
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
__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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
a3dca3d
to
87d0b96
Compare
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it looks weird to have an example of angular.json
after a whole paragraph about package.json
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would you suggest rephrasing or to remove the example?
docs/configuration/OVERVIEW.md
Outdated
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This corresponds to the customized configuration, I can rephrase if the sentence is not clear enough
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
> 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You may create a linter rule for that ! :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can do it in a separate Github issue ;)
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And a vscode extension for autocomplete
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I will open an issue once the PR is merged
} | ||
``` | ||
|
||
### Configuration categories |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And a vscode extension for autocomplete
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I will open an issue once the PR is merged
Proposed change
Update documentation on configuration