Bloomreach IFrame Perspective – How to install the IFrame Perspective Plugin

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>hippo-forge</id>
      <name>Bloomreach Forge Maven 2 repository.</name>
      <url>https://maven.onehippo.com/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.

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/

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 instead. For convenience, this project provides 9 different class names for the same feature (org.bloomreach.forge.iframeperspective.IFramePerspective2 ~ org.bloomreach.forge.iframeperspective.IFramePerspective10). 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:

Property	Example value	Description
iframe.src	http://documentation.bloomreach.org	The initial source of the IFrame element
x-frame-options	SAMEORIGIN	Optionally set X-Frame-Options response header if configured. See https://developer.mozilla.org/en-US/docs/Web/HTTP/X-Frame-Options for details.
content-security-policy	Refer to the specification	Optionally set Content-Security-Policy response header if configured. See https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy and https://www.owasp.org/index.php/Content_Security_Policy for details.
x-content-security-policy	Refer to the specification	Optionally set X-Content-Security-Policy response header if configured. See https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy and https://www.owasp.org/index.php/Content_Security_Policy for details.
x-webkit-csp	Refer to the specification	Optionally set X-Webkit-CSP response header if configured. See https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy and https://www.owasp.org/index.php/Content_Security_Policy for details.
iframe.*		If there is any property with name starting with 'iframe.', then the remaining part after 'iframe.' will be added as an additional attribute of the iframe element. For example, if you add 'iframe.name' with value, 'myiframe', then the iframe will have `name="myiframe"` HTML attribute.