Package com.adobe.cq.dam.cfm

Interface ContentFragment

All Superinterfaces:
Adaptable, Versionable<ContentFragment>
public interface ContentFragment extends Adaptable, Versionable<ContentFragment>

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 to ContentFragment.class. This means that each implementing module has to provide a AdapterFactory that adapts Resources to ContentFragment.

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 Details

    • getElements

      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(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(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

      String getName()
      Gets the (technical) name of the content fragment.
      Returns:
      The name of the content fragment

    • getTitle

      String getTitle()
      Gets the (human-readable) title of the content fragment.
      Returns:
      The title of the content fragment

    • setTitle

      void setTitle(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

      String getDescription()
      Gets the description of the content element.
      Returns:
      The description of the content element

    • setDescription

      void setDescription(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

      Map<String,Object> getMetaData()
      Gets a map of the fragment's meta data.
      Returns:
      The map of meta data

    • setMetaData

      void setMetaData(String name, 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 property
      value - Value of the meta data property
      Throws:
      ContentFragmentException - if the property could not be set/persisted

    • listAllVariations

      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(String name, String title, 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 the name or the title parameter, but not both.

      Parameters:
      name - The (technical) name of the variation to be created; null if the name should be derived from the title
      title - The (human-readable) title of the variation to be created; may be null if an explicit (technical) name is specified
      description - 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(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

      Iterator<Resource> getAssociatedContent()
      Gets an iterator on associated content.
      Returns:
      Iterator on associated content

    • addAssociatedContent

      void addAssociatedContent(Resource content) throws ContentFragmentException
      Adds the provided Resource 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 provided Resource as associated content.
      Parameters:
      content - The associated content to remove
      Throws:
      ContentFragmentException - if the resource could not be removed

    • getLastModifiedDate

      @Nullable @Nullable 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 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 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 fragment
      variationName - 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 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