Learn about using references in Content Fragments author-headless-references

The Story so Far story-so-far

At the beginning of the AEM Headless Content Author Journey the Introduction covered the basic concepts and terminology relevant to authoring for headless.

You have learned the basics of Headless CMS Authoring, with an introduction to authoring with AEMaaCS and in particular, authoring Content Fragments.

This article builds on these so you understand how to use references to author your own content for your AEM headless project.

Objective objective

What are references what-are-references

References are simply a mechanism for connecting your resources, be it other content, assets (as in images), or other fragments. Although very similar, there are some differences.

Some references have dedicated data-types (for example, Content References and Fragment References), whereas others are simply added as a reference within a text block (asset references and ad hoc references).

Content References content-references

Content References do just that - they let you reference any other content. This opens a browser that lets you select the content item.

Asset/Media References assets-media-references

Assets (for example, images or media) can be referenced within a Text block by using the Insert asset option. This opens a browser that lets you select the asset.

Fragment References fragment-references

Again Fragment References do just that - they let you reference another fragment. Why this is significant needs a bit more explanation.

For example, you might have the following Content Fragment Models defined:

Seems pretty straightforward, but a Company has both a CEO and Employees…and these are all people, each defined as a Person.

And a Person can have an Award (or maybe two).

And that’s just for starters. Depending on the complexity, an Award could be Company-specific, or a Company could have its main office in a specific City.

Representing these interrelationships can be achieved with Fragment References, as they are understood by both you (the author) and the headless applications.

As an author you’re not responsible for defining these relationships (that’s done by the Content Architect when creating the Content Fragment Model), but you need to know how to recognize and edit the references.

How to author nested fragments author-nested-fragment

Authoring Fragment References is fairly straightforward (though usually the field will not be labelled as Fragment Reference). You can either type in the reference directly, or (more likely) select the folder icon to open a browser that lets you navigate and select the fragment you need.

The definition of the Content Fragment Model controls:

How to navigate nested fragments navigate-nested-fragment

Using the Structure Tree tab of the Content Fragment Editor you can navigate through the fragments referenced by your fragment, and then through any references they may contain. Selecting a reference opens that fragment for editing.

Ad Hoc References adhoc-references

Ad hoc references can be added as a simple link within a block of text:

What’s Next whats-next

Now that you have learned about references and structure in Content Fragments, the next step is to Learn how about Metadata and Tagging. This will introduce and discuss how you can define metadata and tags for your Content Fragments.

Additional Resources additional-resources