Add a Custom Report to the Content Reports Application

Info: The Content Reports feature in Bloomreach Content requires a standard or premium license. Contact Bloomreach for licensing details.

Overview

This guide describes how to add a custom reporting plugin to the Content Reports application in the CMS.

When to Use

Use this procedure to extend the Insights > Content reports application with a custom portal group and panel. This allows you to display custom reports or visualizations within the CMS.

Prerequisites

Access to the project source code, specifically the cms module.
Familiarity with Java, Ext JS, and Wicket.
A standard or premium Bloomreach Content license.

Implementation Steps

1. Create a PortalPanelPlugin

A portal panel groups related plugins and provides an icon, title, and description in the Content Reports application.

Create the following Java class in the cms module:

HelloWorldPortalPanel.java:

package com.onehippo.cms7.reports.plugins;

import org.apache.wicket.request.resource.ResourceReference;
import org.apache.wicket.request.resource.PackageResourceReference;
import org.apache.wicket.model.IModel;
import org.apache.wicket.model.Model;
import org.hippoecm.frontend.plugin.IPluginContext;
import org.hippoecm.frontend.plugin.config.IPluginConfig;
import org.onehippo.cms7.reports.ReportsPerspective;
import org.onehippo.cms7.reports.plugins.PortalPanelPlugin;

public class HelloWorldPortalPanel extends PortalPanelPlugin {

    public static final String HELLO_WORLD_PANEL_SERVICE =
                                         "service.reports.helloworld";

    public HelloWorldPortalPanel(final IPluginContext context,
                                 final IPluginConfig config) {
        super(context, config);
    }

    @Override
    public ResourceReference getImage() {
        return new PackageResourceReference(HelloWorldPortalPanel.class,
                                     "hello-world-48.png");
    }

    @Override
    public IModel<String> getTitle() {
        return new Model<String>("Hello World");
    }

    @Override
    public IModel<String> getHelp() {
        return new Model<String>("Hello World Help");
    }

    @Override
    public String getPanelServiceId() {
        // the service id of the perspective this plugin should be rendered
        // in, here the reports perspective
        return ReportsPerspective.REPORTING_SERVICE;
    }

    @Override
    public String getPortalPanelServiceId() {
        // the service id of the portal panel, to associate plugins to
        // the panel
        return HELLO_WORLD_PANEL_SERVICE;
    }

}

getPanelServiceId() and getPortalPanelServiceId() link the portal panel to the reporting perspective and associate plugins with this panel.
The getImage() method references an icon file named hello-world-48.png. Add a 48x48 pixel icon with this name to src/main/resources/com/onehippo/cms7/reports/plugins in the cms module. You can use this sample icon.

2. Create an ExtPlugin

To render content inside the portal, implement a plugin that bridges Wicket and Ext JS. This plugin contributes JavaScript resources and initializes the Ext JS component.

Create the following Java class in the cms module:

HelloWorldPlugin.java:

package com.onehippo.cms7.reports.plugins;

import org.apache.wicket.markup.head.IHeaderResponse;
import org.apache.wicket.markup.head.JavaScriptHeaderItem;
import org.apache.wicket.request.resource.JavaScriptResourceReference;
import org.hippoecm.frontend.plugin.IPluginContext;
import org.hippoecm.frontend.plugin.config.IPluginConfig;
import org.onehippo.cms7.reports.AbstractExtRenderPlugin;
import org.onehippo.cms7.reports.plugins.ReportPanel;
import org.wicketstuff.js.ext.ExtComponent;
import org.wicketstuff.js.ext.util.ExtClass;
import org.wicketstuff.js.ext.util.ExtProperty;

public class HelloWorldPlugin extends AbstractExtRenderPlugin {

    private static final JavaScriptResourceReference PANEL_JS =
        new JavaScriptResourceReference(HelloWorldPlugin.class, "Hippo.Reports.HelloWorldPluginPanel.js");

    private ExtComponent helloWorldPluginPanel;

    @ExtClass("Hippo.Reports.HelloWorldPluginPanel")
    public class HelloWorldPluginPanel extends ReportPanel {

        @ExtProperty
        public String helloWorldText;

        public HelloWorldPluginPanel(final IPluginContext context,
                                     final IPluginConfig config) {
            super(context, config);
            helloWorldText = config.getString("helloworld.text");
        }

        @Override
        public void renderHead(IHeaderResponse response) {
            super.renderHead(response);
            response.render(JavaScriptHeaderItem.forReference(PANEL_JS));
        }
    }

    public HelloWorldPlugin(IPluginContext context, IPluginConfig config) {
        super(context, config);
        helloWorldPluginPanel = new HelloWorldPluginPanel(context, config);
        add(helloWorldPluginPanel);
    }

    @Override
    public ExtComponent getExtComponent() {
        return helloWorldPluginPanel;
    }

}

The @ExtClass annotation maps the Java class to the Ext JS class Hippo.Reports.HelloWorldPluginPanel.
The @ExtProperty annotation exposes the helloWorldText property to the JavaScript configuration.

Create the corresponding JavaScript file in the same package as the Java classes:

Hippo.Reports.HelloWorldPluginPanel.js:

(function(Ext) {

    // define the namespace
    Ext.ns('Hippo.Reports');

    // custom javascript class which gets initialised due to the annotations
    // in HelloWorldPlugin.java
    Hippo.Reports.HelloWorldPluginPanel = Ext.extend(Hippo.Reports.Portlet, {

         // config.helloWorldText holds the value of the @ExtProperty annotated
         // helloWorldText class member variable
         constructor : function(config) {

            // set the Ext html panel property to render the hello world text
            // in the panel
            config = Ext.apply(config, { html : config.helloWorldText });

            // call the super constructor
            Hippo.Reports.HelloWorldPluginPanel.superclass.constructor.call(
                                                                this, config);
        }

    });

    // register the class as xtype
    Ext.reg('Hippo.Reports.HelloWorldPluginPanel',
             Hippo.Reports.HelloWorldPluginPanel);
})(Ext);

This JavaScript defines the Ext JS component that displays the configured text.

3. Configure the Plugins in the Repository

Configure the reporting dashboard under /hippo:configuration/hippo:frontend/cms/hippo-reports. Import the following YAML definitions using the Console:

Portal panel configuration:

definitions:
  config:
    /hippo:configuration/hippo:frontend/cms/hippo-reports/hello-world-portal-panel:
      jcr:primaryType: frontend:plugin
      plugin.class: com.onehippo.cms7.reports.plugins.HelloWorldPortalPanel

Plugin configuration:

definitions:
  config:
    /hippo:configuration/hippo:frontend/cms/hippo-reports/hello-world-plugin:
      jcr:primaryType: frontend:plugin
      background: true
      height: 600
      helloworld.text: Hello World!
      plugin.class: com.onehippo.cms7.reports.plugins.HelloWorldPlugin
      wicket.id: service.reports.helloworld
      width: 0.5

The wicket.id property must match the HELLO_WORLD_PANEL_SERVICE constant in HelloWorldPortalPanel.java. This links the plugin to the portal panel.

Layout and Appearance

The width property (Double) sets the plugin width as a percentage of the available space.
The height property (Long) sets the plugin height in pixels.
Set background: true to apply a light grey gradient background to the plugin panel.

Verification

Deploy your changes and start the CMS.
Navigate to Insights > Content reports in the CMS.
Confirm that the new "Hello World" icon appears.
Click the icon to open the custom panel and verify that the configured text is displayed.

Troubleshooting

If the icon does not appear, verify the image file location and the getImage() method in HelloWorldPortalPanel.java.
If the panel does not display the configured text, check the YAML configuration for the helloworld.text property and ensure the JavaScript file is loaded.
Review the CMS logs for errors related to plugin initialization.