Milestone 2: Create a Frontend App

📘

Note:

To make the most of this tutorial, acquire our publicly available credentials to log in to a shared developer environment. (This is different from your personal developer trial account credentials that leads you to a private trial environment.)

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.

📘

Note:

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 Content 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?

📘

Note:

See Pages 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 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.

Watch the video below which will give you an overview on how to create a frontend app. This will be followed by commands that you need to use to create a frontend app below the video.

Create a new React app using the following command:

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

❗️

React 17

Our React SDK currently supports React up to version 17 while create-react-app uses the latest React version 18. The generated app requires a few small changes to make it compatible with React 17 and our React SDK.

The create-react17-app github project contains a default Create React App output downgraded from React 18 to 17. Please clone or download the project code instead of using the npx create-react-app command above or, alternatively, manually apply the changes detailed in the relevant commit.

We are working on making our SDK compatible with React 18 and apologize for the inconvenience.

To simplify integration with Javascript-based frontend applications, Bloomreach provides a Bloomreach 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

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 Bloomreach Content 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.

👍

Tip:

Make sure to modify the endpoint URL in the code to reflect your Bloomreach Content 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:

12771277

Congratulations, you created your first frontend app for Bloomreach Content!

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.