Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.

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

Inheritable components are added on a parent page and are automatically displayed on child pages. This is an example of content reuse that saves time and effort. With inheritance you can define components that must be displayed on child pages. This helps display consistent information across the site.

An editor can add an inheritable component at the top of a site section, for example. The component will be displayed on each child page in that section. An inheritable component is only editable on the parent page. There are no component toolbars on the child pages. Inheritance is completely configurable and requires no coding. Promos are a common example of inheritable components. They are used to promote special events or deals. Since promotional content changes often, you want to edit them once and have the change reflected on the whole site.

Configuring inheritance

Inheritance is enabled at area level, as opposed to component level, and is available in all areas. It is configured in the area definition and there are different component behavior options.

In the demo websites, it is enabled in footer, metaNavigation, promos, extras and sectionHeader areas by default.

Inheritance is typically configured in the prototype template in Templating Kit > Site Definitions /default/templates/prototype/area/<area name>. This sets behavior for all configured sites. We use this option in the examples below. It is also possible to configure inheritance on a site and template level by adapting the examples:

  • Site level: Configure inheritance in the specific site definition in Site Definitions.
  • Template level: Configure inheritance in the template definition in Template Definitions.

Enabling inheritance

Inheritance is configured in the areas/<area name> node. The boolean enabled property enables or disables inheritance for an area. Set the value to true or false.

The  ConfiguredInheritance Java class allows for three alternative values for the components property: all, filtered and none.

  • none, no components are inheritable. This has the same effect as disabling inheritance by setting the enabled property to false.
  • filtered means components added in the area cascade only if the Show in subpage box is checked in the component dialog.

All components

When the components node is set to all, all components in the area are automatically inherited on child pages. The footer area and metaNavigation subarea are examples of this behavior in the demo sites. In the template prototype the /<area name>/editible property is set to false making the components non-editable by default. This setting is reversed on the stkHome template. 

For example, the link components in the metaNavigation area can only be created and edited on the Home page. They are displayed on all sub pages but component toolbars are not available.

Filtered components

When the components node is set to filtered, making a component inherited is an editorial decision. The extras1 area is an example of this behavior.

When an editor checks the Show in subpage checkbox in the component dialog, an inheritable property is created on the component content node and its value is set to true. This property is the trigger for the filter. Only nodes with the property set to true are inherited to child pages.

To use this option, add the Show in subpage checkbox in the component dialog. It is a generic inheritable field which you can add to any dialog definition using the extends property. The screenshot below shows both the generic inheritable field definition and its inclusion in the stkExtrasInternalPage dialog definition through extends.

This what an inherited component looks like on a child page. In the Extras area, Articles is an inherited component. You can tell this because it does not have a toolbar. The History component below it has a toolbar because it is not inherited.

You can view the component properties in Tools > JCR Browser (Website). Note the inheritable=true property in the component node.

Example: Configuring inheritance in base area

The base area is near the bottom of the page, above the footer. It can contain optional components that use the full width of the page such as a tag cloud or a carousel.

By default, inheritance is not available in the base area. Here is how to enable it.

Enabling inheritance in the site definition

In Templating Kit > Site Definitions default/templates/prototype/areas/base:

  1. Add a new content node inheritance.
  2. Add a data node enabled and set the value to true.
  3. Add another data node components and set the value to all to inherit all components or filtered to inherit filtered components.

Adding the Show in subpage checkbox to dialogs

If the components node is set to filtered, add the inheritable field to the component dialogs. There are two components that editors can add in the base area by default: stkTeaserCarousel and catCloudWide, see the /areas/base/availableComponents node in the screenshot above. You can add the field to either component dialog, making one inheritable and the other not, or both.

The catCloudWide component is part of the Categorization module. The component uses the catCloud dialog configured at Configuration > /modules/categorization/dialogs/catCloud.

To add the checkbox:

  1. Under tabMain, add a new content node inheritable.
  2. Under inheritable, add a data node extends and set the value to /modules/standard-templating-kit/dialogs/generic/controls/inheritable. You are extending the generic Show in subpage checkbox control.

The base area is not the only place where editors can add the stkTeaserCarousel component. The component is also available in the main area on the stkSection template. When you add the Show in subpage checkbox control in the component dialog, editors will also see it when adding the component to the main area. Since inheritance is only configured in base this is not intuitive. To work around this issue, you can add a warning in the checkbox control using the description property, saying that the checkbox is only applicable to base area. Alternatively, you can configure separate components and dialogs for each area. For more information about configuring dialog definitions and assigning them to components see Dialogs.

Nested components

The stkTeaserCarousel component is a container for stkTeaserCarouselItem components. The inheritable dialog control needs to be added to both the parent carousel and the item. If only added to the parent component, the items will cascade on child pages as expected, but will remain editable on all pages.

Add the control to the stkTeaserCarousel and stkTeaserCarouselItem dialogs in the way described above. Both dialogs are configured in Templating Kit > Dialog Definitions /components/teasers.


Testing the result

To test, add a component in the base area on any parent page. If the components node is set to filtered in your configuration, check the Show in subpage checkbox in the component dialog. Verify that the component is inherited to child pages. Verify also that the component does not have a toolbar on the child pages.

Java classes

Classes that make inheritance possible are:

  • AreaElement renders an area and sets the sInherit() method.
  • DefaultInheritanceContentDecorator provides a configurable inheritance model. Options include enabling inheritance completely or selectively based on the properties. The inheritance source is the node hierarchy. All nodes of node type mgnl:content qualify as anchor nodes. The destination node uses the nearest parent anchor node with the same sub path. For example, destination node page1/page2/main uses anchor node page1/main, if it exists. 
  • InheritanceConfiguration provides the inheritance configuration that allows for separate configuration of properties and components. Can also control if specific components are included, and their final order.
  • ConfiguredInheritance defines inheritance behavior and allows for enabling of inheritance.