CMS Perspectives - 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.

08-01-2018

CMS Perspectives

Perspectives in Bloomreach Experience Manager are the different screens provided by the UI to a user. Examples are the Content perspective in which documents, images and assets can be edited, the Admin perspective 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 perspectives are bundled with the default installation of Bloomreach Experience Manager.

Creating 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 XML definition/configuration of the perspective and a Wicket plugin together with its HTML file, its resource bundle. Optionally, the perspective can include a CSS file for styling and an icon that will show up in the main menu on the left side of the CMS.

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>

The perspective's configurations need to be added to the repository. This can be done with a YAML source definition:

my-custom-perspective.yaml

definitions:
  config:
    /hippo:configuration/hippo:frontend/cms/cms-static/myCustomPerspective:
      jcr:primaryType: frontend:plugin
      plugin.class: com.example.MyCustomPerspective
      wicket.id: service.tab
Order of perspectives
The order of the perspectives in the CMS is determined by the order of their configuration nodes under /hippo:configuration/hippo:frontend/cms/cms-static. Change the order by using the .meta:order-before flag in the YAML definition to insert the node at a location relative to another node.

The title of the perspective will be loaded from a compile-time Java resource bundle. For now, we only add the key of the English title ('perspective-title') in the file  cms/src/main/resources/com/example/MyCustomPerspective.properties:

perspective-title=My Custom Perspective

The perspective also needs an icon that will be displayed in the left side of the CMS. The icon should be an SVG that's rendered at 48x48 pixels. The icon should be placed in the same Java package as the perspective, and have the same name but in spinal-case instead of CamelCase. For the example, download  this Hippo icon and save it as  cms/src/main/resources/com/example/my-custom-perspective.svg.

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 start your project. The CMS should now contain a custom perspective that displays "Hello World!".

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:
  cluster.name: hippo-reports
  plugins.class: org.onehippo.cms7.reports.ReportsPerspective
  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?