Module definition items

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

A definition item is a component configuration for executing tasks in a Magnolia instance. Template definitions, dialog definitions, app definitions (also known as app descriptors), renderer definitions, themes definitions and field definitions are all examples of such definition items.

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

The table below outlines the configuration item, its purpose, and whether it is visible in Apps/Definitions-app.adoc

Config item Purpose Visible

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.

Trait

A trait is an attribute or property of a visitor or visit, such as age or gender, that you can use to personalize content.

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.

We recommend using YAML files for definition items.

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 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[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

Item YAML file path JCR node path in the config workspace

App descriptor

$magnolia.resources.dir/<module‑name>/apps

/modules/<module‑name>/apps

Command definition

/modules/<module‑name>/commands

Dialog definition

$magnolia.resources.dir/<module‑name>/dialogs

/modules/<module‑name>/dialogs

Field type definition (Magnolia 5 UI)

$magnolia.resources.dir/<module‑name>/fieldTypes

/modules/<module‑name>/fieldTypes

Media editor definition

$magnolia.resources.dir/<module‑name>/mediaEditors

/modules/<module‑name>/mediaEditors

Message view definition

$magnolia.resources.dir/<module‑name>/messageViews

/modules/<module‑name>/messageViews

Renderer definition

$magnolia.resources.dir/<module‑name>/renderers

/modules/<module‑name>/renderers

REST endpoint definition

$magnolia.resources.dir/<module‑name>/restEndpoints

/modules/<module‑name>/restEndpoints

Template definition

$magnolia.resources.dir/<module‑name>/templates

/modules/<module‑name>/templates

Trait definition

/modules/<module‑name>/traits

Virtual URI mapping definition

$magnolia.resources.dir/<module‑name>/virtualUriMappings

/modules/<module‑name>/virtualUriMappings

dev days event sign up
dev days event sign up
Feedback