Mike Reynolds

Jun 30, 2021

Getting started with Bloomreach Content

We have launched ‘Bloomreach Content’ - our SaaS Content Management platform and this post aims to help you, our developers to get started.  Note - there is also a wealth of content and tutorials available over on our documentation website

Before we Begin

First, you will need access to a Bloomreach Content environment. If you or your organization have signed up for the Bloomreach Content module, and a user account has been created for you, then you should have received a password reset email. Once you’ve set your password, you should be able to login to your Bloomreach Content environment.

If you want to be able to make changes to the front-end code then you need to download the React Reference App from GitHub.

The reference app uses the Bloomreach React SDK to connect to a Bloomreach Content environment for the editing and delivery of the experience. As a developer, you will be able to run the reference app on your local machine and connect it to your Bloomreach Content environment to see how your changes will be used by content managers in the system. 

Signing In For The First Time

Signing into the Content Module interface for the first time will bring you to the Home screen. From here you can see the activity stream and any pending requests for content reviews and approvals.

The first thing you’ll want to do is open the Experience Manager perspective by clicking the second icon in the navigation strip on the left side of the window. (It’s the one that looks like a circular play button).

This is the perspective that business users use to manage pages (and to iterate on documents / pages / products / search) and will be used, by you, to preview the changes you make to your front end code.

The default view of the Channels perspective displays a list of the channels that have been created in the system. (A channel is an endpoint, a website, a region or essentially whatever you configure it to be.) Assuming this is a new instance, you should see only one channel listed, BrX SaaS:

Clicking on the icon for the channel will launch the editing interface:

 

Bloomreach hosts a copy of the reference app so you can get a feel for the editing experience. Within the edit interface you can preview the sample site and can make changes to pages, content and components it uses. You can even  publish your changes but you will not be able to view them on the “live” site since it is shared. 

While the concept of previewing and editing a React app inside Bloomreach Content is amazing, I’m sure you’re probably more interested in making changes to the code and you want to know if you can do that without standing up servers or installing tunnelling software. No worries. All you need is a local instance of the reference app and a Development Project created in your Bloomreach instance.

Starting The Reference App

If you haven’t already downloaded the code for the React Reference App then you should do it now. Follow the instructions in the README.md to create a .env file, copying the .env.dist file and updating it with the domain for your Bloomreach Content environment. (Sample entry below)

REACT_APP_BRXM_ENDPOINT=https://<your_account>.bloomreach.io/delivery/site/v1/channels/brxsaas/pages

Save the changes to your .env file, then build and run the React app using the following commands

yarn
yarn start

The app should open a new browser window and load the Pacific Nuts & Bolts site with the content and configuration for the core version of the BrX SaaS channel in your Bloomreach Content environment. Any changes that have been made to the core version of the BrX SaaS channel will also be visible in your local instance. 

Getting Into The (Pacific) Nuts & Bolts

Projects allow developers to work on changes to channels in their Bloomreach Content environment without impacting business users. When you create a Development Project, it makes a separate branch in the underlying repository, similar to a code branch, which gets merged back into the core channel configuration when complete.

To create a new Development Project, click the Projects icon in the navigation strip on the left side of the window. (It’s the one that looks like a clipboard.) This will open the Projects perspective for your instance, which should look pretty empty. To add a new project, click the blue  + Project button in the top right corner of the screen. 

In the New project screen enter a Project name for your project, check the Development project checkbox, and click the Create button in the top right-hand corner. (Don’t worry about the Includes document type changes checkbox for now) After creating the project, you will be taken to the project details view. 

On the Project details screen, click the + Channel button in the top right corner of the Channels tab for your project and select the BrX SaaS channel in the pop up window. After the channel is added to the project, click the Gear icon, located on the right-hand side of the row, to manage the channel settings. In the modal window, select the third radio button, enter:

http://localhost:3000

in the text field and click the Set button. Your project is now configured to use the React app running on your local machine for previewing your changes made in your development project.

Click the BrX SaaS channel from your Projects perspective. You should be taken to the Experience Manager perspective and at the top of the preview window you should see the text: “For project: <your project name> (In progress)”.

Modifying A Component

Now that you have your project created, and connected to a local instance of the reference app, you can make, and review, changes to the reference app. To demonstrate this, you’ll update the Single-Banner Carousel component that appears on the Pacific Nuts & Bolts homepage. 

The code  for the SingleBannerCarousel component can be found under the src/components folder in the reference app. Inside the component folder there is a Banner.tsx file that contains the display logic for each banner in the carousel. In the Banner.tsx file, remove following code block and save the file:

{content && (
  <div
    className={`${styles.banner__contents} d-inline-block mark mt-1`}
    dangerouslySetInnerHTML={{ __html: page?.rewriteLinks(content.value) ?? '' }}
  />
)}

Return to the Experience Manager perspective in your browser and make sure you are still viewing your development project. Click the Tray Slideout icon in the top left corner of the screen to open the Sitemap and Components tray, then click the home link in the Sitemap to reload the homepage and verify that the content block you removed is not shown.

While still in your development project, edit the title of one of the banners by clicking the orange Edit Content button and adding it to your project. After saving your changes you should see them reflected in the carousel. 

To confirm that your changes only exist in your development project, switch to the Core project by selecting it from the For project dropdown at the top of the preview panel. When the preview panel reloads, you should see the original banner content with the original template.

The content, and the reference app, used by the Core branch are unaffected by the changes in your development branch and your local code.

In Conclusion

In this article, we got up and running with Bloomreach Content in under 3 minutes and we went on to build out a developer workflow.

Next up, There is an amazing tutorial available here which will helps you to get going with your own local SPA.