brXM

# Scaffold a new project from the Hippo/Bloomreach Maven archetype
# (prompts for groupId, artifactId, version, and package)
mvn archetype:generate \
  -DarchetypeGroupId=org.onehippo.cms7 \
  -DarchetypeArtifactId=hippo-project-archetype \
  -DarchetypeVersion=RELEASE

cd my-hippo-project

# Build every module, including compiling repository-data bootstrap content
mvn clean verify

# Start a local Tomcat instance with the CMS and site both deployed
mvn -P cargo.run

The generated project splits into modules the same way an AEM project splits into core/ui.apps: cms and site hold the Java code and HST/Freemarker templates, while repository-data (with application, content, and development submodules) holds the namespaces, document types, and any bootstrap content that gets loaded into JCR on first startup. Re-run mvn clean verify after any change to repository-data to see it reflected on the local instance.

[myproject:article] > hippo:document
- myproject:title (string) mandatory
+ myproject:body (hippostd:html) = hippostd:html

Save this as repository-data/application/src/main/resources/myproject.cnd (or add the lines to an existing project CND), then reference it from that module’s bootstrap YAML so it loads on the next mvn clean verify / mvn -P cargo.run — at that point myproject:article shows up as a creatable document type in the CMS with a title field and a rich-text editor.

For compounds, constraints, and more field types, see the fuller Defining a Document Type (CND) entry in Document & Content Types.

// ArticleComponent.java
public class ArticleComponent extends BaseHstComponent {

  @Override
  public void doBeforeRender(HstRequest request, HstResponse response) {
    HippoBean document = request.getRequestContext().getContentBean();
    request.setModel("document", document);
  }
}

<#-- article.ftl -->
<#include "../include/imports.ftl">
<article>
  <h1>${document.title?html}</h1>
</article>

Wire ArticleComponent and article.ftl together on a component node under the page’s component configuration, matching them by the template’s ID — that pairing is what every HST component boils down to. Copy this as the starting point for any new page component: rename the class and template, and resolve whatever content the page actually needs in doBeforeRender.

For the full request-to-render path — sitemap matching, a multi-component page tree, and a HippoBean with more than one field — see the fuller HST Components & Templates entry in Channels & Pages.

import org.onehippo.repository.update.BaseNodeUpdateVisitor

class Updater extends BaseNodeUpdateVisitor {

  boolean doUpdate(Node node) {
    node.setProperty('myproject:priority', 'medium')
    return true
  }

  boolean undoUpdate(Node node) {
    throw new UnsupportedOperationException('Updater does not support undo')
  }
}

Paste this into a new updater in the console’s Groovy Updater editor, set its node-set query to whatever it should visit, and run it dry first. It’s deliberately doing the least possible — one unconditional property set — so you’re only ever adding logic on top of a version you already know runs.

For a real query, a property-existence check, and logging, see the fuller Writing a Groovy Updater Script entry in Groovy Updaters & Console.

/content/documents/myproject/news/q3-earnings-report     [hippo:handle]
  /q3-earnings-report                                     [myproject:newsdocument]
    hippostd:state: unpublished
    myproject:title: "Q3 Earnings Report (draft edit)"
  /q3-earnings-report                                     [myproject:newsdocument]
    hippostd:state: published
    myproject:title: "Q3 Earnings Report"
    myproject:date: 2026-07-15T00:00:00.000Z

Editors and links always point at the handle, never at a variant directly — that is what makes it possible to publish a new draft without breaking every reference to the document. The repository resolves which variant to actually return based on who’s asking: the CMS shows the unpublished/draft copy to an editor, while the site or Delivery API serves the published one.

Namespace URI:  http://myproject.org/nt/2.0
Prefix:         myproject

myproject:newsdocument      <- registered under /hippo:namespaces/myproject
myproject:address
myproject:title
myproject:date

hippo:document              <- core brXM namespace, never edited directly
hippostd:relaxed            <- mixin: allows undeclared child properties

Every custom node and property name is prefix:localname, and the prefix is what keeps myproject:title distinct from another project’s otherapp:title living in the same repository. Namespaces are versioned together with the CND that defines them — reloading a changed CND bumps the namespace version and brXM handles migrating existing content nodes to match.

[myproject:newsdocument] > hippo:document, hippostd:relaxed
  orderable
- myproject:title (string) mandatory
- myproject:summary (string)
- myproject:date (date) mandatory
+ myproject:body (hippostd:html) = hippostd:html
+ myproject:image (hippogallerypicker:imagelink) = hippogallerypicker:imagelink

The - prefix declares a single-value property, + a child node — which is how a rich-text field (hippostd:html) or an image picker ends up modeled as a node rather than a plain string. Loading this CND into the project’s namespace regenerates the document’s edit form in the CMS and its matching HST bean, so the type definition stays the single source of truth for both.

New to writing a document type? See the New Document Type Starter in Starter Templates for the minimal version — a title and a body, nothing else — before adding compounds and constraints.

[myproject:address] > hippo:compound
- myproject:street (string)
- myproject:city (string)
- myproject:zipcode (string)

[myproject:newsdocument] > hippo:document, hippostd:relaxed
+ myproject:location (myproject:address) = myproject:address
- myproject:priority (string)
  < 'low','medium','high'

myproject:address has no identity of its own outside the document that embeds it — unlike a mirror, a compound’s data physically lives under the parent node and is copied wherever the field is reused. The < 'low',... line is a value constraint: the CMS renders it as a dropdown, and the repository itself rejects any other string on save.

Request: GET /news/2026/q3-earnings-report.html

1. Sitemap match:  news/_any_/_any_.html  ->  page "newsdetail"
2. Page "newsdetail" component tree:
     BaseLayout
       Header       (component: HeaderComponent,     template: header.ftl)
       NewsDetail   (component: NewsDetailComponent,  template: newsdetail.ftl)
                    content resolved from URL to:
                    /content/documents/myproject/news/q3-earnings-report
       Footer       (component: FooterComponent,     template: footer.ftl)
3. NewsDetailComponent#doBeforeRender() loads the HippoBean, request.setModel("document", bean)
4. newsdetail.ftl renders ${document.title}, ${document.body}

Each component in the tree is independent — it resolves its own content and populates its own template model — which is what lets the header and footer stay identical across every page while only the middle component changes per sitemap match. doBeforeRender() is the one method most component classes actually implement.

Writing your first component? Start with the plain HST Component Starter in Starter Templates — one class, one template, one field — and grow it into a tree like the one above once you actually need more than one component per page.

GET /site/api/documents/news/2026/q3-earnings-report

{
  "id": "3f2a1c9e-88b1-4e11-9a0d-6a9d2b7c1234",
  "name": "q3-earnings-report",
  "displayName": "Q3 Earnings Report",
  "content": {
    "myproject:title": "Q3 Earnings Report",
    "myproject:date": "2026-07-15T00:00:00.000Z",
    "myproject:body": { "value": "<p>Revenue grew 12% year over year...</p>" },
    "myproject:image": { "$ref": "/content/gallery/2026/q3-chart.png" }
  }
}

The response mirrors the document type’s own field names, so a front end consuming it needs to know the content model but nothing about the repository underneath. A $ref is not the linked data itself — it’s a pointer the client (or the SPA SDK, for page-model requests) resolves with a follow-up call, the same way a mirror node resolves separately in the JCR.

import org.onehippo.repository.update.BaseNodeUpdateVisitor
import org.hippoecm.repository.util.JcrUtils

class Updater extends BaseNodeUpdateVisitor {

  boolean doUpdate(Node node) {
    if (!node.isNodeType('myproject:newsdocument')) return false
    if (!node.hasProperty('myproject:priority')) {
      node.setProperty('myproject:priority', 'medium')
      log.info "Set default priority on ${node.path}"
      return true
    }
    return false
  }

  boolean undoUpdate(Node node) {
    throw new UnsupportedOperationException('Updater does not support undo')
  }
}

The updater is configured with a query — often a node-type query like //element(*, myproject:newsdocument) — and doUpdate only ever sees nodes that query returns, so most of the real design work is picking a query that’s neither too broad nor too narrow. undoUpdate is usually left unimplemented; the safer rollback plan is almost always a repository backup taken before running the updater for real.

New to writing an updater? See the Groovy Updater Starter in Starter Templates for the bare skeleton — no query logic, one unconditional property set — before adding the node-type check and logging shown here.

[myproject:newsdocument] > hippo:document, hippostd:relaxed
+ myproject:related (hippo:mirror) = hippo:mirror multiple

/content/documents/myproject/news/q3-earnings-report
  myproject:related                    [hippo:mirror]
    hippo:docbase: "3f2a1c9e-88b1-4e11-9a0d-6a9d2b7c1234"

hippo:docbase stores the target’s UUID rather than its path, which is the detail that makes mirrors durable — the linked document can be renamed or moved to a different folder and the reference still resolves. That makes a mirror the right choice for “related article” or “author” style references to a shared document, while a compound is the right choice when the data genuinely belongs to and travels with the document that holds it, like an address or a single quote block.