Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
Magnolia allows to reuse configuration items with JCR and with YAML.
include
mechanism in YAML filesUse the Magnolia !include
directive to add a reusable YAML chunk. Include a fragment on a sub-level of your definition. Reference the file you include by its resource path starting with /<module-name>/
.
form: label: Example page properties tabs: - name: tabText label: Texts and categories fields: - name: title class: info.magnolia.ui.form.field.definition.TextFieldDefinition label: Title and categories i18n: true # an include within a list, here adding a field - !include /documentation-examples-templates/includes/categorization-field.yaml # an include within a map, here adding a tab actions: !include /documentation-examples-templates/includes/default-actions-block.yaml
The !include
directive is Magnolia specific. The !
is a special character in YAML for a non-specific tag, see http://www.yaml.org/refcard.html.
If you have created the includable fragment after the creation of the file which includes it, save the latter again to force the YAML parser to properly register the definition. /<module-name>/includes
is the recommended directory for YAML fragment files. Avoid adding the YAML fragment files into the following directories: apps
, blocks
, decorations
, dialogs
, i18n
, messageViews
, renderers
, templates
and virtualUriMappings
.
With Magnolia 5.5.6+, the
!include
directive has been extended to provide more functionalities. (See YAML inherit and include).
extends
mechanism in JCR node based configurationYou can extend a configuration by defining an extends
property and setting its value to the source configuration you want it to inherit. The target configuration inherits everything from the source and adds its own exceptions. This can save time and effort as you only need to define exceptions explicitly. The mechanism is only available in the config
repository. In the example below, the sportstation
site definition extends the travel
site definition.
Node name | Value |
---|---|
fallback |
|
travel |
|
sportstation |
|
mappings |
|
theme |
|
templates |
|
domain |
|
i18n |
|
extends | ../travel |
The definition inherits all configuration from the default
configuration and adds its own domains, internationalization and URI-to-repository mappings. The extends
property can point to the source configuration with an absolute or relative path.
You can use Magnolia's extends mechanism to minimize configuration. For example, if you have a number of components that include an image, you can configure a generic image tab and use it by extension in all relevant dialogs.
This example configuration shows the use of a generic imageTab
in a TextImage
dialog.
Node name | Value |
---|---|
<my-module> | |
dialogs | |
components | |
textImage | |
actions | |
form | |
tabs | |
textTab | |
imageTab | |
extends | /modules/my-modules/dialogs/components/generic/imageTab |
generic | |
imageTab | |
fields | |
image | |
position | |
size | |
title | |
altText | |
description |
Property:
extends | optional Path to the configuration that is extended. |
You can configure one template in full and create as many extensions with slight differences as you like. The mechanism is used to minimize configuration. Only changes, exceptions and additions are configured in the extended configuration. All other configurations are taken from the original configuration.
The extends
property has two possible values:
</path to extended template>
: Used to reference the template that is extended.override
: Used to override a portion or part of the configuration that is extended.In the example below page-template-2
extends page-template-1
. The extended template uses the full configuration of the template it extends except the configurations in the extended template.
Node name | Value |
---|---|
page-template-1 | |
page-template-2 | |
areas | |
content | |
availableComponents | |
news-component-1 | |
news-component-2 | |
extends | override |
extends | /modules/my-module/templates/pages/page-template-1 |
subType | news |
title | Extended Template |