Interface ContentFragment
-
- All Superinterfaces:
Adaptable
,Versionable
public interface ContentFragment extends Adaptable, Versionable
Implementations of this interface allow to access content fragments through a stable API, independently from the actual content structure.
Content fragments consist of one or more elements, which in turn may contain variations of their content - for example, a short variation for publishing the fragment on Twitter or maybe an on-the-fly variation when the fragment is reused on a different page than the original one.
Each variation can be synchronized with the original element content, which in the simplest way means that the current content of the element is copied to the variation. Depending on the implementation, there might be more sophisticated ways that change the original content in some way.
Additionally, each content fragment has a collection of associated content, which may contain references to assets, collections or other content fragments.
Each content fragment has a set of meta data, which can be used for determining associated content.
Usage pattern: To obtain a ContentFragment, simply adapt a
Resource
toContentFragment.class
. This means that each implementing module has to provide aAdapterFactory
that adaptsResources
toContentFragment
.Transactional behavior: The caller is responsible for committing the respective
ResourceResolver
after calling one or more methods that change a content fragment unless specified otherwise.In older versions of the API, one element (the "main" or "master" element) was considered to define the content fragment. This means, it had a special position within the content fragment and usually contained the "most important" or "most distinctive" content. With the advent of structured content fragments this is not the case anymore.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addAssociatedContent(Resource content)
Adds the providedResource
as associated content.ContentElement
createElement(ElementTemplate template)
Creates a new element from the specified template.VariationTemplate
createVariation(java.lang.String name, java.lang.String title, java.lang.String description)
Creates a new variation.java.util.Iterator<Resource>
getAssociatedContent()
Gets an iterator on associated content.java.lang.String
getDescription()
Gets the description of the content element.ContentElement
getElement(java.lang.String elementName)
Gets the content element of the specified name.java.util.Iterator<ContentElement>
getElements()
Gets an iterator on the templates of predefined content elements of the fragment.@Nullable java.util.Calendar
getLastModifiedDate()
Returns the date the content fragment was last modified.@NotNull java.util.Calendar
getLastModifiedDeep()
Returns the most recent modified date of this content fragment or any (recursively-referenced) fragment it references.java.util.Map<java.lang.String,java.lang.Object>
getMetaData()
Gets a map of the fragment's meta data.java.lang.String
getName()
Gets the (technical) name of the content fragment.@NotNull Tag[]
getTags()
Gets all the tags associated with this fragment as an array.FragmentTemplate
getTemplate()
Gets the fragment template assigned to this content element.java.lang.String
getTitle()
Gets the (human-readable) title of the content fragment.@NotNull Tag[]
getVariationTags(@NotNull java.lang.String variationName)
Gets all the tags for the passed variation name as an array.boolean
hasElement(java.lang.String elementName)
Determines if the content fragment has an element of the specified name.java.util.Iterator<VariationDef>
listAllVariations()
Gets an iterator on all available variations that are available for the entire fragment.void
removeAssociatedContent(Resource content)
Removes the providedResource
as associated content.void
removeVariation(java.lang.String name)
Removes the specified global variation from the fragment.void
setDescription(java.lang.String description)
Sets the description of the content fragment.void
setMetaData(java.lang.String name, java.lang.Object value)
Sets a single meta data property.void
setTags(@NotNull Tag[] tags)
Sets the passed tags on the fragment.void
setTitle(java.lang.String title)
Sets the (human-readable) title of the content fragment.void
setVariationTags(@NotNull Tag[] tags, @NotNull java.lang.String variationName)
Sets the passed tags on the variation of the fragment.-
Methods inherited from interface com.adobe.cq.dam.cfm.Versionable
createVersion, getVersionedContent, listVersions
-
-
-
-
Method Detail
-
getElements
java.util.Iterator<ContentElement> getElements()
Gets an iterator on the templates of predefined content elements of the fragment.- Returns:
- The iterator on the content elements
-
hasElement
boolean hasElement(java.lang.String elementName)
Determines if the content fragment has an element of the specified name.- Parameters:
elementName
- The name of the element to check- Returns:
- True if there is an element of the provided name
-
createElement
ContentElement createElement(ElementTemplate template) throws ContentFragmentException
Creates a new element from the specified template.- Parameters:
template
- The element template- Returns:
- The newly created content element
- Throws:
ContentFragmentException
- if the change could not be persisted
-
getElement
ContentElement getElement(java.lang.String elementName)
Gets the content element of the specified name.- Parameters:
elementName
- The name of the element;null
or empty string for the "main" or "master" element- Returns:
- The element;
null
-
getName
java.lang.String getName()
Gets the (technical) name of the content fragment.- Returns:
- The name of the content fragment
-
getTitle
java.lang.String getTitle()
Gets the (human-readable) title of the content fragment.- Returns:
- The title of the content fragment
-
setTitle
void setTitle(java.lang.String title) throws ContentFragmentException
Sets the (human-readable) title of the content fragment.- Parameters:
title
- The new title- Throws:
ContentFragmentException
- if the change could not be persisted
-
getDescription
java.lang.String getDescription()
Gets the description of the content element.- Returns:
- The description of the content element
-
setDescription
void setDescription(java.lang.String description) throws ContentFragmentException
Sets the description of the content fragment.- Parameters:
description
- The new description- Throws:
ContentFragmentException
- if the change could not be persisted
-
getMetaData
java.util.Map<java.lang.String,java.lang.Object> getMetaData()
Gets a map of the fragment's meta data.- Returns:
- The map of meta data
-
setMetaData
void setMetaData(java.lang.String name, java.lang.Object value) throws ContentFragmentException
Sets a single meta data property.As meta data is not limited to the meta data provided through the template, this method is generic.
- Parameters:
name
- Name of the meta data propertyvalue
- Value of the meta data property- Throws:
ContentFragmentException
- if the property could not be set/persisted
-
listAllVariations
java.util.Iterator<VariationDef> listAllVariations()
Gets an iterator on all available variations that are available for the entire fragment.This is used to get a "plain view" on variations, as not all elements may have all variations.
The list does not include the "master" or base variation!
- Returns:
- Iterator on available variations
-
getTemplate
FragmentTemplate getTemplate()
Gets the fragment template assigned to this content element.- Returns:
- The fragment template
-
createVariation
VariationTemplate createVariation(java.lang.String name, java.lang.String title, java.lang.String description) throws ContentFragmentException
Creates a new variation.The variation is added to all elements of the fragment.
The content of each fragment must be initialized with a copy of the element content.
Note that the specified (technical) name might not be the final name. In some cases - like there is already a variation with the specified name - the implementation may change it. To determine the final name of the variation, use the
getName
method of the return value.Also note that you can pass a
null
value for either thename
or thetitle
parameter, but not both.- Parameters:
name
- The (technical) name of the variation to be created;null
if the name should be derived from the titletitle
- The (human-readable) title of the variation to be created; may benull
if an explicit (technical) name is specifieddescription
- The (optional) description of the variation- Returns:
- The intermediate template that represents the newly created variation
- Throws:
ContentFragmentException
- if the change could not be persisted
-
removeVariation
void removeVariation(java.lang.String name) throws ContentFragmentException
Removes the specified global variation from the fragment.
- Parameters:
name
- The name of the global variation to remove- Throws:
ContentFragmentException
- if the variation could not be removed properly or there is no such variation available
-
getAssociatedContent
java.util.Iterator<Resource> getAssociatedContent()
Gets an iterator on associated content.- Returns:
- Iterator on associated content
-
addAssociatedContent
void addAssociatedContent(Resource content) throws ContentFragmentException
Adds the providedResource
as associated content.- Parameters:
content
- The new associated content- Throws:
ContentFragmentException
- if the resource could not be added
-
removeAssociatedContent
void removeAssociatedContent(Resource content) throws ContentFragmentException
Removes the providedResource
as associated content.- Parameters:
content
- The associated content to remove- Throws:
ContentFragmentException
- if the resource could not be removed
-
getLastModifiedDate
@Nullable @Nullable java.util.Calendar getLastModifiedDate()
Returns the date the content fragment was last modified.- Returns:
- the last modified date or
null
if not available yet
-
getLastModifiedDeep
@NotNull @NotNull java.util.Calendar getLastModifiedDeep() throws ContentFragmentException
Returns the most recent modified date of this content fragment or any (recursively-referenced) fragment it references.- Returns:
- the last recursive modification date or creation date if none available
- Throws:
ContentFragmentException
- if the last recursive modification date could not be determined correctly
-
setTags
void setTags(@NotNull @NotNull Tag[] tags) throws ContentFragmentException
Sets the passed tags on the fragment. This will delete all existing tags for the fragment and replace them with the passed ones. For deleting all tags for the fragment use an empty array.- Parameters:
tags
- The tags to be set on the fragment- Throws:
ContentFragmentException
- if the tags could not be set/persisted
-
getTags
@NotNull @NotNull Tag[] getTags() throws ContentFragmentException
Gets all the tags associated with this fragment as an array. If no tags are available an empty array is returned.- Returns:
- An array with the existing tags or an empty array if no tags exist
- Throws:
ContentFragmentException
- if the tags could not be read
-
setVariationTags
void setVariationTags(@NotNull @NotNull Tag[] tags, @NotNull @NotNull java.lang.String variationName) throws ContentFragmentException
Sets the passed tags on the variation of the fragment. This will delete all existing tags for that variation and replace them with the passed ones. For deleting all tags for that variation use an empty array.- Parameters:
tags
- The tags to be set on the fragmentvariationName
- The name of the variation- Throws:
ContentFragmentException
- if the tags could not be set/persisted or if there is no such variation
-
getVariationTags
@NotNull @NotNull Tag[] getVariationTags(@NotNull @NotNull java.lang.String variationName) throws ContentFragmentException
Gets all the tags for the passed variation name as an array. If no tags are available an empty array is returned.- Parameters:
variationName
- The name of the variation- Returns:
- An array with the existing tags or an empty array if no tags exist
- Throws:
ContentFragmentException
- if there is no such variation or if the tags could not be read
-
-