@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.
-
Interface Summary Interface Description CollectionHelper Implementors provide easier access to DAM collections for managing the associated content of a content fragment.ContentElement Implementations of this interface allow accessing elements of a content fragment in a way agnostic to the underlying data structures.ContentFragment Implementations of this interface allow to access content fragments through a stable API, independently from the actual content structure.ContentFragmentManager Implementations of this interface provide means to manage content fragments.ContentVariation Implementations of this interface allow to access a variation of a content element through a stable API, agnostic to the underlying content structure.DataType Represents a data type for structured content provided by a Content Fragment.ElementTemplate Implementations of this interface allow to access an element template through a well-defined API, without needing to care about the underlying content structure.FragmentData Represents a piece of content (or data) provided by a content fragment.FragmentTemplate Implementations of this interface allow to access the fragment template in a standardized way, independently of the actual content structure.MetaDataDefinition Implementations of this class provide access to the meta data definition of a template.MetaDataProperty Implementations of this class represent a single meta data definition.VariationDef Implementors provide some essential definitions of a variation.VariationTemplate Implementations of this interface allow accessing a variation template in a standardized way, without requiring knowledge about the underlying content structure.Versionable Implementations of this interface provide means to version their content.VersionDef Represents a version of a content item (like the entire fragment, an element or a variation of it).VersionedContent Represents the content of a specific version of a content item (be it the element master or a variation of it). -
Class Summary Class Description BasicDataType Defines the type string (seeDataType.getTypeString()
for the required data types.SemanticDataType This class defines the OOTB semantic types provided by Content Fragments. -
Enum Summary Enum Description SyncStatus Enumeration that defines the synchronization state of a "slave" variation against the respective element master. -
Exception Summary Exception Description ContentFragmentException This class represents a generic exception in handling content fragments.