Magnolia 6.1 reached end of life on March 31, 2021. This branch is no longer supported, see End-of-life policy.
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.
Configuration item | Purpose | Visible in the Definitions app |
---|---|---|
apps | optional, YAML supported App descriptor files, defining Apps. | |
| optional Command definitions used with Magnolia command management. | |
| optional, YAML supported Dialog definitions for content editing. | |
| optional, YAML supported Field definitions for Magnolia 5 UI fields. | |
mediaEditors | optional, YAML supported Media Editor definitions. | |
| optional, YAML supported | |
| 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. | |
| 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. | |
| optional, YAML supported URI mapping definitions that redirect an incoming request to the actual content location. |
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.
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:
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.
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
|