Create an extra menu item - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 12. There's an updated version available that covers our most recent release.

13-09-2018

Create an extra menu item

Menu plugin

If users should initiate some of the workflow actions from the CMS GUI, a module should contain:

  1. Plugin: a Wicket Java class. A standard plugin requires only copy/paste.
  2. Plugin html: The html for the Wicket Java class.
  3. Plugin properties files: Files for translations of words shown in the GUI.
  4. Icons to show on the buttons that are for initiating workflow actions.

In addition, the repository bootstrap content should contain configuration to define when & where the plugin should be created.

Folder context menu

The folder context menu is defined by the workflow category 'threepane'. It contains different configurations for the admin, editor & author roles.

As an example, a simple 'index' button will be added to the menu. Clicking it will create a document named 'index' of a particular type.

Plugin Wicket Java class - IndexWorkflowPlugin.java

In your project, add a file cms/src/main/java/com/example/IndexWorkflowPlugin.java:

package com.example;

import org.apache.wicket.Component;
import org.apache.wicket.model.StringResourceModel;
import org.hippoecm.addon.workflow.StdWorkflow;
import org.hippoecm.addon.workflow.WorkflowDescriptorModel;
import org.hippoecm.frontend.plugin.IPluginContext;
import org.hippoecm.frontend.plugin.config.IPluginConfig;
import org.hippoecm.frontend.plugins.standards.icon.HippoIcon;
import org.hippoecm.frontend.service.render.RenderPlugin;
import org.hippoecm.frontend.skin.Icon;
import org.hippoecm.repository.api.WorkflowDescriptor;
import org.hippoecm.repository.standardworkflow.FolderWorkflow;
 
public class IndexWorkflowPlugin extends RenderPlugin<WorkflowDescriptor> {
 
    public IndexWorkflowPlugin(IPluginContext context, IPluginConfig config) {
        super(context, config);
 
        add(new StdWorkflow<FolderWorkflow>("index",
                new StringResourceModel("index", this, null),
                (WorkflowDescriptorModel) getModel()) {

            @Override
            protected Component getIcon(final String id) {
                return HippoIcon.fromSprite(id, Icon.FILE);
            }

            @Override
            protected String execute(FolderWorkflow workflow) throws Exception {
                workflow.add("new-document", "myhippoproject:index", "index");
                return null;
            }
        });
    }
}

Above you see the code for the IndexWorkflowPlugin class. This class uses Wicket to add a button in the CMS GUI and defines which workflow action is performed if that button is pressed.

Elaborate custom plugin

Add your own code for a more elaborate custom plugin. To understand the above plugin first, lets dissect it: It uses a call to the Wicket add method to add a button for the 'index' workflow action. An anonymous inner Std Workflow subclass overrides the getIcon and the execute methods. The StringResourceModel is a Wicket class that allows the "index" string to be replaced by entries from the properties file.

Plugin Wicket HTML - IndexWorkflowPlugin.html

The markup file should be located in the same package as the Java file, with the same name. We'll put in below src/main/resource so Maven picks it up automatically.

cms/src/main/resources/com/example/IndexWorkflowPlugin.html:

<html xmlns:wicket="http://wicket.apache.org/">
  <wicket:panel>
    <div wicket:id="index">[ WORKFLOW ]</div>
  </wicket:panel>
</html>

Above you see the Wicket HTML file. The wicket ID named "index" is given to a <div> inside of a Wicket panel. The string ' [ WORKFLOW ]' will be replaced by the Wicket with the button we are making.

Plugin Wicket resource bundle - IndexWorkflowPlugin.properties

The plugin needs a Java resource bundle for the 'index' label. Add a file  cms/src/main/resources/com/example/IndexWorkflowPlugin.properties:

index=Create index

Add more properties files for different languages. For example, a Dutch version  cms/src/main/resources/com/example/IndexWorkflowPlugin_nl.properties:

index=Creeer index

Repository Configuration

The plugin needs to be loaded as part of the plugin cluster for the context menu. This menu is defined in the 'threepane' category, /hippo:configuration/hippo:workflows/threepane. Three nodes define the clusters for different users:

  • folder-permissions/frontend:renderer (for admins)
  • folder-extended/frontend:renderer (for editors)
  • folder/frontend:renderer (for authors)

To make the 'Create index' action available to all these users, add a node of type frontend:plugin below each of these cluster nodes. The node name does not matter, but let's use "create-index":

/hippo:configuration/hippo:workflows/threepane/folder-permissions/frontend:renderer/create-index:
  jcr:primaryType: frontend:plugin
  plugin.class: com.example.IndexWorkflowPlugin
  wicket.id: ${item}
/hippo:configuration/hippo:workflows/threepane/folder-extended/frontend:renderer/create-index:
  jcr:primaryType: frontend:plugin
  plugin.class: com.example.IndexWorkflowPlugin
  wicket.id: ${item}
/hippo:configuration/hippo:workflows/threepane/folder/frontend:renderer/create-index:
  jcr:primaryType: frontend:plugin
  plugin.class: com.example.IndexWorkflowPlugin
  wicket.id: ${item}

See the plugin in action

Our plugin will create a document of type myhippoproject:index, so first add a document type with that name to the project. Next, open the context menu of a folder in Content > Documents. The last menu item will be Create index, and clicking it will create a new document called "index".

Document editor menu

The document editor menu is very similar to the folder context menu case. The main differences are the workflow category and the workflow type.

The plugin cluster that contains the standard menu items is located at

/hippo:configuration/hippo:workflows/default/handle/frontend:renderer

The workflow type in use here is the DocumentWorkflow.

Sub menu

Since the document editor menu is hierarchical, rather than flat like the context menu, menu items here can use additional control over their positioning. Override the getSubMenu method to control in which dropdown the item should appear. The submenu 'top' is special; the button will be rendered in the menu bar. Use a different name (e.g. 'document' or 'publication') to add the item to an existing sub-menu.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?