Fork me on GitHub

How to install the IFrame Perspective Plugin

Note: to install this plugin in Bloomreach Experience Manager 13 or earlier, follow How to install in brXM 13 or earlier page.

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. 

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 Default 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.

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]