Best practices for content modelling

Pages

We can model page content models in three different ways depending on the context and the needs of the page you are trying to build.

Templated pages have a static page structure, only allowing authors to edit content in predefined areas on the page. This makes editing really simple but gives the author no control over the layout of the page. An example of this might be a blog post page, where the layout is fixed, and only the title, blog content, and authors need to be inputted by the content author.

An example of a templated blog post page in Sanity. The page only contains predefined fields in enter in authors, summary and blog content. It gives content author no ability to add in additional components or reorder the layout.

Non-templated pages are fully customizable, enabling the author to pick components and rearrange the order of the layout. This provides a lot of flexibility but comes with a high degree of complexity and design choices.

An example of a non-templated page on Contentful. The page is made up entirely of components that content authors can select and rearrange.

Alternatively, hybrid pages specify some fixed content and allow some specific sections of the page to be dynamic and reordered. This is the most common type of page content model we encounter. It gives the content author the right amount of flexibility without being too complex or tedious to edit.

An example of the static hero editorial component on a hybrid home page on Sanity.

An example of the dynamic section on the same hybrid home page.

How to determine what to use

The right type of page content model is entirely dependent on your use case. To determine what is the best strategy will require you to look at the page you are trying to model and answer a few questions.

Is the layout of this page or this type of page always the same? If yes, templated page. Are there parts of the page that is fixed on the layout? This could be something like a standard header or call to action. If yes, hybrid page; if no, non-templated page.

Page modules

There are two types of page modules that we model: reusable and global page modules. The way we model them is the same, but they are used differently in our platform.

Reusable page modules, as the name suggests, are meant to be modelled once and used in multiple places with different content. Header, Accordion, and Quote components are good examples of reusable page modules that we can picture appearing on various different pages.

A couple of reusable page modules (e.g., Quote, Logo Grid) being used on a home page in Sanity.

Global page modules are modelled and used once for the entire site. They contain content that only needs to be defined once and are not unique per page. Navigation and Footer are good examples since they tend to be the same on every single page. With global page modules, we won’t ever see them referenced in any other content models and will live at a global level.

Global page modules (navigation and footer) set up in Sanity. They are not used within any other pages and are organized in the Global folder.

Naming

We give matching field names and prop names to content in a headless CMS and properties in a component library, respectively. This is critical for buildComponent to match our JSON files (from a headless CMS) to the appropriate components (from a component library) and dynamically build pages. (More about this in the Connecting content data to front-end components section.)

Notably, there are two kinds of names for a field. There’s a Field ID and a Display Name (actual names vary by headless CMS).

• The Field ID must mirror the component name and is not visible to the content authors.

• The Display Name is what the content author sees in the CMS interface as the name of the content field.

Although teams often use the same name for Field ID and Display Name, this isn’t always the best approach. A name that makes sense to developers might be ambiguous and confusing for authors.

The Display Name and Field ID fields and values in a Quote content model in Contentful.

Mapping

The fields of a page module map to the props of its counterpart component. This doesn’t mean that every prop of a component should be mirrored in the content model. Thinking back to the importance of simplicity and its impact on user experience, we want to only include what's absolutely necessary for content authors. It's better to add more options later, as needed, rather than granting maximum flexibility from the start.

Data objects

We use reference fields to allow authors to add existing content to new content models. This is really useful if a piece of content needs to be displayed in various pages or components and managed in one place. Rather than recreating the same content over and over again, we can create it once and use it anywhere we want. Let’s take a look at an example.

Let’s say we’re building a blog section of a website, and we want to be able to show the authors' information on all of our blog post pages. For those of you who are familiar with relational databases, the relationship between authors and blog posts can be viewed as a many-to-many relationship. For a given blog post, we can have any number of authors; similarly, any given author could have written any number of blog posts.

Rather than creating an author (or authors) every time we create a new blog post, we want to be able to reference them from a preexisting set of authors. Then, at a later date, we are able to easily change the author’s profile image, for example, in a single location and have that change be reflected on all of the blog posts.

A list of authors created through the Author content model in Sanity.

An existing “Author” content (Shawn Griffiths) is referenced in a blog post