@Version(value="1.3.1") @Export

Package com.adobe.cq.dam.cfm

Defines the basic API for creating and managing Content Fragments.

See: Description

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 (see DataType.getTypeString() for the required data types.

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.

Package com.adobe.cq.dam.cfm Description

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.