Prerequisites

These instruction assumes that you have Maven based build for your project.

Add the Forge repository configuration

In the main pom.xml of the project, in the repositories section, add this repository if it is not configured there yet.

    <repository>
      <id>bloomreach-forge</id>
      <name>Bloomreach Forge Maven 2 repository.</name>
      <url>https://maven.bloomreach.com/repository/maven2-forge/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <updatePolicy>never</updatePolicy>
      </releases>
      <layout>default</layout>
    </repository>
        

Add version property to the project pom

In the main pom.xml of the project, in the properties section, add this property. For the correct version number, check the Release Notes page.

    <bloomreach.forge.iframeperspective.version>version.number</bloomreach.forge.iframeperspective.version>
        

Maven Dependency

Make sure you have the dependency definition in the root pom.xml of your project:

<dependencyManagement>
  <dependencies>

    <dependency>
      <groupId>org.bloomreach.forge.iframeperspective</groupId>
      <artifactId>iframeperspective</artifactId>
      <version>${bloomreach.forge.iframeperspective.version}</version>
    </dependency>

  </dependencies>
</dependencyManagement>
        

Add the following dependency to either cms-dependencies/pom.xml or cms/pom.xml in the earlier versions that don't have that:

  <dependencies>

    <dependency>
      <groupId>org.bloomreach.forge.iframeperspective</groupId>
      <artifactId>iframeperspective</artifactId>
    </dependency>

  </dependencies>
        

Add the plugin configuration to the repository

To add an IFrame based perspective configuration, add configuration nodes to the /hippo:configuration/hippo:frontend/cms/cms-static/ node in the repository. In the following example two IFrame based perspectives are added.

Version 8.0.1 introduces lazy-loading option, which loads perspective URL only when perspective is selected (instead of when user logins into the CMS).

Version 8.0.1 also introduces a new boolean property called reload-on-activate, which, when set to true reloads Iframe when perspective is selected again.

definitions:
  config:
    /hippo:configuration/hippo:frontend/cms/cms-static:
      /example-iframe-perspective:
        jcr:primaryType: frontend:plugin
        jcr:mixinTypes: ['frontend:navigationitem']
        frontend:appPath: example-iframe-perspective
        hipposys:userrole: xm.cms.user
        plugin.class: org.bloomreach.forge.iframeperspective.IFramePerspective
        wicket.id: service.tab
        iframe.src: https://bloomreach-forge.github.io/
      /example-iframe-perspective-second:
        jcr:primaryType: frontend:plugin
        jcr:mixinTypes: ['frontend:navigationitem']
        frontend:appPath: example-iframe-perspective-second
        hipposys:userrole: xm.cms.user
        plugin.class: org.bloomreach.forge.iframeperspective.IFramePerspective2
        wicket.id: service.tab
        iframe.src: https://bloomreach-forge.github.io/iframe-perspective/
      /example-lazy-iframe-perspective:
        jcr:primaryType: frontend:plugin
        jcr:mixinTypes: ['frontend:navigationitem']
        frontend:appPath: example-lazy-iframe-perspective
        hipposys:userrole: xm.cms.user
        plugin.class: org.bloomreach.forge.iframeperspective.LazyIFramePerspective
        wicket.id: service.tab
        iframe.src: https://bloomreach-forge.github.io/iframe-perspective/
        reload-on-activate: false
        

Note: each perspective must have unique, mandatory frontend:appPath property. See also Create a Custom Perspective page for more detail.

Note: the CMS UI does not support multiple custom perspective plugin configurations with the same plugin.class property value. That's why the second example shown above is set to use org.bloomreach.forge.iframeperspective.IFramePerspective2 or org.bloomreach.forge.iframeperspective.LazyIFramePerspective2 instead. For convenience, this project provides 9 different class names for the same feature (org.bloomreach.forge.iframeperspective.IFramePerspective2 ~ org.bloomreach.forge.iframeperspective.IFramePerspective10 and org.bloomreach.forge.iframeperspective.org.bloomreach.forge.iframeperspective.LazyIFramePerspective2 ~ org.bloomreach.forge.iframeperspective.LazyIFramePerspective10 ). This allows developers to avoid adding a custom class extending org.bloomreach.forge.iframeperspective.IFramePerspective in their projects.

Also, the translation key-value pairs for each perspective must be added to /hippo:configuration/hippo:translations/hippo:navigation/navigationitem like the following example:

definitions:
  config:
    /hippo:configuration/hippo:translations/hippo:navigation/navigationitem/displayName/en:
      example-iframe-perspective: Example IFrame Perspective
      example-iframe-perspective-second: Example IFrame Perspective 2nd
        

Note: The translation keys must be the same as the frontend:appPath property values. See the Create a Custom Perspective page for further detail.

Plugin Configuration Details

You can configure the followings:

Add another value to the existing frame-src property

Add another value i.e. "bloomreach-forge.github.io" to the frame-src property of the /hippo:configuration/hippo:modules/application-settings/hippo:moduleconfig/content-security-policy node in the repository.

definitions:
  config:
    /hippo:configuration/hippo:modules/application-settings/hippo:moduleconfig/content-security-policy:
      frame-src:
        operation: add
        value: [bloomreach-forge.github.io]