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
Depending on your installation of Magnolia, the set of definition registries present in the system may vary. The table below outlines some of the common configuration items, the item’s purpose, and whether it is visible in the Definitions app.
Config item | Purpose | Visible | ||
---|---|---|---|---|
|
optional YAML supported; App descriptor files, defining Apps. |
✓ |
||
|
optional YAML supported; Block definitions.
|
✓ |
||
|
✓ |
|||
|
optional Command definitions used with Magnolia command management. |
✓ |
||
|
A Magnolia content type is a formal definition for a type of content in Magnolia including the properties the type may contain and its relationships to other types of content.
|
✓ |
||
|
optional YAML supported; Dashboard definitions for analytics dashboards. |
✓ |
||
|
optional YAML supported; Supplies the raw data for dashboards. |
✓ |
||
|
optional YAML supported; Dialog definitions for content editing. |
✓ |
||
|
optional YAML supported; Allows use of the E-commerce app. |
✓ |
||
|
optional YAML supported; Field definitions for Magnolia 5 UI fields. |
✓ |
||
|
optional YAML supported; GraphQL type definitions.
|
✓ |
||
|
optional YAML supported; Media Editor definitions. |
✓ |
||
|
optional YAML supported; Message view definitions. |
✓ |
||
|
optional YAML supported; Renderer definitions. Creating custom renderers for other templating languages such as Velocity is possible.
|
✓ |
||
|
optional YAML supported; Specifies REST clients that can be used together with the
|
✓ |
||
|
optional YAML supported; REST endpoint definitions. |
✓ |
||
|
optional; Search result suppliers are responsible for providing search results to the Find Bar’s search result area through the Periscope module. |
✓ |
||
|
A site definition contains site-wide configuration such as navigation, common page areas, and JavaScript that you want to load on every page. |
✓ |
||
|
optional YAML supported; Template definitions for pages, areas or components. |
✓ |
||
|
optional YAML supported; Themes for the site. A Theme is a collection of resource files that gives a site its visual identity through the use of colors and typography. A theme consists of cascading style sheets (CSS), JavaScript files and an imaging configuration that tells the Imaging module what to do with images for a particular page or component. |
✓ |
||
|
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. |
✓ |
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 info.magnolia.rendering.template.TemplateDefinition in info.magnolia.rendering.template.registry.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 info.magnolia.dirwatch.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 |
|
|
Command definition |
— |
|
Dialog definition |
|
|
Field type definition (Magnolia 5 UI) |
|
|
Media editor definition |
|
|
Message view definition |
|
|
Renderer definition |
|
|
REST endpoint definition |
|
|
Template definition |
|
|
Trait definition |
— |
|
Virtual URI mapping definition |
|
|