Using $ref for inline and linked content
Properties in content types can contain references to externally defined content types using the $ref keyword, allowing you to support a feature known as combining content.
Combining content has a number of advantages:
- You can reference externally defined content and display this inside the same content editing form. This is inline content.
- You can define complex content such as a carousel, where a carousel content item contains one or more carousel slides, each stored as separate content items. This is linked content.
For more information about the concepts behind combining content and when to use inline or linked content, expand the section below.
Combining content: concepts
There are two methods for combining content:
- Nested / Linked content, whereby the linked item is independent and may be shared by a number of assets that all link to it.
- Inline content, which forms part of the whole and is indivisible from it, thereby providing reuse of structure but no reuse of content.
Nested / Linked Content allows the user to create and add other content types to an existing content item; for example the user may wish to compile a carousel made up of several different image slides. This approach to linking otherwise independent content allows for re-use, by making the linked content available via the Content Library as an individual content item. One effect of this is that an update to the linked content will be reflected in all the content that links to it; e.g. all carousels that show a particular image slide will change if the image slide is updated. In technical terms, this is like linking objects "by reference" in an association arrangement.
Inline Content works by embedding one content type within another one by (the developer) embedding one schema within another one, which in technical terms is like linking the objects "by value" in an aggregation / composition arrangement. It is applicable to simple compositions where a particular set of fields and validation are required for inclusion in a particular content type but without the values being shared across multiple content objects.
Inline content never exists in its own right independent of the containing content, and so cannot be reused via the Content Library in the production view of Dynamic Content.
When to Use Each Kind of Included Content
When deciding between nested content and inline content, the things you should consider include:
Granularity: Do you merely want to break down a big unwieldy content schema into smaller parts for clarity, and to factor out potentially reusable definitions? This would be inlining.
Reuse: Do you also want the content items defined by these sub-schemas to be shared among multiple content items? This would be nesting or linking.
Ownership / Lifetime: Do the items defined by the sub-schemas somehow "belong" to the containing schema, such that they should cease to exist at the same time? This would be inlining.
In the context of the Content Authoring workflow, it is the developer who determines what schema structures get reused through inlining whereas it is the content editor who decides what content gets reused via nesting / linking.
On this page we'll include two examples of inline content, where we have defined a single piece of content into which content is combined from an external content type. Then we provide an example of linked content with a simple carousel including carousel slide content items.
Including a single item of content
Note that this will only allow the user to add a single item of content of the type defined in link.json. To add multiple items of content see the section below.
Including multiple items of content
To allow the user to add multiple items of content of an externally defined content type you need to store the content in an array.
In the example below, up to three content items of the type defined in roundel.json can be added to the content item. These content items are all added to the same form as shown in the image below.
With linked content, you refer to separate content items that are created and managed externally. In the carousel example, the carousel content item contains an array of carousel slide content items that are stored separately in the Content Library and can be shared between other carousel items.
In the example below, the carousel content type contains a
slides property. This contains an array of links to external content, in this example just the carouselslide content type. When the user interface encounters this definition, the user will be asked to choose to select an existing carousel slide or create a new one. The minItems and maxItems properties are used to set the minimum items that can be added to the carousel to 1 and the maximum to 6.
For more details, see the full Carousel example.
When specifying linked content, you can use either a
content-reference property type. See the content and media choosers page for more information.