Hello World

Hands-On Introduction to Bloomreach Content Core Concepts

This tutorial demonstrates fundamental concepts in Bloomreach Content, focusing on the delivery tier (HST). You will build a basic "Hello World" example to see how the Model-View-Controller (MVC) pattern is used to render pages in a Bloomreach Content website.

This guide is intended for Java developers seeking a practical introduction to Bloomreach Content development. Anyone with basic Java skills and access to an IDE can follow these steps.

About the Essentials Setup Application and Feature Library

Bloomreach Content includes an Essentials setup application and a feature library with prebuilt features to accelerate project setup. This tutorial does not use Essentials. Instead, you will implement a simple Hello World page from scratch to understand the underlying mechanics.

Note: To learn how to use Essentials and build a website with out-of-the-box features, see the Get Started and Build a Website tutorials.

Static Hello World Example

You will first create a static Hello World page served by Bloomreach Content. This section covers adding a Freemarker template and configuring the system to use it.

Step 1: Create a New Project

Ensure your development environment meets the prerequisites.

Generate a new Bloomreach Content project using the Maven archetype as described in Create the Project.

After generating the project, open it in your preferred IDE. See Eclipse or IntelliJ for guidance.

Step 2: Build the Project

Compile and run the project with Maven:

mvn verify
mvn -Pcargo.run

This process creates WAR files and starts the project using Cargo. The initial build may take time as Maven downloads dependencies.

Step 3: Add a Freemarker Template

In your IDE, navigate to repository-data/webfiles/src/main/resources/site. Create a freemarker folder, then a home folder inside it. Add a file named home.ftl with the following content:

repository-data/webfiles/src/main/resources/site/freemarker/home/home.ftl

<html>
    <head>        
    </head>
    <body>
        <h1>Hello World </h1>
    </body>        
</html>

Note: Placing the Freemarker template in the web files module enables automatic reloading on modification, which speeds up development.

Step 4: Access the Console

Open the Console at http://localhost:8080/cms/console and log in with the default credentials: admin / admin.

The Console provides direct access to the content repository, displaying all data—including content and configuration—as JCR nodes in a tree structure. Selecting a node allows you to view and edit its properties. Each node has a type defining its properties and child nodes, similar to how an XML schema defines elements and attributes.

For this tutorial, you will work in the delivery tier configuration section under the hst:myproject/hst:configurations node, which holds your website's configuration.

Step 5: Configure the Template

Configure Bloomreach Content to use your new template:

  1. In the Console, navigate to /hst:myproject/hst:configurations/myproject.

    Bloomreach console showing hst:configurations myproject node details

  2. Select the hst:templates node.

  3. Add a child node named homepage of type hst:template.

  4. Add a property named hst:renderpath with the value webfile:/freemarker/home/home.ftl.

/hst:myproject/hst:configurations/myproject/hst:templates:
  /homepage:
    jcr:primaryType: hst:template
    hst:renderpath: webfile:/freemarker/home/home.ftl


![Console dialog for adding hst:renderpath property to homepage template](https://xmdocumentation.bloomreach.com/binaries/original/content/gallery/connect/trails/hello-world/13.0/add-template-property.png)

Step 6: Add a Page Component

The delivery tier uses a hierarchical Model-View-Controller pattern. Each page is a hierarchy of MVC components. So far, you have created a view (the Freemarker template). You will now configure a page with a single MVC component using only a view.

  1. Select the hst:pages node.
  2. Add a child node named home of type hst:component.
  3. Add a property hst:template with the value homepage.
/hst:myproject/hst:configurations/myproject/hst:pages:
  /home:
    jcr:primaryType: hst:component
    hst:template: homepage


![Console dialog adding hst:template property with homepage value](https://xmdocumentation.bloomreach.com/binaries/original/content/gallery/connect/trails/hello-world/13.0/add-page-property.png)

Step 7: Configure the Sitemap

Map a URL to your page using the sitemap:

  1. Select the hst:sitemap node.
  2. Add a child node named root of type hst:sitemapitem.
  3. Add a property hst:componentconfigurationid with the value hst:pages/home.
/hst:myproject/hst:configurations/myproject/hst:sitemap:
  /root:
    jcr:primaryType: hst:sitemapitem
    hst:componentconfigurationid: hst:pages/home

Step 8: Persist Changes

Click 'Write changes to repository' in the Console to save your configuration.

Open http://localhost:8080/site/ to view the Hello World page:

Browser showing localhost site with Hello World heading

Dynamic Hello World Example

The previous example used a static template. In this section, you will extend the example to render content managed in Bloomreach Content.

Step 1: Create a Document Type

Bloomreach Content separates content from presentation. Content is stored in documents with defined structures, making editing straightforward and reusable.

To create content, define a document type using the CMS document type editor:

  1. In the CMS, open the Content application.

  2. Select Document Types from the dropdown in the top left.

  3. Choose the myproject namespace and select 'New Document Type'.

    Content app showing New document type menu in myproject namespace

  4. Name the document type simpledocument.

  5. Select the 2 column layout for the editing template.

    Document type editor showing title and rich text fields

  6. Add a String field (Primitive) with Caption Title and Path title.

  7. Add a Rich Text Editor (Compound Field) with Caption Content and Path content.

  8. Click Done, then select Type Actions > Commit to finalize the document type.

Step 2: Create a Document

  1. Select Documents from the dropdown in the top left.

  2. Add a new document to the 'My Project' folder.

    New document dialog with name, URL name, and document type

  3. Name the document 'Hello World'. The URL name field generates a URL-friendly version for use as the filename.

  4. Click OK to open the document editor, which displays the fields you configured.

    Bloomreach document editor showing Hello World title and content fields

  5. Enter content in the fields and click Done.

  6. In the Publication menu, select Publish to make the document available to the site.

Step 3: Create a Model

In Bloomreach Content, models are implemented as content beans: Java objects that wrap content stored in JCR nodes. Each document type requires a corresponding content bean class extending org.hippoecm.hst.content.beans.standard.HippoBean.

For most document types, including your simple document, content beans are dynamically generated. No manual implementation is needed in this case.

Step 4: Create a Controller

Controllers in the delivery tier are Java components that retrieve content and prepare it for the view.

  1. In your IDE, create a new Java class in the site-components module, package org.example.components, named SimpleComponent.
  2. Add the following code:

site/components/src/main/java/org/example/components/SimpleComponent.java

package org.example.components;

import org.hippoecm.hst.component.support.bean.BaseHstComponent;
import org.hippoecm.hst.content.beans.standard.HippoBean;
import org.hippoecm.hst.core.component.HstComponentException;
import org.hippoecm.hst.core.component.HstRequest;
import org.hippoecm.hst.core.component.HstResponse;
import org.hippoecm.hst.core.request.HstRequestContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class SimpleComponent extends BaseHstComponent {

    public static final Logger log = LoggerFactory.getLogger(SimpleComponent.class);

    @Override
    public void doBeforeRender(final HstRequest request, final HstResponse response) throws HstComponentException {
        super.doBeforeRender(request, response);
        final HstRequestContext ctx = request.getRequestContext();

        // Retrieve the document based on the URL
        final HippoBean document = ctx.getContentBean();

        if (document != null) {
            // Put the document on the request
            request.setAttribute("document", document);
        }
    }
}

The doBeforeRender method retrieves the content bean from the request context, based on the URL, and stores it as a request attribute for the view to access.

Step 5: Update the View for Dynamic Content

Modify the Freemarker template to render content from the model:

repository-data/webfiles/src/main/resources/site/freemarker/home/home.ftl

<#assign hst=JspTaglibs["http://www.hippoecm.org/jsp/hst/core"] >
<html>
<head>
</head>
<body>
  <#if document??>
    <h1>${document.title?html}</h1>
    <div>
      <@hst.html hippohtml=document.content />
    </div>
    <#else>
      <h1>Goodbye? cruel world</h1>
  </#if>
</body>
</html>

This template uses Bloomreach Content-specific tags from the HST tag library. The <@hst.html> tag processes the Rich Text field, validating and rewriting internal links as needed.

After updating the template, stop, rebuild, and restart the project:

mvn verify
mvn -Pcargo.run

Step 6: Configure the MVC Component

Register the Java component in the Console:

  1. Add a new hst:component node under hst:components named simplecomponent.
  2. Add a property hst:componentclassname with the value org.example.components.SimpleComponent.
/hst:myproject/hst:configurations/myproject/hst:components:
  /simplecomponent:
    jcr:primaryType: hst:component
    hst:componentclassname: org.example.components.SimpleComponent
  1. In hst:pages, select the home node.
  2. Add a property hst:referencecomponent with the value hst:components/simplecomponent.
/hst:myproject/hst:configurations/myproject/hst:pages/home:
  hst:referencecomponent: hst:components/simplecomponent
  hst:template: homepage

Write your changes to the repository.

Visit http://localhost:8080/site/. The page should display the fallback message since the document is not yet mapped:

Browser showing localhost page with “Goodbye? cruel world”

Step 7: Map the URL to the Content

Currently, the template does not receive a document because the model is not mapped. Map the URL to your content:

  1. In the Console, select the hst:sitemap node.
  2. Select the root node.
  3. Add a property hst:relativecontentpath with the value hello-world. Use the 'URL name' from when you created the document. If the document is in a subfolder, use the path format mysubfolder/hello-world.
/hst:myproject/hst:configurations/myproject/hst:sitemap/root:
  hst:componentconfigurationid: hst:pages/home
  hst:relativecontentpath: hello-world

Note: In production projects, use wildcards to map groups of documents instead of mapping each document individually.

Write the changes to the repository and reload the site. The page now renders the managed content:

Browser showing localhost page with Hello, Title and content

Next Steps

Continue with the Build a Website tutorial.

Share Feedback
Page: /build/component-development/hello-world
Section: Build
Category *
Hello World (Tutorial) | Bloomreach Content Documentation