Skip to content

Commit

Permalink
feat: update configuration doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@sdo-1A
sdo-1A committed Apr 16, 2024
1 parent c1932a3 commit 4c2a2ab
Show file tree
Hide file tree
Showing 2 changed files with 145 additions and 137 deletions.
95 changes: 51 additions & 44 deletions docs/configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,23 @@
# Configuration
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`.

Note that the component.class.metadata.json is used at the moment only in rules engine scope, but in the future will be a requirement for the next steps of the Adobe SPA Editor.
The _component extractor_ is used to extract the configuration metadata from an application or a library. It extracts the list of all configuration 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 configs, pages, components).
It also generates the metadata for component classes and types from an Otter library/application, outputting them in a JSON file `component.class.metadata.json`.

Note that the `component.class.metadata.json` file is currently only used in the scope of the rules engine, but will be required in the future for the next steps of the Adobe SPA Editor.

## How to use it

Since the v3 of Otter, you should use the component-extraction builder directly in your angular.json
You should use the component-extraction builder directly in your `angular.json` file.
The Component Extractor is accessible via an NgCLI builder: `@o3r/components:extractor`.
For an up-to-date documentation, run `ng help @o3r/components:extractor`.

First thing to do is to define your given filenames for the configuration in the _package.json_ of the library/app where you run the extractor.
When running in a library it will use this configuration as the names for the metadata files.
When running the extractor in an application, it will search for these filenames in each node_module (package.json file) of each library,
in order to concat the metadata from the file with other libraries metadata and app metadata.
First, define your filenames for the configuration in the `package.json` of the library/app where you run the extractor.
* When the extractor is run in a library, it uses this configuration to name the metadata files.
* When the extractor is run in an application, it searches for these file names in each node_module (in the `package.json` file) of each library,
in order to concatenate the file's metadata with the metadata of the other libraries and the application's metadata.

```
```json
// in package.json file
...
"cmsMetadata": {
Expand All @@ -23,14 +28,14 @@ in order to concat the metadata from the file with other libraries metadata and
...
```

The Component Extractor is accessible via a NgCLI builder: `@o3r/components:extractor`;

For an up-to-date documentation, run `ng help @o3r/components:extractor`
If the _component extractor_ is run on an application that is using components from an otter library, the _libraries_ option can be
specified to concatenate the classes/configuration files generated for the application with those of the specified _libraries_.
The extractor will search for a `component.config.metadata.json` file and a `component.class.metadata.json` file in the node_modules package
of each defined library (the name of the files to be searched for will be read from the `cmsMetadata` property in the `package.json` file defined for each library).

* If the _component extractor_ is run on an application which is using components from an otter library, the _libraries_ option can be specified to concat classes/configuration files generated for application with ones from specified _libraries_. The extractor will search a _'component.config.metadata.json'_ and a _component.class.metadata.json_ file in the node_modules package of each defined library (the name of the files to search will be read from the _cmsMetadata_ property in _package.json_ file defined for each library).
* Here is an example on the otter demo app
Here is an example on the otter demo app:

```
```json
// in angular.json
"extract-components": {
"builder": "@o3r/components:extractor",
Expand All @@ -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]
> These options will not search for the duplicate configurations in libraries.
The __strict mode__ option should be used for production builds, it will throw an error if something not supported by the
CMS is found in the config. You can set it to `false` to allow the generation of metadata including the unknown types to
ease issues fixing, and with the errors logged as warnings.
CMS is found in the configuration. You can set it to `false` to enable the generation of metadata including the unknown types to
facilitate troubleshooting, and with errors logged as warnings.

Here is an example on a library
Here is an example on a library:

```json
{
//...
"extract-configurations": {
"extract-components": {
"builder": "@o3r/components:extractor",
"options": {
"tsConfig": "modules/@scope/area/components/tsconfig.metadata.json",
Expand All @@ -67,13 +73,13 @@ Here is an example on a library
}
```

In case you have a lib in a mono repository, it's important to specify both configOutputFile and componentOutputFile, by
default if not specified, it will be generated at the root of the project
In case you have a library in a mono repository, it's important to specify both the `configOutputFile` option and the `componentOutputFile` option.
By default, if not specified, the output files will be generated at the root of the project.

For the tsconfig, you should include only the files that you want to parse, i.e. components, modules and config. You can
For the tsconfig, you should include only the files that you want to parse, i.e. components, modules, and config. You can
extend your tsconfig, and just override the fields that you need.

Example of a tsconfig :
Example of a tsconfig:

```json
{
Expand All @@ -92,8 +98,8 @@ Example of a tsconfig :

## Component file (*.component.ts)

Here is an example of configuration in the component, note that dynamicConfig$ is there for the configuration service
and config$ for the configuration store
Here is an example of configuration in the component, note that `dynamicConfig$` is there for the configuration service
and `config$` for the configuration store.

```typescript
// ...
Expand All @@ -120,20 +126,19 @@ export class MyComponent implements DynamicConfigurable<MyConfig> {
}
```

## Configuration file (*.config.ts)
## Configuration file (*.config.ts) --> NEEDS UPDATING

You need to implement Configuration
You need to implement the configuration.

NestedConfiguration is part of @o3r/core package, with only primitive types allowed inside ( string | boolean |
number)
`NestedConfiguration` is part of the @o3r/core package, with only primitive types allowed inside (string | boolean | number).
Optional types that are __not__ supported will be ignored by the extractor.

OPTIONAL Types NOT supported: they will be ignored by the extractor Here is an example of configuration file containing
all the supported types :
Here is an example of a configuration file containing all the supported types:

```typescript

/**
* an UnionType with string values used in configuration (ex: can be reused for several fields)
* a UnionType with string values used in configuration (ex: can be reused for several fields)
*/
type Position = 'top' | 'bottom';

Expand Down Expand Up @@ -219,8 +224,8 @@ export const MY_DEFAULT_CONFIG: MyConfig = {
};
```

Note that the order for the Nested config interface doesn't matter, but the default config needs to be put AFTER the
interface declaration, and contain no variable references.
Note that the order of the Nested configuration interface doesn't matter, but the default configuration needs to be placed __AFTER__ the
interface declaration, and must not contain any variable references.

`UnionTypes` are supported in 2 cases:

Expand All @@ -229,8 +234,7 @@ interface declaration, and contain no variable references.

### Configuration tags

Tagging configuration is possible starting otter v4.1. To implement this feature, one should add the tags in the JSDoc
of the configuration interface while respecting the following format:
To implement this feature, one should add the tags in the JSDoc of the configuration interface while respecting the following format:

```typescript
/**
Expand All @@ -244,10 +248,12 @@ export interface MyConfig extends Configuration {
}
```

These tags will be exported inside the extracted metadata (see the [CMS Adapters documentation](../cms-adapters)) provided
they are supported in the [CMS JSON schema](https://github.com/AmadeusITGroup/otter/tree/main/packages/%40o3r/configuration/schemas/configuration.metadata.schema.json). Please refer to the schema for the latest supported model.
These tags will be exported inside the extracted metadata (see the [CMS Adapters documentation](https://github.com/AmadeusITGroup/otter/blob/main/docs/cms-adapters/CMS_ADAPTERS.md))
provided they are supported in the [CMS JSON schema](https://github.com/AmadeusITGroup/otter/tree/main/packages/%40o3r/configuration/schemas/configuration.metadata.schema.json).
Please refer to the schema for the latest supported model.

For instance, if you want to add a title to your component's configuration to provide a user-friendly name and label for your property, you can set the following tags:

For instance, if you want to add a title to your component's configuration as a way to have a user friendly naming and a label for your property, you can set the following tags:
```typescript
/**
* This is an incredible config but the name is not so easy to read for CMS users
Expand All @@ -264,8 +270,9 @@ export interface MyConfigWithADifficultName extends Configuration {
}
```

If you use any non supported tags in your tsdocs, it will be ignored by the extractor. For example, in the following example, the invalidTag will not be part of the
If you use any non-supported tags in your tsdocs, they will be ignored by the extractor. For instance, in the following example, `invalidTag` will not be part of the
extracted metadata.

```typescript
/**
* Yet another Configuration
Expand Down Expand Up @@ -339,7 +346,7 @@ export interface SimpleHeaderPresConfig extends Configuration {

## Troubleshooting

Starting from Otter 3.5 we have strong validators on the metadata output, if you face any issue importing in the CMS,
ensure that you have no warning raised in the cms-adapter run.
We have strong validators on the metadata output so if you face any issues when importing in the CMS, please
ensure that no warnings have been raised when running the cms-adapter.

You can also check the config causing the issue in your metadata file to see if there is something unusual.
You can also check the configuration causing the issue in your metadata file to see if there is anything unusual.

0 comments on commit 4c2a2ab

Please sign in to comment.