Related product pages

#Overview

Product Page model - Book

This guide shows how to create interconnected Product models for an online bookstore with Product information stored in the CMS.

Whether you decide to use an external PIM as the source of truth for your product information and copy/paste the information in Hygraph or create and store all of your product information in the CMS only, this recipe shows an efficient way to combine schema elements to create a set of connected product pages that contain basic product information about books, authors, and genres, and use reference fields to allow users to navigate the linked data.

This mock image shows what a frontend using this setup could look like:

Product Page mock image

#Prerequisites

• REQUIRED: You need to have a Hygraph account. If you don't have one, you can sign up here.
• REQUIRED: You need to have a Hygraph project. Look into the following section to learn more about your options.

#What you can do

Use this guide to create a Product Page model. You have two options:

• OPTION 1: Create a project. This is the way to go if you want to follow the entire tutorial for learning purposes.
• OPTION 2: Use an existing project of yours. This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

#Not in the mood to start building?

Clone the entire cookbook

This is the way to go if you're curious about how we built the Product Pages but don't want to follow the step-by-step creation process. This project contains the entire Product Page Cookbook so you can compare recipes or look into what instances they contain.

#Core concepts

In this guide, you'll work with different schema elements to create a Product Page model. Let's look into them:

• Model: Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
• Component: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
• Basic component field: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A basic component field can only have one component attached to it. You can limit the number of component instances to one or allow multiple component instances to be added to the content entry.
• Enumerations: an enumeration is a predefined set of values representing a list of possible options. You can use them to group values within a type.
• References: References are relations between two or more content entries in your project. With references, you can reuse content entries by connecting them. Once the relation is configured, you can also create related content directly from the content form.

#Step-by-step guide

This video follows the same step-by-step tutorial offered in this document.

#1. Create the enumeration

Create the enumeration

One of the Product Page models that you'll create in the next section will contain a component field with a dropdown menu for product discounts. Since it's best to start building from the bottom up, we'll start with the enumeration.

Navigate to the Schema builder of your Hygraph project, and click +Add next to Enumerations on the left sidebar. We'll use the following information to create the first one:

Before saving, you need to add enumeration values, which are the options you will get when using this later as a dropdown menu in the content form.

For every enumeration value, you need to enter a Display name, an API ID, and click Add.

We'll add the following values:

Finally, click Add enumeration to save.

Now that you have created the enumeration that you need to add to your component, it's time to create the component.

#2. Create the component

Create the component

In this section you'll create a component for promotional prices, which you will later add to one of your models as a component field. Creating this as a component offers the possibility to easily reuse it in different models as your business grows.

In the Schema builder, click +Add next to Components and use the following information:

Click Add component to save.

Now that you've created the component itself, it's time to add fields to it. This component will have a name, a description, an image, and the enumeration for discounts that you created in the previous step.

We'll start with the discount name. Find the Single line text field on the right sidebar, click Add, and use the following information to create it:

Click Add to save.

Next, add the discounts list. Find the Enumeration field on the right sidebar, click Add, and use the following information to create it:

Click Add to save.

Next, you want the component to offer the option to add a description by including a rich text field, which will also allow some formatting. Add a Rich text field from the right sidebar, using the following information:

Click Add to save.

Finally, you want editors to optionally include one image related to the discount in the content form. Add an Asset picker field from the right sidebar, using the following information:

Click Add to save.

#3. Create the models

Now it's time to create the models. We'll create one for authors, one for books and one for book genres.

Keep in mind that this setup contemplates information being stored in the CMS, so we'll include all the information needed to create a book listing, an author page, and genres as categories. This, however, does not necessarily mean this information exists only in the CMS, as it could be copy-pasted from an external source that a company uses to store their product information.

#Book model

Product Page model - Book

You'll create the Book model first. In the Schema builder, click +Add next to Models, and use the following information:

Click Add Model to save.

Book listings in online stores normally show the title, ISBN, a summary, a cover image, and the price. In addition to this, the model will have a a boolean to indicate if the book is in stock, and the promotion component that you built earlier.

You'll start with the book title. Add a Single line text field from the right sidebar, and use the following information:

Click Add to save.

This configuration prevents editors from creating book listings without a title.

Next, you'll add the ISBN. Add a Single line text field from the right sidebar, and use the following information:

Click Add to save.

Since an ISBN is essentially a product identifier, we decided to make it unique. You can later use it to find a specific book in your content entries.

Next, you want editors to be able to add an image of the book cover. Add an Asset picker field from the right sidebar, using the following information:

Click Add to save.

Next, you want editors to add a book summary. We'll use a rich text field for this, as it also allows some formatting. Add a Rich text field from the right sidebar, using the following information:

Click Add to save.

Now you'll add a switch that editors can use to indicate whether the book is in stock. Add a Boolean field from the right sidebar, using the following information:

Click Add to save.

A smart way to give this boolean an additional use, is to use it to set a condition. For instance, imagine you want the price field of the book to only show when the book is available. To do this, add a Float field from the right sidebar, using the following information:

Click Add to save.

The conditional visibility you set for this field means that if the Is available boolean that you created in the previous step is selected, then this price field will be visible in the content form. This is handy considering that prices can change when the company buys new stock.

It's time to add the Promotion component that you built earlier. Add a Basic component field from the right sidebar, using the following information:

Click Add to save.

Your model is ready for now. We'll be coming back later, after creating all models, to connect them.

#Author model

Product Page model - Author

Since the objective of an online bookstore is to sell books, it would be natural for the Book model to contain the most information. However, it is also common for online bookstores to allow potential buyers to navigate by author and genre. In our example, these will only contain basic information, as the real aim is not to provide in-depth information about an author or a certain literary genre, but rather to facilitate navigation.

This Author model will be a simple model containing only the author's name, bio & photograph. After you're done creating all models, you will revisit this model as well, to connect it to the others using reference fields.

In the Schema builder, click +Add next to Models, and use the following information:

Click Add Model to save. Let's add the fields next.

You'll start with the name. Add a Single line text field from the right sidebar, and use the following information:

Click Add to save.

This configuration prevents editors from creating author entries without a title (name).

Next, you want editors to add a bio for each author. We'll use a rich text field for this, as it also allows some formatting. Add a Rich text field from the right sidebar, using the following information:

Click Add to save.

Next, you want editors to be able to add a picture of the author. Add an Asset picker field from the right sidebar, using the following information:

Click Add to save.

We'll come back to this model later. Let's move on to create the final model.

#Genre model

Product Page model - Genre

This model will be the simplest of the group. It will only contain a name and a description. Practically speaking, this will work as a category model.

In the Schema builder, click +Add next to Models, and use the following information:

Click Add Model to save. Let's add the fields next.

Let's start with the genre name. Add a Single line text field from the right sidebar, and use the following information:

Click Add to save.

This configuration prevents editors from creating genre entries without a name, or to create two or more entries with the same genre name.

Finally, you want genres to have a description, in case editors are unsure which ones to select for a certain book or author. We'll use a rich text field for this, as it also allows some formatting. Add a Rich text field from the right sidebar, using the following information:

Click Add to save.

It is now time to connect the models. We'll work on this in the next step.

#4. Connect the models

Now that the three models have been created, it's time to connect them. To do so, we'll use reference fields. Selecting the reference field configuration your model needs depends on the characteristics of your product.

In the context of the current example:

• An author can have more than one book, and those books can fit into multiple genres.
• A book can have multiple authors, and fit into multiple genres.
• A genre encompasses a number of books and authors.

With this in mind, the best way to connect these three models is to use two-way references that allow multiple values. Creating two-way references also creates a reverse field in the related model. Because of this, while we need to have 6 reference fields, we will only be creating 3.

You'll create the first reference field in the Book model. Access it in the Schema builder, find the reference field on the right sidebar, and click Add. Use the following information:

Click Add to save.

This reference configuration will allow editors to add links to multiple books to author entries, and multiple authors to book entries. If you check the Author model, you'll find the Books reverse field has been added there.

Repeat the process to add a reference field that links to the Genre model using the following information:

Click Add to save.

By now, despite having created only 2 reference field, we have the 2 that we added to the Book model, a reverse field in the Author model, and one in the Genre model.

Navigate to the Author model. We said earlier that an author can write several books that may fit into different genres. While we already have a reference field here which will allow editors to link multiple book entries, we're missing a reference to the Genre model.

Repeat the process one more time to add a reference field that links to the Genre model using the following information:

Click Add to save.

You have now created the last 2 reference fields that we needed, since one was created here and its reverse field in the linked model (Genre).

This setup shows 3 content models for an online bookstore. As they are all connected through references, every time an editor creates a new content entry for a book, they will have the chance to either create new entries for genre & author, or link existing ones.

A frontend using this data could allow navigating all three to find related information, i.e. click on an author name to find all the books by that author that are available.

#Resulting content form

If you followed this tutorial, your resulting content form should look like this:

Content form

Editors will be able to create product entries, and at the same time link existing entries from the related models or create new ones.

#Useful links

• Components documentation: Learn more about components, available component field types, and how to use them.
• Enumerations: Learn more about enumerations and how to configure them.
• References: Learn more about the different reference field types and how to configure them.