Modularization in YAML
YAML modules build on data models supplied by other modules. A module can add its own model elements, change selected properties of existing elements, or exclude elements from the build. These contributions stay in the module that defines them; they do not require editing the source module.
This page shows how these relationships appear in a converted YAML workspace and how they relate to AOD modifications. For the general concepts, see Modularization.
How modules fit together
Consider the Activity module and its dependency on the Contact module. Contact defines the Organisation entity and its views. Activity contributes its own field to that entity and a change to one of its view templates. The files are stored in different packages, even though their paths describe the same logical context:
Activity YAML workspace
├── .aditoprj/dependencies/@aditosoftware/contact/
│ └── contexts/Organisation/... # Contact's converted models
└── contexts/Organisation/
├── entity/fields/LastActivity/
│ └── LastActivity.field.yaml # Field contributed by Activity
└── views/OrganisationPreview_view/viewTemplates/Header/
└── Header.card.override.yaml # Activity's change to Contact's card
During transpilation, the project and its dependencies are assembled into the effective model. The original Contact files remain in the dependency; Activity's files describe its contribution. For a general explanation, see Transpile.
The YAML workspace's package.json refers to converted modules under
.aditoprj/dependencies. To change a dependency version, follow
Updating module dependencies rather than
editing the generated dependency copy.
Add an element to another module's model
Activity adds LastActivity to Contact's Organisation entity with its own
LastActivity.field.yaml. The Parent section establishes the relationship
across the module boundary:
General:
title: Activity_Days inactive
Parent:
parent: /contexts/Organisation/entity/Organisation_entity.entity.yaml
yamlPath: General/entityFields
Processes:
valueProcess: ./valueProcess.js
The field and its valueProcess.js belong to Activity; the parent entity
belongs to Contact. The parent path identifies the existing entity, and
yamlPath identifies the collection receiving the field. The example omits
other properties from the actual file.
Change an existing element
To change a property of a model element supplied by another module, use a
*.override.yaml file for that element. It contains the properties changed by
the current module and the information needed to locate the parent. It is not
necessarily a complete copy of the original element. Multiple changes to the
same target are grouped in that module's override file; changes from other
modules remain in their respective packages.
Exclude an existing element
To exclude an element supplied by another module from the build, use its
override file with Modularization.includeInBuild: false. The source file
remains in the dependency. Check any references and behavior that depend on the
excluded element. A concrete example follows below.
Relationship to AOD modifications
In an AOD project, changes to another module's data model are recorded as modifications. In YAML, those contributions are represented as model files or override files, depending on the change:
| AOD modification | YAML override file | |
|---|---|---|
| Purpose | Records an operation against a model from another module. | Represents changes to an existing element in the YAML workspace. |
| Location | An .aod file under the modifying package's modification directory. | A *.override.yaml file in the corresponding model hierarchy of the modifying package. |
| Content | Identifies the model, target path, operation and, where applicable, value. | Contains the relevant YAML properties and parent information. |
| Processing | The transpile applies modifications to the target model. | Conversion and transpilation use the override to represent changes against the existing model. |
An override file and an AOD modification are not two independent changes to make for the same property. They can be representations of the same change in the two project formats. See Modifications for the AOD format.
How operations map to YAML
| AOD operation | YAML representation |
|---|---|
INSERT | Add the new element as its own YAML model file in your package, such as foo.field.yaml. |
MODIFY (update) | Put changes to the same target element in one *.override.yaml file in your package. |
DELETE | Exclude the existing element using Modularization.includeInBuild: false in its override file. |
For example, to add the foo field to an entity provided by another module,
create a field file in your own package. Its parent points to the existing
entity definition:
contexts/Example/entity/fields/foo/foo.field.yaml
Parent:
parent: /contexts/Example/entity/Example_entity.entity.yaml
yamlPath: General/entityFields
This excerpt shows the parent relationship; add the field properties required by its schema. The new field is a separate definition, not an override of the entity. The original entity in the dependency remains unchanged.
In contrast, changes to existing properties of the same target are collected in one override file in the modifying module, even if they were separate AOD modifications. Changes made by different modules remain in their respective packages.
To exclude an existing field from the build, use an override for that field:
Modularization:
includeInBuild: false
Parent:
parent: /contexts/Example/entity/Example_entity.entity.yaml
yamlPath: General/entityFields
This excludes the target from the build; it does not delete the original file from its source module. Check references to the field and test the affected functionality after excluding it.
Example: Change a view template action
In the Activity example, the Contact module supplies a Header card in the
PersonPreview_view view. The original YAML definition is in the converted
dependency:
.aditoprj/dependencies/@aditosoftware/contact/contexts/Person/views/PersonPreview_view/viewTemplates/Header/Header.card.yaml
The Activity module has a separate override file at the corresponding location in its own workspace:
contexts/Person/views/PersonPreview_view/viewTemplates/Header/Header.card.override.yaml
Its content includes the following:
Actions:
favoriteAction1: newActivity
Parent:
parent: /contexts/Person/views/PersonPreview_view/PersonPreview_view.view.yaml
yamlPath: General/children
Here Actions.favoriteAction1 supplies the changed value. The Parent
section identifies the view and its child collection; it does not make this a
new, independent Header card. The original card is still supplied by the
Contact module. Other properties of that card are not shown in this override.
In the corresponding AOD representation, a MODIFY modification targets
PersonPreview_view/children/Header/favoriteAction1 and supplies the new
value. During conversion, metadata connects the YAML representation to the AOD
modification for the return conversion. Preserve the generated metadata; do not
edit or delete it as a substitute for editing the model.
Work with override files
- Identify the original element and its owning dependency. Inspect the dependency's definition and the override together to understand the effect of the change.
- Edit the relevant property in the override in your own package. Keep the
parent reference and the
.override.yamltype suffix consistent with the target. Do not edit the generated dependency copy under.aditoprj/dependenciesto customize it. - Validate the YAML, run the applicable transpile and tests, and check the resulting behavior. When using parallel operation, transfer the YAML changes back to AOD using Transfer Extension Pack Changes.
- After a dependency update, review the override against the updated source. A renamed or removed target can invalidate the change; upstream changes can also alter its meaning.
An override depends on the structure and behavior of another module. Prefer supported Extension Points or Services when they provide the required extension. Verify changes against the target module after upgrades.
An override file is distinct from an npm overrides entry in package.json,
which changes dependency resolution, and from replacing a whole project-level
file. See npm overrides and
project-level overrides.