Content Inheritance Basics in CrafterCMS

Content inheritance is the ability of the CMS to centrally manage content values.  Updating this content in one place automatically updates the value everywhere else.  This goes far beyond simple “shared components” in the sense that, as far as the system is concerned, the inherited values, in fact, belong to the content in question.  In general, with inherited content you may:

• Centrally define default values
• Override previously inherited values (from some other level of the graph)
• Delete or mute previously inherited values (from some other level of the graph)

Content inheritance is useful for a wide range of use cases including translation support, microsite management and common values (hotel count, employee count, CEO name, etc) that you want to use throughout the content but want to manage centrally.

Content Inheritance Basics

Content objects in CrafterCMS are essentially structured markup, XML by default, and house data authored via Crafter Studio by content authors. Content objects are typically structured as a tree which naturally suits the notion of inheriting from a parent (not to say that the inheritance mechanics are limited to that topology). Inheritance works as follows:

Assume we have two objects, one called Parent and one called Child and they’re set up as follows:

Parent: Below you’ll see a typical level descriptor which will be the parent of another object. You’ll note the level descriptor defines multiple elements that are common to everything at this level in the hierarchy and below it. This level descriptor defines a primary CSS file main.css, a common header component default-header.xml and a common footer component default-footer.xml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

    <?xml version="1.0" encoding="UTF-8"?>
    <component>
            <content-type>/component/level-descriptor</content-type>
            <display-template/>
            <merge-strategy>inherit-levels</merge-strategy>
            <objectGroupId>4123</objectGroupId>
            <objectId>41d1c0c5-bfc9-8fe8-2461-dc57a82b6cab</objectId>
            <file-name>crafter-level-descriptor.level.xml</file-name>
            <folder-name/>
            <cssGroup>
                    <item>
                            <key>/static-assets/css/main.css</key>
                            <value>/static-assets/css/main.css</value>
                            <fileType_s>css</fileType_s>
                    </item>
            </cssGroup>
            <jsGroup/>
            <createdDate>2/7/2016 19:40:03</createdDate>
            <lastModifiedDate>10/8/2016 19:58:30</lastModifiedDate>
            <defaultHeader>
                    <item>
                            <key>/site/components/components/header/default-header.xml</key>
                            <value>Default Header</value>
                            <include>/site/components/components/header/default-header.xml</include>
                            <disableFlattening>false</disableFlattening>
                    </item>
            </defaultHeader>
            <defaultFooter>
                    <item>
                            <key>/site/components/components/footer/default-footer.xml</key>
                            <value>Default Footer</value>
                            <include>/site/components/components/footer/default-footer.xml</include>
                            <disableFlattening>false</disableFlattening>
                    </item>
            </defaultFooter>
            <lastModifiedDate_dt>10/8/2016 19:58:30</lastModifiedDate_dt>
    </component>

Child: Below is the XML file of a page residing under the above level descriptor and is setup to inherit from it. You’ll note the definition of the merge-strategy as inherit-levels, this invokes the level-based inheritance mechanics that require CrafterCMS to look at current and higher levels for files named crafter-level-descriptor.level.xml (this is configurable). You’ll also note that this page doesn’t specify the CSS file/group of files to include, nor will it need to specify the header nor footer components.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    <?xml version="1.0" encoding="UTF-8"?>
    <page>
            <content-type>/page/one-col-parallax</content-type>
            <display-template>/templates/web/pages/one-col-parallax.ftl</display-template>
            <merge-strategy>inherit-levels</merge-strategy>
            <objectGroupId>9cef</objectGroupId>
            <objectId>001f0955-6da3-8b7a-4e6b-6b373139d0ba</objectId>
            <file-name>index.xml</file-name>
            <folder-name>child-page</folder-name>
            <internal-name>Child</internal-name>
            <navLabel>CHILD</navLabel>
            <title>Child Page</title>
            <headerOverlap>no-overlap</headerOverlap>
            <placeInNav>true</placeInNav>
            <orderDefault_f>12000</orderDefault_f>
            <description>This is the Child page.</description>
            <disabled>false</disabled>
            <createdDate>7/31/2016 16:52:39</createdDate>
            <lastModifiedDate>8/1/2016 18:55:09</lastModifiedDate>
            <body>
                    <h1>Hello World</h1>
            </body>
    </page>

CrafterCMS will invoke the inheritance mechanics implemented in the merge strategy inherit-levels to merge the page and the level descriptor and the merge strategy will pull in the elements defined in the level descriptor into the child page before handing the new model (XML) to the rendering system. This means that when the page renders, the model will automatically contain the meta-data defined in the parent level descriptor. In our example above, the page will automatically inherit the meta-data fields cssGroup, defaultHeader, and defaultFooter.

This mechanism allows you to define meta-data that flows down the information architecture of the site such that an entire site can have defaults and those defaults can be overwritten by sections individual page. Some examples of real-life use of inheritance:

• Site logo
• Global stylesheet and JS includes
• Global headers and footers
• Section meta-data (flows to all pages/subsections)

What we discussed thus far is a single inheritance strategy implementation, inherit-levels, the code to which is available here: InheritLevelsMergeStrategy.java. There are more inheritance strategies implemented out of the box with CrafterCMS and you can build your own to suit your needs.

Out of the Box Strategies