Product page with a Remote Source

#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

#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.

#1. Configure the Remote Source

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:

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:

1. Go to the app page in our marketplace, and click Install the app.
2. Select a project and an environment.
3. 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:

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:

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:

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:

Click Add to save.

Next, we'll add the slug. Add a Slug field from the right sidebar, and use the following information:

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:

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:

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:

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:

Click Add to save.

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 & Eemote Fields.
• References: Learn more about the different reference field types and how to configure them.