Render a 'Manage Content' Button in the Experience Manager

Introduction

Goal

Enable CMS users to create, select, and edit documents within the Experience manager by rendering Manage content buttons in the preview.

Background

When a channel is previewed in the CMS, a Manage content button can be rendered in a component, allowing CMS users to manage the content rendered by that component.

Depending on its configuration, the Manage content button can enable the following functionalities:

• Create a new document to be rendered by the component and open it for editing in the visual editor.
• Select an existing document from the repository to be rendered by the component.
• Open a document already rendered by the component for editing in the visual editor.

Include the Button in a Template

The Manage Content button can be included in a template using the tag hst:manageContent. The tag will output all the necessary HTML to render the Manage Content button when the channel is previewed inside the CMS. In other cases, the tag outputs nothing.

The tag accepts the following parameters:

Parameter	Description	Default value
hippobean	Content bean for existing document. Can be null.	null
documentTemplateQuery	Template query to use for creating new documents. If the template query result is more than one document type, the user must select a type from a dropdown.	null
rootPath	Path to the root folder of selectable document locations. Can be a relative path to the channel's root folder or an absolute path in the repository. The rootPath folder must exist and will not be created automatically. Users are only allowed to create the new document in this folder or one of its descendants.	content root folder of current channel
defaultPath	Initial location of a new document, relative to the rootPath. Can still be changed by the user. Folders specified by defaultPath will be created if they do not yet exist. The new folders are either created using a template query specified in folderTemplateQuery or, if no template query is specified, as a standard hippostd:folder node with the property hippostd:foldertype copied from the parent folder. Requires documentTemplateQuery to be specified, if not a warning will be logged.	empty string
folderTemplateQuery (*)	Template query to use in case folders specified by defaultPath do not yet exist and must be created. Requires defaultPath to be specified, if not a warning will be logged.	empty string
parameterName	Name of the component parameter in which the document path is stored. Will be disabled when the container that the component is placed in is locked by changes of another user.	empty string

(*) Available since version 13.1.0

When the hippobean parameter is set, the button renders an 'edit' icon, otherwise it renders a 'new' icon. Depending on the parameters, the 'parent' buttons may also have speed-dial buttons which appear when you hover over them. The table below lists all possible combinations of hippobean, documentTemplateQuery, and parameterName and the resulting UI for both webmasters and authors.

Usage	hippobean	documentTemplateQuery	parameterName	webmaster privileges		author privileges
				button	hover	button	hover
Edit existing content	✓	-	-		-		-
Create new content	-	✓	-		-		-
Create new content, edit existing content	✓	✓	-				-
Edit existing content, select content	✓	-	✓				-
Create new content, select content	-	✓	✓			-	-
Edit existing content, create new content, select content	✓	✓	✓				-
Select different content	-	-	✓		-	-	-

Examples

Below are some example usages of the hst:manageContent tag taken from templates included in various Essentials features.

• Render an 'edit' button for a content bean in a template variable document:

  Freemarker:

  <@hst.manageContent hippobean=document />

  JSP:

  <hst:manageContent hippobean="${requestScope.document}"/>

• Render a 'new' button to create a new document using the template query new-content-document at the root path content (relative to the channel's content root):

  Freemarker:

  <@hst.manageContent documentTemplateQuery="new-content-document" 
                      rootPath="content"/>

  JSP:

  <hst:manageContent documentTemplateQuery="new-content-document"
                     rootPath="content"/>
  

• Render a 'new' button to create a new document using the template query new-content-document at the root path content (relative to the channel's content root) in subfolders named after the current year and month (if necessary, create the subfolders using the new-news-folder template query):

  Freemarker:

  <@hst.manageContent documentTemplateQuery="new-news-document"
                      folderTemplateQuery="new-news-folder" 
                      rootPath="news" 
                      defaultPath="${currentYear}/${currentMonth}"/>

  JSP:

  <hst:manageContent documentTemplateQuery="new-news-document"
                     folderTemplateQuery="new-news-folder"
                     rootPath="news"
                     defaultPath="${currentYear}/${currentMonth}"/>

• Render an 'edit' button for a content bean in a template variable document. In case of webmaster privileges, render a 'select' speed-dial button. Open the document picker in root path banners and store the selected document's path in the component parameter document:

  Freemarker:

  <@hst.manageContent hippobean=document 
                      parameterName="document"
                      rootPath="banners" />

  JSP:

  <hst:manageContent hippobean="${document}"
                     parameterName="document"
                     rootPath="banners"/>

• Render an 'edit' button for a content bean in a template variable document. In case of webmaster privileges, render a 'select' and 'new' speed-dial buttons. In case of the 'select' button, open the document picker in root path banners. In case of the 'new' button, create a new document using the template query new-banner-document in the root path banners. Store the selected or created document's path in the component parameter document:

  Freemarker:

  <@hst.manageContent documentTemplateQuery="new-banner-document"
                      parameterName="document"
                      rootPath="banners"/>

  JSP:

  <hst:manageContent documentTemplateQuery="new-banner-document"
                     parameterName="document"
                     rootPath="banners"/>

Position the Button

Each button should be located closely to the the area in which the content it manages is rendered. The position of the button can be tweaked using CSS.

Manage Content Button vs. @JcrPath Annotation

Both the hst:manageContent tag and the @JcrPath annotation can be used to enable users to select the content to be rendered by a component. The former directly in a channel preview through the Manage Content button described on this page, the latter through a component's configuration dialog.

Be careful when using both ways to select a document for a component. The root path can for example be set by both methods. It would be confusing for users and possibly break some functionality if the root path is different when using the component configuration dialog or the picker opened by the Manage Content button.

Because the hst:manageContent tag is used in a template, the values for the path attributes can be set dynamically during rendering. This gives more flexibility than the configurations on the @JcrPath annotation.

When using the Relevance Module, selecting different documents for different component variants will be harder for users when using the hst:manageContent tag. It is better to use @JcrPath and the component configuration dialog in this case.

Limitations and Considerations

Some New Documents Cannot Be Saved in the Experience Manager

The content editor does not support all field types yet. If a document type contains such fields the user always has the option to continue editing in the editor in the Content application. In the case where a not-yet-supported field is a required field, or when it has a not-yet-supported validator, it is possible to start creating the document type in the Experience manager application, but a user cannot save it there. The user must switch to the Content application to finish editing and save the document.

Some Document Types Should not be Created in the Experience Manager

The content editor in the Experience manager application may not be able to detect validators configured for unsupported custom fields in a document type.

If that is the case, developers must NOT implement the "create content" option for such a document type.

For example, a plugin class my.company.MyPlugin.class is used to show a Wicket document field plugin. The definition of that can be in its own configuration outside the document type definition (like the Taxonomy plugin) or maybe just by having a mixin (like the Related Documents plugin). The content editor in the Experience manager application cannot detect with 100% certainty if there is maybe some validator defined for that field. So the creation of the document can and must only be done in the editor in the Content application. Editing the document, however, is possible in the Experience manager. A warning is shown about the not-supported fields at the top.

Check the Prototype of the Document Type Definition

The content editor in the Experience manager application is less lenient than the editor in the Content application. When you start adding the option to create documents in the Experience manager application, it is a good idea to check the configuration of the document type in the /hippo:namespaces section in the repository. If the prototype of your document type is incorrectly configured it is not possible to create these documents in the Experience manager. Please check /hippo:namespaces/<mynamespace>/<mydocumenttype>hipposysedit:prototypes/hipposysedit:prototype.

The following properties with given values must exist:

    hippostd:holder: holder
    hippostd:state: draft
    hippostd:stateSummary: new

Prototype Child Node Definitions on Parent Types are Not Processed

A specific configuration set up of document type definitions in hierarchy is not yet supported. With the following setup it will not be possible to create new documents in the Experience manager application.

• the document type has field definitions that will be stored as child nodes on documents: e.g. rich text fields or other compounds
• in the prototype definition of the document type the compound node is not configured

The editor in the Experience manager application cannot yet create a new compound child node on the document. The user gets an error when trying to save the document: the content is reported to be "invalid". In the server logs an error is logged about this situation.This setup can be found in systems where the document types were configured before the CMS had a functioning document type editor. The to-be created child node definition is used from a parent document or the compound definition. If it is an option to update the document type's prototype node with a child node, then you can resolve this situation and the document can be created in the Experience manager application as well.