Package com.adobe.cq.dam.cfm

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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addAssociatedContent​(Resource content)
      Adds the provided Resource 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 provided Resource 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.

    • 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

      • 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 property
        value - 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 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​(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

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