#Overview
Product Page model
This guide shows how to create a Product model in Hygraph that fetches product information from an external PIM via Remote Sources.
Companies often store their product information in a PIM, which helps them keep it consistent across different platforms. Using Hygraph's content Federation feature, Remote Sources, you can send CMS and product information to your frontend with a single API call.
Using this information directly from the PIM ensures you won't have to keep track of PIM information updates being replicated in the CMS, reducing the chance of error and discrepancies.
This mock image shows what a frontend using this setup could look like:
Product Page mock image
Remote Sources usage
Our Remote Sources feature is not available in Hobby plans (free). To follow this step-by-step tutorial you need to either have a paid plan, or use our 30-day trial.
#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. If you have a Hobby plan, please use the 30-day trial to enable usage of Remote Sources in your project.
#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. Remember that Hobby plan projects cannot use Remote Sources.
#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.
- Remote source: A Remote Source is a custom resolver entry point for your schema that allows data to be sourced from an external third-party web service and accept field values from other Hygraph fields as arguments.
- Remote Field: A field inside a regular Hygraph model that connects specific remote data to an entry of that model. Remote Fields are always related to a single remote source and custom type. RESTful remote fields are configured with a path to a specific endpoint in the remote source, such as user details from Github, or price & availability from Shopify.
- Top Level Remote Field: A field inside the
Query system model in Hygraph. These fields fetch remote data outside the context of a regular model, which is then sent to your frontend alongside your Hygraph data. This Content Federation utility eliminates the need to make separate API requests for data inside & outside of Hygraph.
- 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.
Configure the Remote Source
First, you need to configure a remote source to ensure that the project can use remote data fetched from your external PIM.
This guide will use the Federate this SKNCRE product routes to simulate an external PIM so you can follow the complete step-by-step process.
In your Hygraph project, navigate to the Schema builder and click +Add next to Remote Sources. Use the following information to configure the remote source:
| Field | Input |
|---|
| Select remote source type | Use the radio buttons to select Custom source. |
| Display name | Federate This SKNCRE |
| Prefix | FederateThisSkncre |
| Description | Check out https://federatethis.com for more info |
| Type | Use the radio buttons to select GraphQL |
| Base URL | https://federatethis.com/api/graphql/skncre |
| Introspection method | Use the radio buttons to select POST |
Click Add remote source to save.
This remote source will use the data stored in Federate This, using the Base URL you provided to send queries to. Since we created a GraphQL type remote source, there was no need to provide custom type definitions to define the structure of input arguments passed to your remote field later on.
The remote source itself is not enough to fetch information into a project. This project will use remote fields, top-level remote fields, and a data picker for remote fields app to create a product page that uses information from your external PIM without the need to duplicate it, while remaining easy to use for editors working with the UI.
We'll start by installing the picker app.
#2. Install the picker app
Install the picker app
Click here to install the Remote Source Data Picker app. This app gives your editors the ability to pick data from a Remote Source using a dropdown menu.
To install the app:
- Go to the app page in our marketplace, and click
Install the app.
- Select a project and an environment.
- Authorize permissions.
You will reach this screen:
Install the picker app
Click Install App to finalize the process.
Later on, you will add this app as a field to your Product model. Let's move on to the next step, where you create a Top-level Remote Field.
#3. Create the Top-level Remote Field
Top-level Remote Field
Top-level Remote Fields are added to the Query system model, and can fetch information into a project outside the context of a specific model. The picker app that we installed in the previous step needs both a Remote Field inside the Product model and a Top-level Remote Field to work.
To create a Top-level Remote Field, go to the Schema builder and access the Query system model. Since we created a GraphQL remote source, find the GraphQL field on the right sidebar and click Add on the field card. Use the following information:
| Tab | Field | Input |
|---|
| Settings | Display name | Top level product |
| Settings | API ID | topLevelProduct |
| Settings | Remote Source | Use the dropdown menu to select Federate This SKNCRE. |
| Settings | Method | Use the dropdown menu to select POST. |
| Settings | Query | Select the products [Product!] checkbox. |
Click Add to save.
Our product picker app will use this field to fetch product information from the external PIM.
Now that we have everything we need to build the model, let's move on to the final step.
#4. Create the model
Product Page model
To create the product model, navigate to the Schema builder and click +Add next to Models. Use the following information:
| Field | Input |
|---|
| Display name | Product Page remote source |
| API ID | ProductPageRemoteSource |
| API ID Plural | ProductPageRemoteSources |
| Description | This product page model uses remote sources to fetch information from an external PIM |
Click Add Model to save.
Now that the model has been created, you can start adding fields to it. As the product information lives outside of the CMS, this model does not need to have a large number of fields. Besides the remote fields and the picker, we will add a name, title, slug and asset picker, so editors can add alternative information. You can make your frontend take the alternative data when offered; that way editors can use the product information in the PIM not only for product listings but also for promotional content such as product special offers.
We will also add a reference field that will allow editors to link related products in the content form.
Let's start with the name. Add a Single line text field from the right sidebar, and use the following information:
| Tab | Field | Input |
|---|
| Settings | Display name | Product name |
| Settings | API ID | productName |
| Settings | Use as title field | Leave this checkbox selected |
| Validations | Make field required | Select this checkbox |
Click Add to save.
We want the name to be a required field because this field exists so that editors can identify products in the content table when relating content later on.
The other fields (title, slug and asset picker) will not be required, because this is additional information that editors may or may not add for the frontend to pick up.
Let's continue with the product title. Add a Single line text field from the right sidebar, and use the following information:
| Tab | Field | Input |
|---|
| Settings | Display name | Product title |
| Settings | API ID | productTitle |
Click Add to save.
Next, we'll add the slug. Add a Slug field from the right sidebar, and use the following information:
| Tab | Field | Input |
|---|
| Settings | Display name | Slug |
| Settings | API ID | slug |
| Settings | Lowercase | Leave this checkbox selected |
| Validations | Set field as unique | Select this checkbox |
| Validations | Match a specific pattern | Select this checkbox, and then select Slug from the dropdown. You don't need to modify the pattern. Under Custom error message, write “Input value does not match the expected format.” |
Click Add to save.
Next, you want editors to be able to include at least one image in the content form. Add an Asset picker field from the right sidebar, using the following information:
| Tab | Field | Input |
|---|
| Settings | Display name | Promotional image |
| Settings | API ID | promotionalImage |
| Settings | Allow multiple assets | Select this checkbox |
Click Add to save.
After installing the data picker app, 2 app fields became available to add to our models: One for GraphQL and one for REST. Since we configured a GraphQL Remote Source, we'll find the GraphQL Data Picker on the right sidebar and we'll click Add on the field card.
Use the following information:
| Tab | Field | Input |
|---|
| Settings | Display name | Product picker RS |
| Settings | API ID | productPickerRs |
| Settings | Description | You can select a product here |
| Custom | ID Field ID | id |
| Custom | API ID | topLevelProduct |
| Custom | Title Field ID | name |
Click Add to save.
Regarding the custom fields:
- ID Field ID: This is the key the app uses to find what data to pick as the
ID that gets used in the remote source field. We haven't added this remote field yet, we'll do it in the next step.
- API ID: This is the API ID of the Top-level Remote Field that you configured earlier.
- Title Field ID: This is the key from the data that shows the app what to display in the dropdown menu in the content form for editors to select.
The next thing we need to add to this model, is a Remote Field. Together with the Top-level Remote Field that you configured in the previous step, they will allow you to configure a field for the picker app that you installed earlier.
Find the GraphQL field on the right sidebar, and click Add. Use the following information:
| Tab | Field | Input |
|---|
| Settings | Display name | Remote product data |
| Settings | API ID | remoteProductData |
| Settings | Remote Source | Use the dropdown menu to select Federate This SKNCRE. |
| Settings | Method | Use the dropdown menu to select POST. |
| Settings | Query | Select the product checkbox and the id argument checkboxunder it, then write {{doc.productPickerRs}} in the input field. |
| Advanced | Field visibility | Use the dropdown menu to select API only. |
Click Add to save.
When configuring Settings > Query we selected id to match the ID Field ID from the data picker, and defined it as {{doc.productPickerRs}} so it uses the data picker app field.
As this field is only necessary to configure the remote data picker correctly, we selected the visibility to be API only, so editors cannot see it in the content form.
Finally we'll add a Reference field so that editors have the possibility to link related products. Use the following information:
| Tab | Field | Input |
|---|
| Define | Allow only one model to be referenced | Select this radio button. |
| Define | Model to reference | use the dropdown to select Product Page remote source |
| Define | Reference direction | Use the radio button to select One-way reference |
| Define | Relation cardinality | One to many |
| Define | Allow multiple Product Page remote source per Product Page remote source | Select this checkbox |
| Configure | Display name | Related products |
| Configure | API ID | relatedProducts |
| Configure | Description | You can add related products here |
Click Add to save.
Pro Tip
This reference configuration will allow editors to add links to multiple content entries, but only from the same model.
If you want editors to select entries from more than one model, you should configure the reference to Allow multiple models to be referenced.
If you want your editors to add more than one entry from each model, you will need to select all the Allow multiple checkboxes as well.
This is how you build a Product model that uses Remote Sources to fetch data from an external PIM. The way we built it is user-friendly for editors, who will be able to select product data using a dropdown menu in the content form.
#Resulting content form
If you followed this tutorial, your resulting content form should look like this:
Content form
Editors will be able to select a product whose information lives in the remote source by using a dropdown menu directly in the content form.
#Useful links
- Remote data: Check out our remote data guides to learn more about Remote Sources & Remote Fields.
- References: Learn more about the different reference field types and how to configure them.
