Bloomreach

Bloomreach Documentation version

Create a Custom Perspective

Introduction

Goal

Create a custom Bloomreach Experience Manager application (a.k.a. perspective) and add it to the brX navigation UI.

Background

'Perspectives' is the internal name for the different Bloomreach Experience Manager applications provided to a user through the navigation UI. Examples are the Content application in which documents, images and assets can be edited, the Setup > System application with management of users, groups, roles, etc. These are all different areas the user can navigate to and carry out different types of operations. The end user manual describes which applications are bundled with the default installation of Bloomreach Experience Manager.

Please note that as of Bloomreach Experience Manager, custom applications running on an external URL require their domain to be added to the Content Security Policy.

Create a Custom Perspective

A custom perspective can show any type of information, interact with the content, load an external iframe, etc. Creating one requires at least the repository configuration of the perspective and a Wicket plugin together with its HTML file. Optionally, the perspective can include a CSS file for styling. The custom perspective will be visible in the navigation's Extensions menu.

Example

Our example perspective will show an empty screen that shows the text "Hello world!". The example will use package com.example.

First add the file cms/src/main/java/com/example/MyCustomPerspective.java:

package com.example;

import javax.jcr.Session;

import org.apache.wicket.markup.head.CssHeaderItem;
import org.apache.wicket.markup.head.IHeaderResponse;
import org.apache.wicket.request.resource.CssResourceReference;
import org.apache.wicket.request.resource.ResourceReference;
import org.hippoecm.frontend.plugin.IPluginContext;
import org.hippoecm.frontend.plugin.config.IPluginConfig;
import org.hippoecm.frontend.plugins.standards.perspective.Perspective;
import org.hippoecm.frontend.session.UserSession;

public class MyCustomPerspective extends Perspective {

    private static final ResourceReference PERSPECTIVE_CSS =
            new CssResourceReference(MyCustomPerspective.class, "MyCustomPerspective.css");

    public MyCustomPerspective(IPluginContext context, IPluginConfig config) {
        super(context, config);
        setOutputMarkupId(true);
        Session session = UserSession.get().getJcrSession();
    }

    @Override
    public void renderHead(final IHeaderResponse response) {
        response.render(CssHeaderItem.forReference(PERSPECTIVE_CSS));
    }

}

Next, add the Wicket markup file cms/src/main/resources/com/example/MyCustomPerspective.html:

<html xmlns:wicket="http://wicket.apache.org/">
  <wicket:panel>
    <div id="my-custom-perspective">
      Hello world!
    </div>
  </wicket:panel>
</html>

Last, include the CSS file that is referenced in the Java class:  cms/src/main/resources/com/example/MyCustomPerspective.css

#my-custom-perspective {
  font-size: 16px;
  font-weight: bold;
}

Rebuild and restart your project.

Use the Console to configure the custom perspective.

Add a frontend:plugin node to /hippo:configuration/hippo:frontend/cms/cms-static.

Add the mixin frontend:navigationitem.

Set the mandatory property frontend:appPath. The appPath will be the last path segment of the url if the menu item is active. For example, when the appPath is “myapp” and Bloomreach Experience Manager is deployed on “https://cms.example.com” then the url of the custom perspective is “https://cms.example.com/myapp”.

Set the property hipposys:userrole. You can choose a role provided by the product (e.g. xm.cms.user) or you can assign a role provided by your own project.

/hippo:configuration/hippo:frontend/cms/cms-static/myCustomPerspective:
  jcr:primaryType: frontend:plugin
  jcr:mixinTypes: ['frontend:navigationitem']
  frontend:appPath: my-custom-perspective
  hipposys:userrole: xm.cms.user
  plugin.class: com.example.MyCustomPerspective
  wicket.id: service.tab
Order of perspectives
The order of the perspectives in the Extensions menu is determined by the order of their configuration nodes under /hippo:configuration/hippo:frontend/cms/cms-static.

Add translation key-value pairs to /hippo:configuration/hippo:translations/hippo:navigation/navigationitem for the languages you need for your perspective:

/hippo:configuration/hippo:translations/hippo:navigation/navigationitem:
  jcr:primaryType: hipposys:resourcebundles
  /displayName:
    jcr:primaryType: hipposys:resourcebundles
    /en:
      jcr:primaryType: hipposys:resourcebundle
      my-custom-perspective: My Custom Perspective
Please note that displayName is a mandatory translation key for custom perspectives. If a custom perspective does not have displayName defined, the navigation UI will not add it to the Extensions menu.

Log in to Bloomreach Experience Manager and your custom perspective should show up in the Extensions menu.

Lazy-Loaded Perspective

Perspectives can use the CMS plugin framework to register plugins and use other plugins. The example perspective above does not register or use any plugins yet. But if it would, all its plugins would be instantiated directly when someone logs in to the CMS. That may slow down the initial page load of the CMS considerably.

Perspectives can also be loaded lazily. A lazy loaded perspective defers the instantiation of its plugins until it is activated for the first time (i.e. select in the UI). This strategy decreases the amount of time to instantiate the CMS UI after logging in. When your perspective performs expensive operations it may be worthwhile to make it lazy-loaded.

A perspective be made lazy loaded by including a string property cluster.name in its configuration node. That property contains the name of the a plugin cluster node below /hippo:configuration/hippo:frontend/cms. Only when the perspective is activated for the first time, the plugin cluster will be loaded.

Example

For example, the configuration of the lazy loading Reports perspective looks like this:

/hippo:configuration/hippo:frontend/cms/cms-static/reportsPerspective:
  jcr:primaryType: frontend:plugin
  jcr:mixinTypes: ['frontend:navigationitem']
  cluster.name: hippo-reports
  frontend:appPath: content-reports
  hipposys:userrole: xm.report.user
  plugin.class: org.onehippo.cms7.reports.ReportsPerspective
  wicket.extension: []
  wicket.id: service.tab

The cluster.name property refers to the plugin cluster node

/hippo:configuration/hippo:frontend/cms/hippo-reports

That plugin cluster will only be loaded when the Reports perspective is activated for the first time.

When making your perspective lazy loaded, take care when the plugins in the perspective's cluster expose services to the rest of the CMS. Since these plugins will not be started automatically, the services they expose will not be available by default. If these services are needed by default, they should be moved to /hippo:configuration/hippo:frontend/cms/cms-services.
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?