Customizing and Extending Content Fragments

The component uses the fragmentPath property to reference the actual content fragment. The fragmentPath property is handled in the same manner as similar properties of other asset types; for example, when the content fragment is moved to another location.

The component lets you select the variation to be displayed.

Additionally, a range of paragraphs can be selected to restrict the output; for example, this can be used for multi-column output.

The component allows in-between content:

• Here the component lets you place other assets (images, and so on) in between the paragraphs of the referenced fragment.

• For in-between content you need to:

  • be aware of the possibility of unstable references; in-between content (added when authoring a page) has no fixed relationship to the paragraph it is positioned next to, inserting a new paragraph (in the content fragment editor) before the position of the in-between content can lose the relative position
  • consider the additional parameters (such as like variation and paragraph filters) to avoid false positives in search results

Resource types
A list of sling:resourceTypes can be provided to define components that are used for rendering content fragments and where the background processing should be applied to.

Reference Properties
A list of properties can be configured to specify where the reference to the fragment is stored for the respective component.

The name of the property where the element(s) to be rendered is defined must be either element or elementNames.

The name of the property where the variation to be rendered is defined must be either variation or variationName.

If the output of multiple elements is supported (by using elementNames to specify multiple elements), the actual display mode is defined by property displayMode:

• If the value is singleText (and there is only one element configured) then the element is rendered as a text with in-between content, layout support, and so on. This is the default for fragments where only one single element is rendered.
• Otherwise, a much more simple approach is used (could be called “form view”), where no in-between content is supported and the fragment content is rendered “as is”.

If the fragment is rendered for displayMode == singleText (implicitly or explicitly) the following additional properties come into play:

• paragraphScope defines whether all paragraphs, or only a range of paragraphs, should be rendered (values: all vs. range)

• if paragraphScope == range then the property paragraphRange defines the range of paragraphs to be rendered

Fragment Template (FragmentTemplate)

Use FragmentTemplate.createFragment() for creating a fragment.

Resource templateOrModelRsc = resourceResolver.getResource("...");
FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");

This interface represents:

• either a content fragment model or content fragment template from which to create a content fragment,
• and (after the creation) the structural information of that fragment

This information can include:

• Access basic data (title, description)

• Access templates/models for the elements of the fragment:

  • List element templates
  • Get structural information for a given element
  • Access the element template (see ElementTemplate)

• Access templates for the variations of the fragment:

  • List variation templates
  • Get structural information for a given variation
  • Access the variation template (see VariationTemplate)

• Get initial associated content

Interfaces that represent important information:

• ElementTemplate

  • Get basic data (name, title)
  • Get initial element content

• VariationTemplate

  • Get basic data (name, title, description)

Content Fragment (ContentFragment)

This interface lets you work with a content fragment in an abstract way.

CAUTION

It is strongly recommended to access a fragment through this interface. Changing the content structure directly should be avoided.

The interface provides you with the means to:

• Manage basic data (for example, get name; get/set title/description)

• Access meta data

• Access elements:

  • List elements

  • Get elements by name

  • Create new elements (see Caveats)

  • Access element data (see ContentElement)

• List variations defined for the fragment

• Create new variations globally

• Manage associated content:

  • List collections
  • Add collections
  • Remove collections

• Access the fragment’s model or template

Interfaces that represent the prime elements of a fragment are:

• Content Element (ContentElement)

  • Get basic data (name, title, description)

  • Get/Set content

  • Access variations of an element:

    • List variations
    • Get variations by name
    • Create new variations (see Caveats)
    • Remove variations (see Caveats)
    • Access variation data (see ContentVariation)

  • Shortcut for resolving variations (applying some additional, implementation-specific fallback logic if the specified variation is not available for an element)

• Content Variation (ContentVariation)

  • Get basic data (name, title, description)
  • Get/Set content
  • Simple synchronization, based on last modified information

All three interfaces ( ContentFragment, ContentElement, ContentVariation) extend the Versionable interface, which adds versioning capabilities, required for content fragments:

• Create new version of the element
• List versions of the element
• Get the content of a specific version of the versioned element

filter.xml

The filter.xml for content fragment management is configured so that it does not overlap with the Assets core content package.