Components for Content Fragments

You are reading the AEM 6.3 version of Components for Content Fragments.
This documentation is also available for the following versions:  AEM 6.2 

Components for Fragment Authoring

Caution

It is not recommended to extend or change the actual components as they are still subject to change.

Components for Page Authoring

Adobe Experience Manager (AEM) content fragments are created and managed as page-independent assets. They allow you to create channel-neutral content, together with (possibly channel-specific) variations. You can then use these fragments, and their variations, when authoring your content pages. You can also use an existing content fragment asset by dragging it from the asset browser to the page (as for other asset based components, such as the foundation component Image). The out-of-the-box content fragment component displays only one element of the referenced content fragment. Using the component dialog you can define the element, variation and range of fragment paragraphs that you want to display on the page. 

Note

The Content Fragment component was introduced in AEM 6.2 as an enhanced version of the Article component, which has been deprecated.

Note

Content Fragments are not supported in the classic UI.

Definition

The Content Fragment component is used to hold a reference to a content fragment asset (effectively enhanced text assets). The resource type for the content fragment is:

dam/cfm/components/contentfragment/contentfragment

The reference is defined in the property:

fileReference

Only the editor of the touch-enabled UI fully supports content fragment components, which includes the client library:

cq.authoring.editor.plugin.cfm

This library adds features, specific to content fragments, to the editor. For example, support for the ability to add and configure content fragments on the page, ability to search for content fragment assets in the asset browser, and for associated content in the side panel are available.

In-Between Content

The Content Fragment component allows you to drop additional components in-between the different paragraphs of the displayed element. Basically, the element displayed is composed of different paragraphs (each paragraph is marked by a carriage return). Between each of those paragraphs, you can insert content using other components.

From a technical viewpoint, each paragraph of the displayed element lives in its own parsys, and each component that you add in-between the paragraphs will be (under the hood) inserted into the parsys.

In other words, if the instance of the content fragment component is composed of three paragraphs, then the component will have three different parsys in the repository. All of the in-between content that is added to the content fragment will actually be located inside these parsys.

In the repository the in-between content is stored relative to its position inside the overall paragraph structure, i.e. it is not attached to the actual paragraph content.

To illustrate this, let us consider that we have:

  • An instance of a content fragment composed of three paragraphs
  • And that some content has already been inserted after the second paragraph
    • This means that the content will be stored in the second parsys.

Basically, if the paragraph structure of this instance changes (by changing the variation, element, or range of paragraphs displayed), it could affect the in-between content displayed when the content fragment content:

  • Is edited and another paragraph is added before the second paragraph:
    • The in-between content will be displayed after the newly created paragraph (the second parsys now holds the newly created paragraph).
  • Is edited and the second paragraph is removed:
    • The in-between content will be displayed after the paragraph that was previously the third (the second parsys now holds the previous third paragraph).
  • Is configured so that only the first paragraph is shown:
    • The in-between content will not be displayed (the second parsys is not rendered anymore due to the new configuration).

Customizing the Content Fragment Component

To use the out-of-the-box content fragment component as a blueprint for extension you should respect the following contract:

  • Reuse the HTL rendering script and its associated POJO to see how the in-between content feature is implemented.
  • Reuse the content fragment node: cq:editConfig
    • The afterinsert/afteredit/afterdelete listeners are used to trigger JS events. These events will be handled in the cq.authoring.editor.plugin.cfm client library to display the associated content in the side panel.
    • The cq:dropTargets are configured to support dragging content fragment assets.
    • cq:inplaceEditing is configured to support authoring of a content fragment in the page editor. The fragment in-place editor is defined in the cq.authoring.editor.plugin.cfm client library and allows a quick link to open the current element/variation in the fragment editor.

Asset Rewriting Before Rendering

Content Fragment Management uses an internal rendering process to generate the final HTML output for a page. This is used internally by the Content Fragment component, but also by the background process that updates referenced fragments on referencing pages.

Internally, the Sling Rewriter is used for that rendering. The respective configuration is found at /libs/dam/config/rewriter/cfm and can be adjusted if required. See the Apache Sling Rewriter for more information.

The out-of-the-box configuration uses the following transformers:

  • transformer-cfm-payloadfilter - for retrieving the body part (<body>...</body>) of the fragment's HTML only
  • transformer-cfm-parfilter - filters out unwanted paragraphs if a paragraph range is specified (as can be done with the Content Fragment component)
  • transformer-cfm-assetprocessor - is used internally for retrieving a list of the assets that are embedded in the fragment

The rendering process is exposed through com.adobe.cq.dam.cfm.content.FragmentRenderService and can be leveraged (for example) by custom components if required.

Any questions?

Have a question about this or any other AEM topic? Ask our Community.
Learn more about AEM topics on our help hub.
Was this helpful?

By submitting your feedback, you accept the Adobe Terms of Use.

Thank you for submitting your feedback.