DEV Community: Francisco Araujo

Content Saas | Learning to walk with Bloomreach content SaaS

Francisco Araujo — Fri, 19 May 2023 12:36:39 +0000

Blogs to enjoy before this one

This is Blog number 2 of what I hope will become a Content Saas | Learning to series.
As such, to get a better idea of where we are, you should at least glance at the Content SaaS | Learning to Crawl with Bloomreach Content SaaS Blog.
If any questions come up during this blog, you can check the documentation website or the blog mentioned above.

What will be covered in this blog

So, you have access to Bloomreach Content SaaS and have created a couple of documents and pages. But how do we display something on that page? What if we want to create something a bit more costume?
In this blog, we'll continue working on a fully integrated website and we'll answer the above questions.
We'll start by customizing the Blog page that we created on the previous Blog post.

Learning to walk | How I learned to add components to pages

After you've logged in to your instance of Bloomreach Content SaaS navigate to the Experience Manager tab.

Navigate to the Blog Page. You can do this via the Menu item we created last time or via the Sitemap And Components Button.

Now that we're on the Blog page, we can proceed to add an already existing Component to the page.
But what is a Component? A Component is just a part of the website that can be reused as desired. For example, we could use a Banner with an image and a Title as a Component.

Components are added to Containers.
You can view all containers on a page by clicking the Show Components outlines and content Button button.

To add a Component to the page, click on the Sitemap and Components button. This will display all the Sitemap Items and all the Components. Click on the Component button.

This shows us a list of all available Components, be it Page specific Components or Shared Components.

The only difference between Page Specific Components and Shared components is the way they retrieve the information to display.

Page Specific Components receive arguments directly in the component. This is more direct, but it forces you to rewrite the same information if you want to have the same component with the same fields.

Shared Components require you to provide a document with all the information.

For now, let's simply add a ** Reference SPA Title & text ** single page component to the main container. You can give whatever values you want.
This is the main container as you can see via the name.

The Page should now look something like this.

Then, we click on the components tab.

Learning to walk | How I learned to create my own components

As you might have noticed, there's a limited amount of Components and they can't possibly cover all possible use cases.
This is why Bloomreach Content SaaS enables you to create costume components with virtually unlimited possibilites. From the most basic of components to the most complex.

To create Components, simply click on the Site development tab.

Then, we click on the components tab.

And follow by clicking the +Components Button.

This will show you a tab with a lot of different fields.

The Display Name defines the name that will be displayed in the Sitemap And Components tab.
The ctype field allows us to define the Component Name that the frontend will work refer to.

The Extends field defines what type of component we are going to create.
There are 3 choices for the Extends field.

The base/component field allows us to add a simple component without much background logic.

The ** base/menu** field allows us to create an extra menu component that can be used.

The base/query field allows the component to perform queries in the background.

For now, we will be using the base/component.
Fill in the fields with the following values and then click the Create button.

The base/component field allows us to add a simple component without much background logic.

Now, navigate to the Properties of the newly created component and click the + Property Button.

We will continue by adding a single Title property. This will be used in the frontend to display some text.

We've just created our first component. Currently, it's very simple, but we'll continue to iterate over this component in the following blogs.

Now, if you go back to the Experience Manager, you'll see the component is now available.

Add it to the Right Container on the Blogs page. You'll find that while the component is added you won't see anything.

This is okay for now and will be addressed in the next chapter.

Learning to walk | How I learned to develop the front-end for my own components

So far, we've managed to customize the Blogs page with some pre-existing components and even create our very own costume component.
Now, all that's missing, is adding some frontend logic to the just created component.

First thing, we need to connect our local frontend with the Bloomreach Content SaaS environment.
In this Blog, we are using https://github.com/bloomreach/bloomreach-reference-spa.
You might be using something different and that's okay.
Just make sure to connect the frontend correctly.

In the .env file quickly change the NEXT_PUBLIC_BRXM_ENDPOINT to connect to your environment.
It should be something like this:

NEXT_PUBLIC_BRXM_ENDPOINT=https://<context-path>/delivery/site/v1/channels/<channel>/pages

Finally, in your channel settings make sure to point to the localhost url!

Now that we've set up the frontend, we need to create a component with the exact same name as the component we created.

In the React SPA project, we simply create the component folder in the components folder.

Then, we simply start to write the frontend code.

import React from 'react';
import { ContainerItem, getContainerItemContent } from '@bloomreach/spa-sdk';
import { BrProps } from '@bloomreach/react-sdk';

export function AllBlogsComponent({ component, page }: BrProps<ContainerItem>): React.ReactElement | null {
  if (!component || !page) { return null; }

  if (component.isHidden()) {
    return page.isPreview() ? <div /> : null;
  }

  const { title:parameterTitle } = component.getParameters();

  return (
    <div>
      {parameterTitle && <h1>{parameterTitle}</h1>}
    </div>
  );
}

And finally, we export it in index.ts

export { AllBlogsComponent } from './AllBlogsComponent';

Then, we simply add the export to the App.ts and index.ts.

The final result will look like this.

Conclusions

Congratulations!

Over this blog, we managed to customize the Blogs page with a title and text and we've managed to even create our custom component with whatever frontend code we want.
In the next blog, we will continue by improving the Blog page and further adding complexity to the Component we just created.

Content SaaS | Learning to Crawl with Bloomreach Content SaaS

Francisco Araujo — Fri, 20 Jan 2023 15:18:22 +0000

Blogs to enjoy before this one

This Blog assumes you know what Bloomreach Content SaaS is and that you’ve set up your own developer’s workflow. If not, you can simply start reading the Get Started with Bloomreach Content SaaS blog. This will help you set up an environment where you and your developers can quickly and efficiently start working.
If there are any questions that come up during this blog, you can check the documentation website. It offers a wealth of content and tutorials for all levels which will be sure to help you with any doubts you might have.

What will be covered in this blog

To better structure the learning, we will follow a “learn to walk before you learn to run” approach. We will start by creating basic, but fundamental things, and then moving on to more complex structures. By the end of the learning to crawl section you’ll be able to work with the experience manager, create documents, associate those documents with pages and edit the contents of the menu of those pages.
In the future, there will be more blogs like this one designed to teach you subsequently more complex structures that can be achieved easily with Bloomreach Content SaaS.

Learning to crawl | How I learned the basics of the Experience Manager

So, you have access to the Bloomreach Content SaaS environment with a project ready to be worked on. But how do we get started?  Before work can be done, you need to be familiar with the Experience Manager.
These tool allows the users to view the preview of the page, as well as allowing users to add/edit content to several different pages.

Users can view all the available urls, described as sitemap items in the Sitemap and Contents button.
This items are defined by documents in the content tab and by the routes defined in the site development tab.
You can quickly view the preview of any of these urls by simply clicking on them. When viewing the preview, you’ll have the option to customise the page further by adding components to Containers or by adding Channel Settings. Channel Settings won't be mentioned in this blog, but they will be revisited in future blogs.

The Components Tab allows the users to view the available components. These components can then be added into any page that we want.  The difference between Page-Specific Components and Shared Components is just with the information that they receive.  Simply put, Shared Components receive documents with information that can be shared/used with other components. So two components could point to the one document.  On the other hand, Page-Specific Components receive the arguments directly. So the information can not be shared in different pages.

Learning to crawl | How I learned about documents

The Content Tab allows the users to create and edit documents. Documents are used for a variety of things such as to save information that we want to display or to create pages.  Documents have different types, named Document Types. Different document types allow different types of information.
You can create a document by clicking on the 3 dots next to the folder name. The following menu will appear

If we want to create a new document we simply click the New Document… option.  Once clicked, you must select which Document Type you want, what title to give it, and if you have more than a single project, which project to create it to. By default the Core Project is selected. The Core Project functions as the main branch in the source control. All changes by default will be to the Core Project.

The difference between the Name option and the URL Name option is that the Name option is what is shown to the world. While the URL Name option is what is used internally to reference the document.

When you click the OK button the document will be officially created.

Learning to crawl | How I learned to work with pages

Let’s put everything we learned on the last chapter together by creating a Blogs Page. In this page, we will eventually display all Blogs documents.
To create a page, you simply need to create a document with a Page Document Type.
The first step is to select/create the folder we want to create the page. In this case, a Blogs Subfolder will be created under the Pages Subfolder.

This is achieved by simply clicking the New Reference Spa Page Folder and giving it the Blogs name.

We then click on the Blogs subfolder and select New Page Document.

The Page Layout field simply selects where the containers are. It’s possible you have different options, but any choice works.
We then simply create the document by selecting OK.

We can see then that the Blogs page has been created, but we’re still not done. In the image above, we can see a lot of information being displayed. At first glance we see the Name of the document and a sign next to it. The sign indicates the document’s State. Currently, the document is in a Not Published State.
A document can have 3 states: Not Published, Published, and Published with Changes. Published with changes simply means there are changes that are not yet viewable in the live site, but are available in the preview.

Along with the Name and State. We can see more information about the Blogs document. Such as the Type, when it was Last modified, by who it was created, when it was published and lastly the available Translations.
Once we click on the document, we can see all the information it contains. Your document might contain different info. 

For example, this document contains a title and some metainfo description. It also has an Open Graph Compound which itself contains more information.

You can edit the document by clicking the Edit button at the top menu. Click it.

 You can publish/depublish the document by clicking the Publish Button after you’re done editing. You can see/edit information about the document via the Document Button. Finally, you have the View button. The View button allows you to preview the document.

Congratulations, you’ve just created your first page. We’ll continue by customising the menu.

Learning to crawl | How I learned to edit the menu

In this section, we will add the Blogs menu item. Editing the menu is as simple as going to the Experience Manager and then selecting the menu link button.

Once clicked, a menu will appear where we can add/remove/edit whatever menu options we want.

You can add root menu items and submenu items by simply clicking the +Menu Item button.

Once clicked, a root item will appear.

This Menu Item could then be edited to be whatever we want. We edit the Title of the menu item via the menu field, and we can select the link to an internal page via the internal link option or an external link via the external link option. In this case, we select the document we created in the previous field.
 Note: Don’t forget to select the documents option!

 
In the end, the Blogs menu item has been added and we've linked it to our new page. This allows users to visit the Blogs Page once.

Conclusions

Creating documents and pages are simple but strong tools that allows Users to quickly create visible content and change the way pages look.
We'll continue editing and making more and more complex steps in future blogs.