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 theContent application in which documents, images and assets can be edited, theSetup > 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. Theend 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 theContent 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'sExtensions menu.
Example
Our example perspective will show an empty screen that shows the text "Hello world!". The example will use packagecom.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 filecms/src/main/resources/com/example/MyCustomPerspective.html:
<html xmlns:wicket="http://wicket.apache.org/"> <wicket:panel> <div> 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 afrontend:plugin node to/hippo:configuration/hippo:frontend/cms/cms-static.
Add the mixinfrontend:navigationitem.
Set the mandatory propertyfrontend: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
The order of the perspectives in theExtensions 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
Log in to Bloomreach Experience Manager and your custom perspective should show up in theExtensions menu.
Lazy-Loaded Perspective
Our development team is actively investigating potential solutions. We will provide updates as soon as they become available.
Perspectives can use theCMS 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 propertycluster.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
Thecluster.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.