Module definition items

This page provides an overview of definition items which can be specified in Magnolia modules.

The majority of these items can be configured via YAML, in which case they are registered in a specific registry. The items registered can be seen in the Definitions app and can be modified through definition decoration. Even though definition items can be configured via JCR in the configuration workspace, configuring them in YAML files is the recommended approach.

Overview of definition items

Configuration item	Purpose	Visible in the Definitions app
apps	optional, YAML supported App descriptor files, defining Apps.
commands	optional Command definitions used with Magnolia command management.
dialogs	optional, YAML supported Dialog definitions for content editing.
fieldTypes	optional, YAML supported Field definitions for Magnolia 5 UI fields.
mediaEditors	optional, YAML supported Media Editor definitions.
messageViews	optional, YAML supported Message view definitions.
renderers	optional, YAML supported Renderer definitions. Creating custom renderers for other templating languages such as Velocity is possible. Magnolia ships with the FreeMarker template renderer.
restEndpoints	optional, YAML supported REST endpoint definitions.
templates	optional, YAML supported Template definitions for pages, areas or components.
traits	optional A trait is an attribute or property of a visitor or visit, such as age or gender, that you can use to personalize content.
virtualURIMapping	optional, YAML supported URI mapping definitions that redirect an incoming request to the actual content location.

Configuring in JCR and in YAML

While all of the configuration items listed above can be stored as JCR nodes, not all of them have YAML support. The items which cannot be stored yet as YAML files may, however, get YAML support in future Magnolia versions.

Both JCR nodes and YAML files are observed. If a data change is detected, object representations are changed in the associated registries. For instance, a change in a template definition re-registers or updates the TemplateDefinition in TemplateDefinitionRegistry.

Item definitions from both JCR nodes and YAML files can be decorated with a definition decoration.

JCR nodes

In JCR context, module configuration items are stored as nodes in the configuration workspace. Use the Configuration app to add, edit or delete JCR-based configuration. The items ares stored under /modules/<module‑name>, for instance under /modules/myModule/templates. JCR configuration nodes are observed using functions provided by the Observation module.

Benefits:

• All configuration items are supported.
• Changes can be published (activated) to other instances.
• The extends mechanism is supported.

YAML files

In a module, YAML configuration files reside in their corresponding folders. For example, <module‑name>/templates is the folder for the templates. To add, edit or delete a YAML file, use any text editor of your choice. Many modern editors such as Brackets or Sublime Text support YAML syntax highlighting.

Directories containing YAML-based configuration data are observed using the DirectoryWatcherService.

Benefits:

• Text files are human readable and easy to compare, which makes collaboration better.

• No need to export. Files are already part of the project lifecycle.

• No need for version handlers for updates.
• Uninstalling is easy.
• The include mechanism is supported.

Location of configuration items