Get Started: Development Environment
Out-of-the-box Account Setup
Out of the box, new brX accounts are set up with sample products and sample configuration which are used to validate the correctness of the account setup through a basic “Sample SPA”. This out-of-the-box setup also helps account holders find a working system to start with, and it is intended to provide both regular users and developers with best-practices on how to set up and use brX.
The sample SPA is not actually part of the brX account, it is hosted centrally by Bloomreach. When you access it inside the account’s Experience Manager, the out-of-the-box configuration instructs the Experience Manager to pass a pointer back to the account’s Page Delivery API endpoint to the sample SPA, such that the sample SPA will access the Page Delivery API of your brX account. When you run a copy of the sample SPA locally, you’ll need to make sure to point it to your brX account’s Page Delivery API. The sample SPA’s README contains instructions on how to accomplish this.
Because the sample SPA is using your account’s Page Delivery API, you can already manage your content and page configuration in your brX account and observe the changes through the centrally hosted sample SPA.
Local Frontend Development
An out-of-the-box working SPA is nice to start with, but ultimately, you want your brX account to power your experience. The first step to getting there is to obtain the code of the sample SPA. You can do so by cloning the public git repository:
git clone https://github.com/bloomreach/brx-react-spa
The sample SPA is a React-based, client-side rendered frontend. You can run the sample SPA locally and start changing it, or you can use it as a reference implementation for your own “from scratch” frontend. If you choose to run the sample SPA locally, follow the instructions in the project’s README file. Make sure to run the local SPA over HTTPS in order to make the integration with the brX back-end work.
The sample SPA makes use of Bloomreach’s SPA SDK, which eases the use of the Content module’s Page Delivery API and helps with the integration of your frontend with the Experience Manager, such that brX users can manage aspects of the SPA in the Experience Manager and see a preview of the effect of their changes.
While the SPA SDK eases the use of the Page Delivery API, as a developer you probably still want to understand the capabilities of the Page Delivery API in some detail.
You can access the Page Delivery API for the homepage of the sample “brxsaas” channel at this URL:
While changes to the frontend can be applied and tested in a local, safe setup, changes to the brX account are directly pushed into the cloud. In order to provide a safe way of developing, reviewing and testing such “developer changes” (as opposed to changes made by regular brX users), the Content module makes use of the Projects feature.
We consider two categories of changes to be “developer changes”, i.e. changes only users with developer privileges are authorized to make: channel configuration changes and document type changes. Currently, multiple development projects can contain channel configuration changes but only one development project can contain document type changes.
Projects representing a developer workspace use the following workflow: Developers create a new Development project in brX’s Projects app.
They can then associate the channel(s) they want to change with that Project, in the Project’s Channels tab. Also there (clicking on the cogwheel icon), developers can set up the URL the Experience Manager should load for that channel in the context of that development project. There is a URL for collaborating developers to share, and a URL for individual developers to use. The latter should typically point to a local URL.
Once the channel is associated with the Project, developers can push changes to that channel in the context of that Project, using the Site Management API. The effect of these changes can be seen in the Experience Manager, in the context of the developer project. You do so by navigating to the Experience Manager by clicking on the channel entry in the Projects app.
Please note that, when accessing the local SPA outside of the Experience Manager, the Page Delivery API will return the “live” page model, so you won’t be able to see changes to a Development project there.