Content Fragment Models in Adobe Experience Manager (AEM) as a Cloud Service define the structure for the content of your Content Fragments. These fragments can then be used for page authoring, or as a foundation for your headless content.
To use Content Fragment Models you:
Navigate to Tools, General, then open Content Fragment Models.
Navigate to the folder appropriate to your configuration, or subconfiguration.
Use Create to open the wizard.
If the use of Content Fragment models have not been enabled, the Create option will not be available.
Specify the Model Title.
You can also define various properties; for example, add Tags, a Description, select Enable model to enable the model if require and define the
Default Preview URL Pattern.
See Content Fragment Model - Properties for full details.
Use Create to save the empty model. A message indicates the success of the action, you can select Open to immediately edit the model, or Done to return to the console.
These properties are defined when you create a model, and can be edited later with the Properties option for the Content Fragment Model:
Model Title
Tags
Description
Enable model
Default Preview URL Pattern
The Content Fragment editor allows authors to Preview their content in an external frontend application. Once the Preview Service is configured, add the URL for the frontend application.
The preview URL should follow this pattern:
https://<preview_url>?param=${expression}
Available expressions are:
${contentFragment.path}
${contentFragment.model.path}
${contentFragment.model.name}
${contentFragment.variation}
${contentFragment.id}
Upload Image
The Content Fragment Model effectively defines the structure of the resulting Content Fragments using a selection of Data Types. Using the model editor you can add instances of the data types, then configure them to create the required fields:
Editing a model that is already used by existing Content Fragments can impact those dependent fragments.
Navigate to Tools, General, then open Content Fragment Models.
Navigate to the folder holding your Content Fragment model.
Open the required model for Edit; use either the quick action, or select the model and then the action from the toolbar.
Once open the model editor shows:
When a field is defined as Required, the Label indicated in the left pane is marked with an asterix (*).
To Add a Field
Drag a required data type to the required location for a field:
Once a field has been added to the model, the right panel shows the Properties that can be defined for that particular data type. Here you can define what is required for that field.
Many properties are self-explanatory, for additional details see Properties.
Typing a Field Label auto-completes the Property Name - if empty, and it can be manually updated afterwards.
When manually updating the property Property Name for a data type, names must contain only A-Z, a-z, 0-9 and underscore “_” as special character.
If models created in earlier versions of AEM contain illegal characters, remove or update those characters.
For example:
To Remove a Field
Select the required field, then click/tap the trash-can icon. You are asked to confirm the action.
Add all required fields, and define the related properties, as required. For example:
Select Save to persist the definition.
A selection of data types is available for defining your model:
Single line text
Multi line text
Whether the text area is Rich Text, Plain Text, or Markdown, is defined in the model by the property Default Type.
This format cannot be changed from the Content Fragment editor, but only from the Model.
Number
Boolean
Date and time
Enumeration
Tags
Content Reference
Fragment Reference
JSON Object
Tab Placeholder
This data type is purely used for formatting, it is ignored by the AEM GraphQL schema.
Many properties are self-explanatory, for certain properties additional details are below:
Property Name
When manually updating this property for a data type, names must contain only A-Z, a-z, 0-9 and underscore “_” as special character.
If models created in earlier versions of AEM contain illegal characters, please remove or update those characters.
Render As
The various options for realizing/rendering the field in a fragment. Often this allows you to define whether the author will see a single instance of the field, or will be allowed to create multiple instances.
Field Label
Entering a Field Label autogenerates a Property Name, which can then be manually updated if required.
Validation
Basic validation is available by mechanisms such as the Required property. Some data types have addition validation fields. See Validation for further details.
For the data type Multi line text it is possible to define the Default Type as either:
If not specified, the default value Rich Text is used for this field.
Changing the Default Type in a Content Fragment model will only take effect on an existing, related, Content Fragment after that fragment is opened in the editor and saved.
Unique
Content (for the specific field) must be unique across all Content Fragments created from the current model.
This is used to ensure that content authors cannot repeat content already added in another fragment of the same model.
For example, a Single line text field called Country
in the Content Fragment Model cannot have the value Japan
in two dependent Content Fragments. A warning is issued when the second instance is attempted.
Uniqueness is ensured per language root.
Variations can have the same unique value as variations of the same fragment, but not the same value as used in any variation of other fragments.
See Content Reference for more details about that specific data type and its properties.
See Fragment Reference (Nested Fragments) for more details about that specific data type and its properties.
Translatable
Checking the Translatable checkbox on a field in the Content Fragment Model editor will:
/content/dam/<sites-configuration>
, if not already present.<translatable>
property on the Content Fragment field to yes
, to allow GraphQL query filter for JSON output with only translatable content.Various data types now include the possibility to define validation requirements for when content is entered in the resulting fragment:
Content Fragments can form nested content, using either of the following data types:
Fragment Reference (Nested Fragments)
This method is of particular interest when you are using Headless Content Delivery using Content Fragments with GraphQL.
AEM has recurrence protection for:
Content References
This prevents the user from adding a reference to the current fragment, and may lead to an empty Fragment Reference picker dialog.
Fragment References in GraphQL
If you create a deep query that returns multiple Content Fragments referenced by each other, it returns null on the first occurrence.
The Content Reference allows you to render content from another source; for example, image, page or Experience Fragment.
In addition to standard properties you can specify:
The Root Path, which specifies where to store any referenced content
This is mandatory if you want to directly upload and reference images in this field when using the Content Fragment editor.
See Reference Images for further details.
The content types that can be referenced
These must include Image if you want to directly upload and reference images in this field when using the Content Fragment editor.
See Reference Images for further details.
Limitations for file sizes
If an image is referenced:
The Fragment Reference references one, or more, Content Fragments. This feature is of particular interest when retrieving content for use in your app, as it allows you to retrieve structured data with multiple layers.
For example:
type EmployeeModel {
name: String
firstName: String
company: CompanyModel
}
type CompanyModel {
name: String
street: String
city: String
}
Fragment References are of particular interest for Headless Content Delivery using Content Fragments with GraphQL.
In addition to standard properties you can define:
Render As:
multifield - the fragment author can create multiple, individual, references
fragmentreference - allows the fragment author to select a single reference to a fragment
Model Type
Multiple models can be selected. When adding references to a Content Fragment, any referenced fragments must have been created using these models.
Root Path
This specifies a root path for any fragments referenced.
Allow Fragment Creation
This allows the fragment author to create a new fragment based on the appropriate model.
A recurrence protection mechanism is in place. It prohibits the user from selecting the current Content Fragment in the Fragment Reference, and may lead to an empty Fragment Reference picker dialog.
There is also recurrence protection for Fragment References in GraphQL. If you create a deep query across two Content Fragments that reference each other, it returns null.
You can either Enable or Disable your Content Fragment Models, for full control over their use.
Once a model has been created it must be enabled so that it:
To enable a Model that is flagged as either:
You use the Enable option from either:
A model can also be disabled so that:
To disable a Model that is flagged as Enabled, you use the Disable option from either:
To implement content governance, you can configure Policies on Assets folder to control which Content Fragment Models are allowed for Fragment creation in that folder.
The mechanism is similar to allowing page templates for a page, and its children, in advanced properties of a page.
To configure the Policies for Allowed Content Fragment Models:
Navigate and open Properties for the required Assets folder.
Open the Policies tab, where you can configure:
Inherited from <folder>
Policies are automatically inherited when creating new child folders; the policy can be reconfigured (and the inheritance broken) if subfolders need to allow models different to the parent folder.
Allowed Content Fragment Models by Path
Multiple models can be allowed.
Allowed Content Fragment Models by Tag
Multiple models can be allowed.
Save any changes.
The Content Fragment Models allowed for a folder are resolved as follows:
Deleting a Content Fragment model can impact dependent fragments.
To delete a Content Fragment model:
Navigate to Tools, General, then open Content Fragment Models.
Navigate to the folder holding your Content Fragment model.
Select your model, followed by Delete from the toolbar.
If the model is referenced a warning is given, so that you can take appropriate action.
Content Fragment Models need to be published when/before any dependent Content Fragments are published.
To publish a Content Fragment model:
Navigate to Tools, General, then open Content Fragment Models.
Navigate to the folder holding your Content Fragment model.
Select your model, followed by Publish from the toolbar.
The published status is shown in the console.
If you publish a Content Fragment for which the model has not yet been published, a selection list will indicate this and the model will be published with the fragment.
Content Fragment Models can be unpublished if they are not referenced by any fragments.
To unpublish a Content Fragment Model:
Navigate to Tools, General, then open Content Fragment Models.
Navigate to the folder holding your Content Fragment Model.
Select your model, followed by Unpublish from the toolbar.
The published status is indicated in the console.
If you try to unpublish a model that is currently used by one or more fragments, then an error warning is shown. For example:
The message suggests that you check the References panel to investigate further:
This feature provides governance for Content Fragment Models that have been published.
Content Fragment Models determine the schema for GraphQL queries in AEM.
AEM GraphQL schemas are created as soon as a Content Fragment Model is created, and they can exist on both author and publish environments.
Schemas on publish are the most critical as they provide the foundation for live delivery of Content Fragment content in JSON format.
Problems can occur when Content Fragment Models are modified, or in other words edited. This means that the schema changes, which in turn may affect existing GraphQL queries.
Adding new fields to a Content Fragment Model should (typically) not have any detrimental effects. However, modifying existing data fields (for example, their name) or deleting field definitions, will break existing GraphQL queries when they are requesting these fields.
To make users aware of the risks when editing models that are already used for live content delivery - in other words, models that have been published).
Also, to avoid unintended changes.
Either of these criteria might break queries if the modified models are republished.
To address these issues, Content Fragment Models are locked into a READ-ONLY mode on author - as soon as they have been published. This status is indicated by Locked:
When the model is Locked (in READ-ONLY mode), you can see the contents and structure of models but you cannot edit them.
You can manage Locked models from either the console, or the model editor:
Console
From the console, you can manage the READ-ONLY mode with the Unlock and Lock actions in the toolbar:
You can Unlock a model to enable edits.
If you select Unlock a warning is shown, and you must confirm the Unlock action:
You can then open the model for editing.
You can also Lock the model afterwards.
Republishing the model immediately returns it to Locked (READ-ONLY) mode.
Model Editor
When you open a model that is locked you will be warned, and presented with three actions: Cancel, View Read Only, Edit:
If you select View Read Only, you can see the content and structure of the model:
If you select Edit, you can edit and save your updates:
There may still a warning at the top, but that is when the model is already in use by existing Content Fragments.
Cancel returns you to the console.