Page tree
Skip to end of metadata
Go to start of metadata

Magnolia allows to reuse configuration items with JCR and with YAML.

include mechanism in YAML files

Instead of adding a list item or a value of a map entry you can include a file.

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/dialogs/common/categorization-field.yaml
# an include within a map, here adding a tab
actions: !include /documentation-examples-templates/dialogs/common/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

Path conventions:

  • Absolute path starting with /<module-name>. (This directory within a Maven-based module would be src/main/resources/<module-name>. See Module structure).
  • Same kind of definitions only. The file which includes and the file to be included must be of the same type.
    • (tick) file /my-module/dialogs/mydialog.yaml can include /my-module/dialogs/common-actions.yaml 
    • (tick) file /my-module/dialogs/mydialog.yaml can include /mte/dialogs/default-actions.yaml 
    • (error) file /my-module/dialogs/mydialog.yaml cannot include /my-module/apps/actions.yaml 

extends mechanism in JCR node based configuration

You 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 travelsite definition.

Node nameValue

 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.

Example: Generic tabs in dialogs

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 nameValue

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

Example: Extending JCR node based template definitions

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 nameValue

 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