Add a Custom Report to the Reporting Dashboard
Introduction
Goal
Add a custom reporting plugin to the CMS.
Background
The reporting dashboard is a separate perspective in the CMS. It is similar to the admin perspective and provides an overview of icons / portals with a breadcrumb behaviour. Each icon represents a configurable group of plugins which gets shown if an icon is clicked. The following example will describe a basic setup to add a custom portal group with one panel.
The reporting dashboard is based on Ext JS and Wicket, for further information have a look at the wicket-extjs project source code.
Create a PortalPanelPlugin
To create a Portal Panel which represents a group of plugins with an icon, title and description create the following class in the cms module of your project:
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;
}
}
The important functions which register and connect everything are getPanelServiceId() and getPortalPanelServiceId().
Note the reference to the image hello-world-48.png. Add a 48x48 icon (e.g. this copy of the 'buzz' icon) with that name to the cms module, under src/main/resources, in the package com.onehippo.cms7.reports.plugins.
Create an ExtPlugin
To render a plugin within the portal you must create another class (also in the cms module) which adds a Javascript resources header contribution and generates the Ext JS Javascript code to instantiate the class. It is a bridge between Wicket and Ext JS which initialises the config object passed to the constructor of the Ext JS javascript class. The annotation @ExtClass maps the java class to the custom javascript Ext JS class Hippo.Reports.HelloWorldPluginPanel which is defined in the file referenced by the head contribution Hippo.Reports.HelloWorldPluginPanel.js. @ExtProperty passes / converts class member variables to the javascript config object ( Hippo.Reports.HelloWorldPluginPanel.js).
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;
}
}
For this example create a custom Ext JS class and simply display a property which was defined in the configuration of the plugin in the repository (see next XML code snippets for more details).
Create the following Javascript file in the cms module (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);
Configuration and initialisation of the plugins
The reporting dashboard is configured under the path /hippo:configuration/hippo:frontend/cms/hippo-reports. For this example you need two child nodes which initialise the two plugins. The XML representations of the child nodes are below and can be imported through the Console:
<sv:node sv:name="hello-world-portal-panel" xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
<sv:property sv:name="jcr:primaryType" sv:type="Name">
<sv:value>frontend:plugin</sv:value>
</sv:property>
<sv:property sv:name="plugin.class" sv:type="String">
<sv:value>
com.onehippo.cms7.reports.plugins.HelloWorldPortalPanel
</sv:value>
</sv:property>
</sv:node>
<sv:node sv:name="hello-world-plugin" xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
<sv:property sv:name="jcr:primaryType" sv:type="Name">
<sv:value>frontend:plugin</sv:value>
</sv:property>
<sv:property sv:name="background" sv:type="Boolean">
<sv:value>true</sv:value>
</sv:property>
<sv:property sv:name="height" sv:type="Long">
<sv:value>600</sv:value>
</sv:property>
<sv:property sv:name="helloworld.text" sv:type="String">
<sv:value>Hello World!</sv:value>
</sv:property>
<sv:property sv:name="plugin.class" sv:type="String">
<sv:value>com.onehippo.cms7.reports.plugins.HelloWorldPlugin</sv:value>
</sv:property>
<sv:property sv:name="wicket.id" sv:type="String">
<sv:value>service.reports.helloworld</sv:value>
</sv:property>
<sv:property sv:name="width" sv:type="Double">
<sv:value>0.5</sv:value>
</sv:property>
</sv:node>
Important is the reference by the property wicket.id. It references the previous defined service string constant HELLO_WORLD_PANEL_SERVICE in HelloWorldPortalPanel.java to associate the plugin with the plugin HelloWorldPlugin.
Layout and appearance
The layout of the plugins is dynamic to the browser size and can be influenced with the properties width ( Double) and height ( Long). width is defined in relative percentage and height in absolute pixels. To give the plugin a light grey gradient background you can set the boolean property background.