@Version("1.11.0")

Package com.adobe.cq.dam.cfm

Defines the basic API for creating and managing Content Fragments.

Main purpose of this API is to abstract the corresponding content structure and provide convenience methods to manage a fragment.

Elements

  • A content fragment is represented by an instance of ContentFragment.
  • Each fragment contains content elements. Elements carry semantically distinctive parts of the fragment (e.g. the title and content elements of a typical news article).
  • Each element can have multiple variations of its content. This can be used for creating longer or shorter versions of the text, depending on the context. For example, a shorter version may be provided for creating a Twitter-optimized version of the content.

Each content fragment must have at least one element, but can finally consist of multiple elements. Variations are completely optional.

Content (= text fragments) is managed both on the element and the variation level. This means: To access an element's text, first retrieve the element, then use the respective methods to access the text and its MIME type (note that the com.adobe.cq.dam.cfm.converter API provides means to get a standardized HTML representation of the fragment).

Basic usage

To create a ContentFragment from a Sling resource, simply adapt the resource to ContentFragment.

After adapting the resource, you can access and manipulate the fragment using the respective methods of the API.

Note that the API doesn't assume auto-commit. This means that you have to commit the org.apache.sling.api.resource.ResourceResolver explicitly after manipulating the fragment.

Concurrency

The API is not explicitly designed for sharing its objects between multiple thread, so the user has to take care of correct synchronization should the use case require shared access.

References

The com.adobe.cq.dam.cfm.converter API provides means to create an HTML representation for content that leverages other formats like plain text or Markdown. It is also used to convert formats back and forth.

The com.adobe.cq.dam.cfm.content API is leveraged for post-processing the content of a fragment instance, before it eventually gets rendered within a specific context. "Fragment instance" in this case means a single occurrence of the fragment in a page (for example).

Structured fragments

Version 1.1 of the API introduces typed data, extending the purely text-based fragments of version 1.0. Fragments based on typed data are called "structured fragments".

The content structure of both fragment types are different. On the API level, they are handled interchangeably: You don't need to explicitly care if you stay within the borders of the system, i.e. stick to the data types that a fragment exposes. To further lower the barrier, the class that is used for wrapping data provides some type conversation rules that allow to access text-based fragments in a typed way.

The changes in the API are mainly related to adding support for typed data to elements and variations. Also, some help with converting data (mainly required for text-based fragments) is provided.