Skip to main content

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:

LastActivity.field.yaml (excerpt)
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 modificationYAML override file
PurposeRecords an operation against a model from another module.Represents changes to an existing element in the YAML workspace.
LocationAn .aod file under the modifying package's modification directory.A *.override.yaml file in the corresponding model hierarchy of the modifying package.
ContentIdentifies the model, target path, operation and, where applicable, value.Contains the relevant YAML properties and parent information.
ProcessingThe 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 operationYAML representation
INSERTAdd 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.
DELETEExclude 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
foo.field.yaml (excerpt)
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:

foo.field.override.yaml (excerpt)
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​

  1. Identify the original element and its owning dependency. Inspect the dependency's definition and the override together to understand the effect of the change.
  2. Edit the relevant property in the override in your own package. Keep the parent reference and the .override.yaml type suffix consistent with the target. Do not edit the generated dependency copy under .aditoprj/dependencies to customize it.
  3. 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.
  4. 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.
warning

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.