أنت تعرض محتوى المساعدة للإصدار:

A content fragment extends a standard asset; see:

Architecture

The basic constituent parts of a content fragment are:

  • Content Fragment,
  • consisting of one or more Content Elements,
  • and which can have one or more Content Variations.
  • Where:
    • Variations are managed globally; i.e. all elements have the same number of variations with the same name and description, but with (potentially) different content.
    • The MIME type of the content is managed on the actual content; this means that each element and variation can have a different MIME type.

Templates are also used:

  • Templates define the structure of a content fragment when it is created.
  • That structure may change over the lifetime of a fragment; therefore the template is copied to the fragment and considered as its model afterwards.
  • Functions to add new variations, etc., have to update this model accordingly.
  • Content fragment templates operate in a different manner to that of other templating mechanisms within the AEM ecosystem (e.g. page templates, etc.). Therefore they should be considered separately.

Integration with Assets

Content Fragment Management (CFM) is part of AEM Assets as:

  • Content fragments are assets.
  • They use existing Assets functionality.
  • They are fully integrated with Assets (admin consoles, etc.).

Mapping Content Fragments to Assets

chlImage_1

Content fragments are mapped to a composite consisting of a main asset and (optional) sub-assets:

  • All non-content information of a fragment (such as title, description, metadata, model) is managed on the main asset exclusively.
  • The content of the first element of a fragment is mapped to the original rendition of the main asset.
    • The variations (if there are any) of the first element are mapped to other renditions of the main asset.
  • Additional elements (if existing) are mapped to sub-assets of the main asset.
    • The main content of these additional elements map to the original rendition of the respective sub-asset.
    • Other variations (if applicable) of any additional elements map to other renditions of the respective sub-asset.

Asset Location

As with standard assets, a content fragment is held under:

/content/dam

Feature Integration

  • The Content Fragment Management (CFM) feature builds on the Assets core, but should be as independent of it as possible.
  • CFM provides its own implementations for items in the card/column/list views; these plug into the existing Assets content rendering implementations.
  • Several Assets components have been extended to cater for content fragments.

Using Content Fragments in Pages

Content fragments can be referenced from AEM pages, just as any other asset type. AEM provides the Content Fragment component - a generic, out-of-the-box component that allows you to include content fragments on your pages. You can also extend, this Content Fragment component

  • The component uses the fileReference property to reference the actual content fragment. The fileReference 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 allows you to 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 allows you to place other assets (images, etc.) 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
      • include referenced content fragments in the results of a Site search; and ensure an acceptable performance level
      • consider the additional parameters (such as like variation and paragraph filters) to avoid false positives in search results

Integration with other Frameworks

Content fragments can be integrated with:

  • Translations

    Content Fragments are fully integrated with the AEM translation workflow. On an architectural level, this means:

    • The individual ranslations of a content fragment are actually separate fragments:
      • they are located under different language roots (/content/dam/path/en/to/fragment vs. /content/dam/path/de/to/fragment)
      • but they share exactly the same relative path below the language root (/content/dam/path/en/to/fragment vs. /content/dam/path/de/to/fragment)
    • Besides the rule-based paths, there is no further connection between the different language versions of a content fragment; they are handled as two separate fragments, although the UI provides the means to navigate between the language variants.
    • As the model (which also includes lanugage-specific texts such as title, description, etc.) is copied from the template, it can be included in the translation process as well.
  • Metadata schemas

    • Content fragments (re)use the metadata schemas, that can be defined with standard assets.
    • CFM provides its own, specific schema (/libs/dam/content/schemaeditors/forms/contentfragment); this can be extended if required.
    • The respective schema form is integrated with the fragment editor.

The Content Fragment Management API - Server-Side

You can use the server-side API to access your content fragments; see:

com.adobe.cq.dam.cfm

تحذير:

It is strongly recommended to use the server-side API instead of directly accessing the content structure.

Key Interfaces

The following three interfaces can serve as entry points:

  • Content Fragment Manager (ContentFragmentManager)

    This interface provides the mechanisms for you to create new fragments from a template resource. It also allows extended access to associated content by resolving the collection references to the actual collection content.

    ملاحظة:

    If you want to access the associated content on publish (e.g. in a customized component), you cannot use the API. Instead, you have to copy the required information (e.g. reference) to a location that anonymous has read access to before publishing.

  • Content Fragment (ContentFragment)

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

    تحذير:

    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 (e.g. 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 data model (see FragmentTemplate)

    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
  • Fragment Template (FragmentTemplate)

    This interface represents both a template from which to create a content fragment and (after the creation) the data model of that fragment.

    • Access basic data (title, description)
    • Access templates for the elements of the fragment:
      • List element templates
      • Get the model for a given element
      • Access the element template (see ElementTemplate)
    • Access templates for the variations of the fragment:
      • List variation templates
      • Get the model for a given variation
      • Access the variation template (see VariationTemplate)
    • Get initial associated content

    Interfaces that represent important elements of templates:

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

Adapting - Using adaptTo()

The following can be adapted:

  • ContentFragment can be adapted to:

    • Resource - the underlying Sling resource; note that updating the underlying Resource directly, requires rebuilding the ContentFragment object.
    • Asset - the DAM Asset abstraction that represents the content fragment; note that updating the Asset directly, requires rebuilding the ContentFragment object.
  • ContentElement can be adapted to:

    • ElementTemplate - for accessing the element's data model.
  • FragmentTemplate can be adapted to:

    • Resource - the underlying Resource of the fragment's data model;
      • changes made through the Resource are not automatically reflected in the FragmentTemplate.
  • Resource can be adapted to:

    • ContentFragment
    • FragmentTemplate

Caveats

It should be noted that:

  • The API is implemented to provide functionality supported by the UI.
  • The entire API is designed to not persist changes automatically (unless otherwise noted in the API JavaDoc). So you will always have to commit the resource resolver of the respective request (or the resolver you are actually using).
  • Tasks that might require additional effort:
    • Creating/removing new elements will not update the data model.
    • Creating new variations from ContentElement will not update the data model (but creating them globally from ContentFragment will).
    • Removing existing variations will not update the data model-

The Content Fragment Management API - Client-Side

The fragment editor uses a set of (more or less dependent) components that are combined for the different views (Edit, Associated Content, Metadata).

The client-side JavaScript API is basically a set of events used for inter-component communication. This event-based API may be used for extending the Content Fragment feature.

Content Structure

The root path is:

 /libs/dam/cfm/admin

Under this the content is separated into three sub-trees:

  • content - content definitions used by the CFM admin pages
  • components - the components
  • clientlibs - the client libraries

تحذير:

You must not change anything in the /libs path.

Components

The following components are available for use:

تحذير:

It is not recommended to extend or change the actual components as they are still subject to change.

  • Basic page component - adminpage
    • The basic page components, used by all admin pages.
  • Authoring-related components - authoring sub-tree
    • Components required for editing the content of an element or variation; contains both the editor components themselves and the tools that are provided to process the text.
    • Components to manage the variations of a fragment/element.
  • Associated content-related components - associatedcolls sub-tree
    • Components for managing the associated collections.
  • Cards, List, Columns - contentrenderer sub-tree
    • Components for content rendering in list, column and card views.
  • Metadata components - metadata sub-tree
    • Components required for managing the Assets metadata for content fragments.
  • Wizard components - wizards sub-tree
    • Wizard for creating a new fragment
  • General/shared components - shared sub-tree
    • Shared components, such as tagspicker and viewselect.
  • Render conditions - rendercondition sub-tree
    • Conditions for rendering.
  • Datasources - datasources sub-tree
    • Components for managing datasources.

Client Libraries

Clientlibs are provided on a per module base:

  • Page handling/General
    • adminpage (dam.cfm.adminpage) - general scripts and styles shared by all views; notably:
      • editsession.js - handles auto save and the transactional multi-page editing required by CFM
      • page.js - page initialization, resize handling, handling global UI elements; for example, content element (if present) and view switchers
    • shared/tagspicker (dam.cfm.shared.tagspicker) - scripts and styles for the patched CQ default tag picker
  • Text authoring/Editor implementation
    • authoring (dam.cfm.authoring) - currently contains the styles and scripts required for managing the variations UI (adding/removing variations)
    • authoring/rte/core (dam.cfm.authoring.rte.core) - RTE Core (used for Rich Text content); references the required files from /etc/clientlibs/granite/coralui2/optional/rte/js
    • authoring/rte/impl (dam.cfm.authoring.rte) - UI implementation required for CFM's Rich Text editing (UI elements, toolbar, wrapper widget)
    • authoring/contenteditor (dam.cfm.authoring.contenteditor) - implements the tools of the content editor; notably:
      • activevar.js - scripts required for displaying and updating the currently edited variation
      • switcher.js - scripts required for handling a change of the MIME type via the respective dropdown; note that this script only binds the dropdown, the actual type change is implemented in authoring/editor.js
      • textstatistics.js - scripts that handle the display and update of the text statistics (see authoring/contenteditor/textstats)
      • editor.js - binds the editor implementations (see authoring/contenteditor/editors) to the authoring view: handles the saving and loading of elements/variations; enables/disables the editor responsible for the current text (determined by the text's MIME type), changing the MIME type of an element/variation and converting the existing text to the new format, etc.; also exposes the respective functionality through the event API
    • authoring/contenteditor/editors (dam.cfm.authoring.editors) - this client lib provides the implementation of editors for the respective MIME type (currently MarkdownEditor.js, StyledTextEditor.js, PlainTextEditor.js). MIME types and the editor to be used for editing text of that type are mapped through EditorRegistry.js. Styled content (for example, HTML and Markdown) can be converted to plain text by HTMLExtractor.js and MarkdownEditor.js - this is required for calculating the text statistics.  
    • authoring/contenteditor/textstats (dam.cfm.authoring.textstats) - library that is used for calculating the text statistics.
  • View related:
    • Associated content
      • assoccontent (dam.cfm.assoccontent) - scripts related to the associated content.
    • Metadata editor
      • metadata (dam.cfm.metadata) - integrates the standard metadata editor for assets with content fragment management (metadata.js); also contains some required overrides for some of the original asset scripts (form.js, metadataeditor.js); finally implements uploading a thumbnail for the content fragment
    • Other views
      • adminpage/wizard (dam.cfm.adminpage.wizard) - scripts that handle title to name conversation & field validation within Create Fragment wizard
  • Library fragments
    • admin (dam.gui.actions.coral) - adds the scripts required to start the Create Fragments wizard from the Create button on the Assets console.

Additional Information

See the following:

  • filter.xml

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

  • View configuration

    The views are configured under:

    /libs/dam/content/schemaeditors/forms/contentfragment

    تحذير:

    You must not change anything in the /libs path.

    Each view is represented by a nt:unstructured child node and configured by means of the following properties:

    • text - the text that appears in the view selector; for example, Edit
    • type - the internal name of the view; for example, authoring
    • value - the URL of the page that hosts the view; for example,
      ${granite:url("/mnt/overlay/dam/cfm/admin/content/fragment-editor.html")}${requestPathInfo.suffix}

Edit Sessions

An editing session is started when the user opens a content fragment in one of the editor pages and starts editing; for example, by entering text or removing a variation.  The editing session is finished when the user leaves the editor by selecting either save (checkmark/tick) or cancel (X).

Requirements

Requirements for controlling an editing session are:

  • Editing a content fragment, which can span multiple views (= HTML pages),  should be atomic.
  • The editing should also be transactional; at the end of the edit session the changes must either be committed (saved) or rolled back (cancelled).
  • Edge cases should be handled properly; these include situations such as when the user leaving the page by entering a URL manually or using global navigation.
  • A periodic auto save (every x minutes) should be available to prevent data loss.
  • If a content fragment is edited by two users concurrently, they should not overwrite each other's changes.

Processes

The processes involved are:

  • Starting a session
    • A new version of the content fragment is created.
    • Auto save is started.
    • Cookies are set; these define the currently edited fragment and that there is an edit session open.
  • Finishing a session
    • Auto save is stopped.
    • Upon commit: 
      • The last modified information is updated.
      • Cookies are removed.
    • Upon rollback:
      • The version of the content fragment that was created when the edit session was started is restored.
      • Cookies are removed.
  • Editing
    • All changes (auto save included) are done on the active content fragment - not in a separated, protected area.
    • Therefore, those changes are reflected immediately on AEM pages that reference the respective content fragment

Actions

The possible actions are:

  • Entering a page
    • Check if an editing session is already present; by checking the respective cookie.
      • If one exists, verify that the editing session was started for the content fragment that is currently being edited
        • If the current fragment, reestablish the session.
        • If not, try to cancel editing for the previously edited content fragment and remove cookies (no editing session present afterwards).
      • If no edit session exists, wait for the first change made by the user (see below).
    • Check if the content fragment is already referenced on a page and display appropriate information if so.
  • Content change
    • Whenever the user changes content and there is no edit session present, a new edit session is created (see Starting a session).
  • Leaving a page
    • If an editing session is present and the changes have not been persisted, a modal confirmation dialog is shown to notify the user of potentially lost content and allow them to stay on the page. This modal dialog can also be blocked manually (see the cfm:block event).

 

Examples

Example: Accessing an existing content fragment

To achieve this you can adapt the resource that represents the API to:

com.adobe.cq.dam.cfm.ContentFragment

For example:

// first, get the resource
Resource fragmentResource = resourceResolver.getResource("/content/dam/fragments/my-fragment");
// then adapt it
if (fragmentResource != null) {
    ContentFragment fragment = fragmentResource.adaptTo(ContentFragment.class);
    // the resource is now accessible through the API
} 

Example: Creating a new content fragment

To create a new content fragment programmatically, you need to use:

com.adobe.cq.dam.cfm.ContentFragmentManager#create

For example:

@Reference
private ContentFragmentManager fragmentManager;

// ...

private void myCreateFun() {
    // Parameters for fragmentManager.create
    //     parent - the folder where the fragment should be created
    //     template - the template to use
    //     name
    //     title
    ContentFragment myFragment = fragmentManager.create(parent, template, "my-fragment", "My Fragment");
    // ... 
}

Example: Specifying the auto-save interval

The auto save interval (measured in seconds) can be defined using the configuration manager (ConfMgr):

  • Node: <conf-root>/settings/dam/cfm/jcr:content
  • Property Name: autoSaveInterval
  • Type: Long
  • Default: 600 (10 minutes); this is defined on /libs/settings/dam/cfm/jcr:content

If you want to set an auto save interval of 5 minutes you need to define the property on your node; for example:

  • Node: /conf/global/settings/dam/cfm/jcr:content
  • Property Name: autoSaveInterval
  • Type: Long
  • Value: 300 (5 minutes equates to 300 seconds)

Templates

See Content Fragment Templates for full information.

Components for Page Authoring

تم ترخيص هذا العمل بموجب الترخيص العام غير المعدل الخاص بالإسناد وعدم التجارة والمشاركة الإصدار 3.0 ‏من ‏‏Creative Commons‏‏  إن بنود Creative Commons لا تشمل منشورات Twitter™‎ وFacebook.

إشعارات قانونية   |   سياسة الخصوصية على الإنترنت