Bloomreach

Bloomreach Documentation version

This article covers a Bloomreach Experience Manager version 12. There's an updated version available that covers our most recent release.

Extend / Hippo CMS Plugins / SPA++ / Configure

Configure SPA++

This feature is available since version 12.3.0

Introduction

In order to enable SPA++ features in the delivery tier, you need to configure the path of the Page Model JSON API on a Mount or SiteMapItem(s) to serve the initial SPA page.

If you choose to serve your SPA from a CDN or a node.js server directly, not from our delivery tier web application, then it is not needed to configure a Mount or SiteMapItem to serve the initial SPA page.

Configure the Page Model JSON API

Configuring the Page Model JSON API requires adding a single property, @hst:pagemodelapi, to a virtual host (hst:virtualhost) or mount (hst:mount) configuration node. The value of the property will be the path on which the Page Model JSON API child mount becomes available. For example, if the  @hst:pagemodelapi property is configured like the following on a mount (hst:mount) configuration node (for mount path like /, /myapp, etc.), then the Page Model JSON API mount becomes available automatically at the configured mount path + / + resourceapi. e.g, /resourceapi, /myapp/resourceapi, etc. You don't need to configure the resourceapi mount underneath explicitly.

hst:pagemodelapi = resourceapi

If the @hst:pagemodelapi property is configured on a virtual host (hst:virtualhost) configuration node, all the descendant mounts under the virtual host will get the resourceapi child mount automatically.

Note that the Page Model JSON API child mount becomes available only for the mounts that are mapped (@hst:ismapped=true) and associated with a specific Channel.

Configure SPA Site Mount

When you serve SPAs through our delivery tier web application, not from node.js or CDN directly, you should configure an SPA Site Mount.

Suppose you have a channel which is mapped to a mount (e.g, hst:root or myapp). You can make the mount an SPA Site Mount as in the following example:

/hst:hst/hst:hosts/dev-localhost/localhost/hst:root/myapp:
  jcr:primaryType: hst:mount
  hst:mountpoint: /hst:hst/hst:sites/myapp
  hst:namedpipeline: SpaSitePipeline
  hst:pagemodelapi: resourceapi

First, set @hst:namedpipeline property to SpaSitePipeline for your Single Page Application. A mount with @hst:namedpipeline=SpaSitePipeline will render only the root HST component for a page URL (e.g, /, /news, /news/news1.html, etc.). The resolved root HST component and its rendering template (ftl or jsp) should serve the HTML that fetches your SPA. For example, it could serve something like the following:

<html lang="en">
  <head>
    <title>React App</title>
  </head>
  <body>
    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>
    <div id="root">
    </div>
    <footer>
      <p>&copy; 2018 BloomReach, Inc.</p>
    </footer>
    <script>
      // load React app from local Node server
      $.getScript( "http://localhost:3000/static/js/bundle.js" )
        .fail(function() {
          // fallback to bundled React app in webfiles
          $.getScript( "/site/js/react-example-app.js" );
        });
    </script>
  </body>
</html>

Afterward, your SPA is able to invoke Page Model JSON API on the /resourceapi child mount (e.g, /resourceapi, /resourceapi/news, /resourceapi/news/news1.html, etc.), as configured by the @hst:pagemodelapi property.

You can also change the value of  @hst:pagemodelapi property from the default value (resourceapi) to something else to change the endpoint of Page Model JSON API, but in that case make sure your Single Page Application uses the new Page Model API endpoint.

Configure SPA Channel

There is no difference in configuring an SPA++ Channel from other channels. Please follow the documentations on Channel Manager. However, please note that Channel Manager SPA Integration feature is available only to Bloomreach Experience Manager customers.

Configure CORS Headers

Sometimes, you might want SPAs on an external server to consume JSON resources from Page Model JSON API. For example, you could run an external node.js server for SPAs which needs to consume JSON resources from Page Model JSON API residing on HST delivery tier web application. As those reside in different domains, you will probably need to set additional CORS headers on HST delivery tier web application. HST provides easy ways to configure additional custom response headers including CORS headers on virtual host, mount or even sitemap item level, by setting @hst:responseheaders (string multiple) property. See Hostname Matching, Mount Matching and SiteMapItem Matching pages for details.

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?