docs(components): update documentation on components

AmadeusITGroup · Apr 4, 2024 · 032954f · 032954f
1 parent e9e9af7
commit 032954f
Show file tree

Hide file tree

Showing 11 changed files with 268 additions and 461 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -11,7 +11,7 @@ The documentation is sorted by topic but in the table below, you shall find the
 | @o3r/apis-manager        | Service to help you communicate with your APIs                                                                                                                 | @o3r/dev-tools                                                                                                                                                                                               | [API_MANAGER](./apis-manager/API_MANAGER.md)                                                                                                                                                                                                                                                                                                                                                                                             |
 | @o3r/application         | Provides development tools for your Otter application                                                                                                          | @o3r/core <br/> @o3r/dev-tools                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | @o3r/chrome-devtools     | Chrome plugin to debug your Otter application                                                                                                                  | N/A                                                                                                                                                                                                          | [chrome-devtools](./dev-tools/chrome-devtools.md)                                                                                                                                                                                                                                                                                                                                                                                        |
-| @o3r/components          | Component related features (Component replacement, CMS compatibility, helpers, pipes, debugging developer tools...) <br/> Comes with an integrated ng builder  | @o3r/analytics <br/> @o3r/build-helpers <br/> @o3r/configuration <br/> @o3r/core <br> @o3r/dev-tools <br/> @o3r/extractors <br/> @o3r/localization <br/> @o3r/logger <br> @o3r/schematics <br/> @o3r/testing | [COMPONENT_STRUCTURE](./components/COMPONENT_STRUCTURE.md) <br/> [COMPONENT_STYLE_OVERRIDE](./components/COMPONENT_STYLE_OVERRIDE.md) <br/> [CONTAINER_PRESENTER](./components/CONTAINER_PRESENTER.md) <br/> [FIXTURES](./components/FIXTURES.md) <br/> [NAMING_CONVENTION](./components/NAMING_CONVENTION.md) <br/> [COMPONENT_REPLACEMENT](./components/COMPONENT_REPLACEMENT.md) <br/> [CMS_ADAPTERS](./cms-adapters/CMS_ADAPTERS.md) |
+| @o3r/components          | Component related features (Component replacement, CMS compatibility, helpers, pipes, debugging developer tools...) <br/> Comes with an integrated ng builder  | @o3r/analytics <br/> @o3r/build-helpers <br/> @o3r/configuration <br/> @o3r/core <br> @o3r/dev-tools <br/> @o3r/extractors <br/> @o3r/localization <br/> @o3r/logger <br> @o3r/schematics <br/> @o3r/testing | [COMPONENT INTRODUCTION](./components/INTRODUCTION.md) <br/> [COMPONENT_STYLE_OVERRIDE](./components/COMPONENT_STYLE_OVERRIDE.md) <br/> [CONTAINER_PRESENTER](./components/CONTAINER_PRESENTER.md) <br/> [FIXTURES](./components/FIXTURES.md) <br/> [COMPONENT_REPLACEMENT](./components/COMPONENT_REPLACEMENT.md) <br/> [CMS_ADAPTERS](./cms-adapters/CMS_ADAPTERS.md) |
 | @o3r/configuration       | Configuration related features (CMS compatibility, Configuration override, store and debugging)                                                                | @o3r/core <br/> @o3r/dev-tools <br/> @o3r/logger <br/> @o3r/testing                                                                                                                                          | [OVERVIEW](./configuration/OVERVIEW.md) <br/> [CONFIGURATION_SUPPORTED_EXTRACTOR](./configuration/CONFIGURATION_SUPPORTED_EXTRACTOR.md) <br/> [CMS_ADAPTERS](./cms-adapters/CMS_ADAPTERS.md)                                                                                                                                                                                                                                             |
 | @o3r/core                | Foundation for all the packages (interfaces, core helpers) and schematics to generate your components/services etc.                                            | N/A                                                                                                                                                                                                          | [START_NEW_APPLICATION](./core/START_NEW_APPLICATION.md) <br/> [DEVELOPER](./core/DEVELOPER.md) <br/> [OTTER_ANGULAR_TOOLS](./core/OTTER_ANGULAR_TOOLS.md)                                                                                                                                                                                                                                                                               |
 | @o3r/design              | Tools to generate theme from design materials                                                                                                                  | N/A                                                                                                                                                                                                          | [TECHNICAL_DOCUMENTATION](./design/TECHNICAL_DOCUMENTATION.md)                                                                                                                                                                                                                                                                                                                                                                           |

diff --git a/docs/components/COMPONENT_REPLACEMENT.md b/docs/components/COMPONENT_REPLACEMENT.md
@@ -132,7 +132,7 @@ This configuration key's value is used at runtime to lookup in the component rep
 
 ## How components are made to accept replacement
 
-In this section we will detail how to make a container's presenter replaceable by this mechanism with a simple, almost empty component.
+In this section we will detail how to make a subcomponent replaceable by this mechanism with a simple, almost empty component.
 
 ### Component's module
 
@@ -178,6 +178,31 @@ export const DUMMY_CONT_DEFAULT_CONFIG: DummyContConfig = {
 export const DUMMY_CONT_CONFIG_ID = computeConfigurationName('DummyContConfig', '@scope/o3r-components');
 ````
 
+For more information on configuration, you can check this [documentation](../configuration/OVERVIEW.md).
+
+### Subcomponent's context (`.context.ts`)
+
+It is used to define the contract to interact with your component, defining the set of dynamic inputs and outputs that a component has.
+It is structured into three interfaces:
+
+* `*ContextInput` interface (e.g. `DummyPresContextInput`): it contains all the inputs of a component. Fields must have a documentation.
+* `*ContextOutput` interface (e.g. `DummyPresContextOutput`): it contains all the outputs of a component. Fields must have a documentation.
+* interface `DummyPresContext`: it brings together `ContextInput` and `ContextOutput`, extending `Context<DummyPresContextInput, DummyPresContextOutput>` from `@o3r/core`.
+
+```typescript
+import {Context} from '@o3r/core';
+
+export interface DummyPresContextInput {
+  dummyInput: string;
+}
+
+export interface DummyPresContextOutput {
+  onDummyOutput: number;
+}
+
+export interface DummyPresContext extends Context<DummyPresContextInput, DummyPresContextOutput> {}
+```
+
 ### Component's class
 
 Here we need to do a couple of things:
@@ -243,8 +268,8 @@ export class DummyContComponent implements DynamicConfigurable<DummyContConfig>,
     };
   }
 
-  public dummyOutput() {
-    console.log('output');
+  public dummyOutput(event: number) {
+    console.log('output', event);
   }
 }
 ````
@@ -272,17 +297,14 @@ Instead, we will simply use an ``ng-template`` tag to which we apply the Otter `
 
 The main limitation is that it is not possible to apply any modification to the ``host`` component created by a factory.
 
-What it means is that any of those:
+What it means is that:
 
 ````html
 <!-- Host binding -->
 <o3r-dummy-cont [class]="dynamicClass"></o3r-dummy-cont>
-
-<!-- Applying directives to the component -->
-<o3r-dummy-cont [formControl]="dummyFormControl"></o3r-dummy-cont>
 ````
 
-Are not possible through an ``ng-template`` and ``c11n`` combination.
+Is not possible through an ``ng-template`` and ``c11n`` combination.
 
 Though there is a solution for the first example in making the value an input, and bind it inside the component using
 the [HostBinding](https://angular.io/api/core/HostBinding) decorator, there is no actual solution for applying directive.

diff --git a/docs/components/COMPONENT_STRUCTURE.md b/docs/components/COMPONENT_STRUCTURE.md