How to structure your content

Introduction

Goal

Structure your content using best practices in order to optimize performance, maintainability and usability.

Background

The choices you make when designing your content structure can have a significant impact on the systems performance, maintainability and usability. Once the system is in use, it can be very hard to change the content structure. This document describes some best practices for modeling and structuring your content.

Content Model

A good indicator of the quality of your content model is the complexity of the queries needed to implement the delivery components.

A common pitfall for content modeling using hierarchical structures is that you have implicit information about the nodes (documents) stored in the containing folders.

If you want to avoid complex queries and want to fully utilize faceted navigation, try to stick to this really simple rule of thumb:

This also implies that properties that you want to use to, for example, sort on or create faceted navigation from, cannot be properties that are part of a child node (e.g. a compound block) of your document. These properties must be stored directly on the document node itself.

Avoid creating a content structure where the folder node contains metadata of the documents it contains. For example, if you want to create a content model with documents about a product (Bloomreach Experience Manager) of a company (BloomReach), one possible structure is as follows:

If you model your content as shown above, you will end up writing mostly inefficient and hard to maintain queries in your delivery components.

Instead, try creating the model like this:

In this case, the document property company stores the information about the document, thereby making it independent of the content structure.

If you want access control based on folders (e.g. restrict document about Bloomreach products to Bloomreach employees only), you may want to model it as follows:

• Products (folder)

  • Bloomreach (folder)

    • Bloomreach Experience Manager (company = Bloomreach)

But in any case, try to keep the company property. This will give you all the features of faceted navigation. Even if you don't use faceted navigation, adhereing to these simple rules will result in much cleaner frontend code.

Respect the Document Model Node Type Hierarchy

As explained in the document model, child nodes of a hippo:handle node are the document variants and are of type hippo:document. Many functionalities in Bloomreach Experience Manager rely on this node type hierarchy, therefore it should not be modified. For example, a document variant node in turn can have other descendant nodes, but those descendant nodes should never be of type hippo:document.

Number of Items in a Folder

The number of items (documents, subfolders) in a single folder can affect performance. In general, the more items in a folder, the more time it costs to retrieve the contents of the folder (e.g. to display them in the folder listing in the CMS). Apart from the negative impact on performance, this can also cause a less than optimal user experience as users have to scroll through endless lists of documents to find the one they are looking for.

As a general rule of thumb:

The easiest way to achieve this is by using an hierarchical folder structure, for example storing news articles not just in a folder "News", but additionally in subfolders reflecting the year and month:

News (folder)

• 2023 (folder)
  • 12 (folder)
    • Boxing Day Sale (news article)
    • New Year's Eve Special (news article)
  • 11 (folder)
    • Thanksgiving (news article)

This way you never have more than 12 month folders per year, and you're good for a century of year folders. If you publish more than 100 news articles per month you could create subfolders for days of the month as well.