Overview of Templates | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will:

• Learn about the difference between streams-generated page templates and static pages
• Learn about common template exports that live in both types of templates
• Look at examples of each

Prerequisites

Before you can customize your site, you’ll need to build it. If you haven’t already, complete the Build Your Site module before doing this one!

Overview

In the last module, you laid the foundation for your site by setting up your local development environment, creating a site, and deploying it to Yext. Now let’s start customizing it!

In this unit, we’ll go into more detail on the two types of templates you can create:

1. Entity templates
2. Static page templates

Entity Templates

Entity templates (aka stream templates) allow you to generate pages based on entities in your Content, all with the same underlying structure and styling.

Hence the name, each stream template is powered by a stream, which you can think of as the vehicle that delivers Content to Pages in the form of JSON documents.

The config export in your template is where you specify the entity and fields you require for your template. In the Turtlehead Tacos example, the location template is used to create individual pages for each location entity. Check out the config export in src/templates/location.tsx

export const config: TemplateConfig = {
  stream: {
    $id: "my-stream-id-1",
    // Specifies the exact data that each generated document will contain. This data is passed in
    // directly as props to the default exported function.
    fields: [
      "id",
      "uid",
      "meta",
      "name",
      "address",
      "mainPhone",
      "description",
      "hours",
      "slug",
      "geocodedCoordinate",
      "services",
    ],
    // Defines the scope of entities that qualify for this stream.
    filter: {
      entityTypes: ["location"],
    },
    // The entity language profiles that documents will be generated for.
    localization: {
      locales: ["en"]
    },
  },
};

The filter field allows you to specify which entityTypes you want to pull from the Content. You can create your own custom filters to pull any subset of data you like, but here, we are grabbing all entities of type location.

The fields array is where you specify which fields from the chosen entityType that will be made available to your template. All of the field names listed in that array will be passed the default export as props on the document object e.g props.document.address or props.document.name

Streams-powered pages are simple but powerful. By specifying the entity type and the desired fields in config you can make hundreds or thousands of pages, each with a uniform structure, but supplied with entity-driven data from the Content.

Static Page Templates

Static pages are one-off pages which are not powered by streams, so they will not generate multiple entity-driven pages per template.

The starter repo has a static page under src/templates/static.tsx .

export const config: TemplateConfig = {
  // The name of the feature. If not set the name of this file will be used (without extension).
  // Use this when you need to override the feature name.
  name: "turtlehead-tacos",
};

The config export isn’t necessary, but it allows you to specify a name if you want to override the file name.

Let’s look at the transformProps function. This function can be used to make external API calls (calls non-Content resources) or to modify props before they are passed to the default export.

export const transformProps: TransformProps<ExternalImageData> = async (
  data
) => {
  const url = YEXT_PUBLIC_EXTERNAL_IMAGE_API_BASE_URL + "/2";
  const externalImage = (await fetch(url).then((res: any) =>
    res.json()
  )) as ExternalImage;
  return { ...data, externalImage };
};

In the example above, a simple get request is made to an external API and the response externalImage is added to the return object. The return value of transformProps is then passed to the default export as props.

Note

This function will be run during generation and pass its return value directly as props to the default export function.

Although static pages are not powered by streams, they can still be updated with information from the Content through Global Data .

Global data is often used for information stored in headers and footers, that is shared across all pages on your site. You’ll learn about this powerful concept later in this module.