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.

    One element (the "main" or "master" element) is considered to define the content fragment. This means, it has a special position within the content element and usually contains the "most important" or "most distinctive" content.

    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.

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

        Parameters:
        name - The (technical) name of the variation to be created
        title - The (human-readable) title of the variation to be created
        description - The 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