Milestone 2: Create a Frontend App - Bloomreach Commerce Experience Cloud - The Headless Digital Experience Platform Built for Commerce

Milestone 2: Create a Frontend App

< Milestone 1: Create a Channel

Milestone Overview

Goal

Create a frontend app to render the channel you created in milestone 1.

Estimated Time to Complete

5-10 minutes

Summary

In this milestone, you will take the Delivery API output for the channel you created in the previous milestone and use the Bloomreach SPA SDK to create your own frontend app that consumes the API output and renders the channel as a website.

The code examples on this page are for a React-based frontend app. You can find Angular and Vue versions of the example app, as well as the full React app, in our Github repository.

A Brief Look at the Delivery API Response

Bloomreach Headless Experience Manager provides a Delivery API for frontend applications to retrieve channel and page data. The API's Pages endpoint provides all the data needed to render a particular page including any containers, components, and content items on that page.

The Pages endpoint for your channel's single page can be accessed at a URL of the following format, where [account_name] and [channel_name] should be replaced with the appropriate values:

https://[account_name].bloomreach.io/delivery/site/v1/channels/[channel_name]/pages

For example, if your account is named "trial-1234abcd" and you named your channel "getting started", the URL would be:

https://trial-1234abcd.bloomreach.io/delivery/site/v1/channels/getting-started/pages

Enter the API URL in your browser and have a brief look at the JSON response. It contains a lot of objects including the page and a flattened hierarchy of containers and components on the page. You don't have to understand everything yet at this point but can you match some of the objects in the JSON data with the page elements you see in the Experience manager preview?

See Page JSON Representation in the Delivery API reference documentation for a full description of the data format.

Create a Frontend App

Now that you have created a channel channel and can retrieve a page from the Delivery API, it is time to create a frontend application that can consume the API response and render the page.

Create a new React app using the following command:

npx create-react-app my-react-content-app

To simplify integration with Javascript-based frontend applications, Bloomreach provides an SPA SDK that interacts transparently with the Delivery API and exposes a simplified and framework-agnostic interface to the API's data model. You'll be using the SDK to build up your frontend app.

Use the following command to install the SDK libraries as well as the axios library:

cd my-react-content-app
npm install @bloomreach/spa-sdk @bloomreach/react-sdk axios

The above npm install command may result in error messages related to incompatible dependencies, due to the current create-react-app using newer versions than the current Bloomreach SDKs. In that case, use the following command to install older, compatible versions and try the above command again:

npm install [email protected] [email protected] [email protected] @testing-library/[email protected]

Open src/App.js in your favorite editor and change its contents to the following:

src/App.js

import logo from './logo.svg';
import './App.css';
import axios from "axios";
import { BrPage } from "@bloomreach/react-sdk";
import { Content } from "./components/Content";

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <BrPage configuration={{
          endpoint: 'https://trial-1234abcd.bloomreach.io/delivery/site/v1/channels/getting-started/pages',
          httpClient: axios
        }} mapping={{ Content }}>
        </BrPage>
      </header>
    </div>
  );
}

export default App;

Study the code above and note the following:

  • The BrPage element (imported from the SDK) is a placeholder in your frontend application which will render components in the page's JSON representation as returned by the Delivery API.
  • The endpoint property specifies the URL of the Delivery API's Pages endpoint (make sure to update the URL to reflect your Headless Experience Manager account!).
  • The mapping property maps your React components their counterparts in the JSON representation.
  • A Content component (which you will implement in a moment) is imported and mapped.
Make sure to modify the endpoint URL in the code to reflect your Headless Experience Manager account!

In the src folder, create a subfolder called components and inside it, create a file Content.jsx with the contents below. This is will be the frontend implementation of the "Content" component you added to the page in the previous milestone.

src/components/Content.jsx

export function Content({ component, page }) {

  const document = page.getDocument();

  const { title, content, introduction } = document.getData();

  return (
    <div>
      <h1>{title}</h1>
      <p>{introduction}</p>
      <div dangerouslySetInnerHTML={{ __html: content.value }} />
    </div>
  );
}

At this point, you are ready to launch your app using the following command:

npm start

This will load the app in your browser (at http://localhost:3000/) and if everything went well you should see the following page:

Congratulations, you created your first frontend app for Headless Experience Manager!

Now go back into the Experience manager application and make some changes to the content (see milestone 1 for instructions, don't forget to publish!) and refresh the frontend app to see the updated content.

Full Code

Find the complete code for milestone 2 in React, Angular, and Vue in Github:

https://github.com/bloomreach/content-getting-started/tree/Milestone_2_Create_a_Frontend_App

Next

Now that you have created a channel and a frontend app, your next step is to set up a development project and configure it to use your frontend app to render the preview.

Milestone 3: Set up a Development Project >

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?