Learn about using references in Content Fragments

The 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

• Audience: Advanced

• Objective: Introduce the use of references for Headless CMS Authoring. What sorts of references are available, and what are their purposes:

  • Content References
  • Asset/Media References
  • Fragment References
  • Ad hoc references from within a text block

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 do just that - they allow you to reference any other content. This will open a browser that allows you to select the content item.

Asset/Media References

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

Fragment References

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

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

• City
• Company
• Person
• Awards

Seems pretty straightforward, but of course 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).

• My Company - Company
  • CEO - Person
  • Employee(s) - Person
    • Personal Award(s) - Award

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

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 allows you to navigate and select the fragment you need.

The definition of the Content Fragment Model controls:

• whether you can select to add multiple references
• the model types of Content Fragments that you can select; the Content Fragment Model defines the fragment models allowed for the reference, so AEM only presents fragments based on those models.

How to navigate nested fragments

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

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

What’s 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

• Working with Content Fragments

  • Managing Content Fragments

    • Apply the Configuration to your Assets Folder

    • Creating a Content Fragment

  • Variations - Authoring Content Fragments

  • Content Fragment Models

    • Content Fragment Models - Data Types

    • Content Fragment Models - Properties

• Getting Started Guides

  • Creating an Assets Folder - Headless Setup

• AEM Headless Content Architect Journey

• AEM Headless Translation Journey