Customizing Your Pages | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to modify basic settings
• How to modify or add Component Settings
• How shared vertical configuration works

Overview of Customizing Pages

The JSON file has a few important sections:

1. Top Level Metadata
2. Page Settings
3. Component Settings
4. Verticals to Configuration

Here’s a sample page file for a locations vertical using the vertical-map template and a verticalKey from the Search Configuration of “locations”. You can also take a look at this file from the Code Editor of any experience by navigating to the theme file (themes/answers-hitchhiker-theme/templates/[template]/page-config.json).

{
  // top level metadata
  "verticalKey": "locations", 
  "pageTitle": "Location Search", 
  "metaDescription": "Use our search to find locations for our business", 
  "canonicalUrl": "https://search.domain.com/search/locations", 
  "keywords": "Yext, Locations, Offices", 

  // page settings
  "pageSettings": {
    "search": {
      "verticalKey": "locations",
      "defaultInitialSearch": "locations near me"
    }
  },

  //component settings
  "componentSettings": {
    "QASubmission": {
      "entityId": "org-1", 
      "privacyPolicyUrl": "www.yext.com/privacy" 
    },
    "Facets": {
      "expand": true, 
      "showMore": true,
      "searchOnChange": true 
    },
    "FilterLink": {
      "changeFiltersText": "sorts and filters", 
      "resetFiltersText": "reset filters", 
      "clearSearchText": "clear search" 
    },
    "AppliedFilters": {
      "removable": true
    },
    "VerticalResults": {
      "noResults": {
        "displayAllResults": true 
      },
      "hideResultsHeader": true
    },
    "SearchBar": {
      "placeholderText": "Search",
      "allowEmptySearch": true,
      "loadingIndicator": {
        "display": true
      },
      "voiceSearch": {
        "enabled": true
      } 
    },
    "Pagination": {
      "noResults": {
        "visible": true
      }
    }
  },

  //Verticals to Configuration
  "verticalsToConfig": {
    "locations": { 
      "label": "Offices", 
      "verticalLimit": 15, 
      "universalLimit": 4, 
      "cardType": "location-standard", 
      "icon": "pin",
      "mapConfig": {
        "mapProvider": "MapBox", 
        "pin": {
          "backgroundColor": "",
          "labelColor": "", 
          "strokeColor": "" 
        },
        "noResults": {
          "displayAllResults": true, 
          "visible": true 
        }
      },
      "universalSectionTemplate": "standard"
    }
  }
}

Top Level Metadata

For each page, there are a few top level settings you can set that are specific to that page. These are things that a consumer can’t see by just looking at your page but are important to get each page working (like verticalKey) or for search engines (like meta description).

These appear at the top of the default files in the page templates in the Theme, e.g.,

{
  "verticalKey": "locations", 
  "pageTitle": "Location Search", 
  "metaDescription": "Use our search to find locations for our business", 
  "canonicalUrl": "https://search.domain.com/search/locations", 
  "keywords": "Yext, Locations, Offices", 
...

These include:

Required Properties

New optional properties may be defined over time.

Page Settings

Page Settings are things you can control from the SDK that aren’t official “ComponentSettings” (which you’ll learn about next). Generally, Page Settings control configuration that is shared or required by multiple components on the page.

For now, this includes the “search” object which allows you to pass in a verticalKey with a defaultInitialSearch to set an initial search query when someone clicks on a vertical without running an explicit search. (This information is needed by both the VerticalResults and the SearchBar components.) You can set it to empty, like "defaultInitialSearch": "", to have all results returned for that vertical sorted based on relevance (e.g., if the vertical has location bias it will automatically show the closest locations to where we think the searcher is). Or, you can input a specific search query to run if you have a more nuanced use case.

Over time, as more features are added to the SDK that behave like this, we’ll add to this section. You can use the SDK properties directly here as they’re defined in the Search UI SDK documentation .

Component Settings

Component Settings is just as it sounds – where you specify the settings for the components from the SDK. The components are what make up most of the modules on a Search Experience. You add and remove these from the handlebars templates and you specify any settings (optional or required) for each one in the json file. This includes things like:

• Search Bar (SearchBar)
• Q&A (QASubmission)
• Facets (Facets)
• Static Filters (FilterBox)
• Pagination (Pagination)
• Direct Answers (DirectAnswer)
• and more

The Component Settings should reflect the SDK documentation. If you’re ever unsure how to specify the settings for a given component, you can always reference the SDK documentation here .

For the most part, you will find that many of the commonly used components are defaulted in the config or commented out for easy reference. You’ll learn more about some components in detail in their own dedicated modules, which includes:

• Sorting
• Facets & Filters
• Q&A Component
• Customizing Maps

There are also some components that have special treatment with the Jambo theme to improve usability. One example of this is the Map Component. While it will work if you specify the Map Component in ComponentSettings, the easiest way to manage the Map is in the verticalsToConfig object, which you’ll learn about next. We’ll cover how to customize maps in the Customizing Maps module .

Here’s an example of what this looks like:

"componentSettings": {
  "QASubmission": {
    "entityId": "org-1", 
    "privacyPolicyUrl": "www.yext.com/privacy" 
  },
  "Facets": {
    "title": "Filters", 
    "expand": true, 
    "showMore": true 
  },
  "SearchBar": {
    "placeholderText": "Search" 
  },
  "VerticalResults": {
    "noResults": {
      "displayAllResults": true 
    }
  }
},

Shared Vertical Config (verticalsToConfig)

The verticalsToConfig object is meant to represent any settings that are shared across the Vertical Pages and Universal Page, which is mostly around the Navigation and Card components. Anything specified here can be accessed when rendering either the Universal Page or that Vertical Page and it is there to save you time from having to specify in both places.

Here’s what this looks like on a page that has a map for a verticalKey “locations”:

"verticalsToConfig": {
  "locations": { 
    "label": "Offices", 
    "cardType": "location-standard",
    "icon": "pin", 
    "mapConfig": {
    //"enablePinClustering": true, // Cluster pins on the map that are close together. Defaults false
        "mapProvider": "MapBox", // The name of the provider (e.g. Mapbox, Google)
        "noResults": {
          "displayAllResults": false // Set to FALSE to hide results on the map when a search returns no results
        },
        "pin": {
          "default": { // The pin in its normal state
            "backgroundColor": "#5387d7", // Enter a hex value or color for the pin background
            "strokeColor": "#2a446b",
            "labelColor": "white"
          },
          "hovered": { // The pin when it is hovered
            "backgroundColor": "#2f4d71",
            "strokeColor": "#172638",
            "labelColor": "white"
          },
          "selected": { // The pin when it is selected by mouse click or through a card click
            "backgroundColor": "#2f4d71",
            "strokeColor": "#172638",
            "labelColor": "white"
          }
        }
     },
  }
}

Why is this important?

In many cases, you want Universal Search results to look and behave similar to your Vertical results in terms of the card layout, section name, map configuration or section icon.

If verticalsToConfig did not exist, you would always need to specify all of this information on both the vertical page and and the index.json page for each vertical so that both pages know what card to use, what section title to use, what icon to use, etc. for each vertical.

When you have to specify the same things in multiple places, it’s both time-consuming and error prone so this is designed to help avoid that when possible. That said, there are definitely instances where you’ll want Universal Search and Vertical Search to diverge, in which case you will have to specify the config twice.

What goes into verticalsToConfig?

From a mental model, think about the different things that appear for a given vertical in both places. Settings for components that are only on one or the other typically are not in verticalsToConfig – only things that are shared on both pages.

Here are the properties you can specify in the verticalsToConfig object:

Required Properties

New optional properties may be defined over time.

How to use verticalsToConfig to Vary Behavior between Universal & Vertical Search

On Universal, you can include any of these properties to override the behavior for that vertical on Universal search.

For example, let’s say you want to update both the icon and vertical label for your FAQ vertical. To do this, you would make sure to specify both the “icon” and the “label” properties in the faqs object in verticalsToConfig.

pages > faq.json (Vertical Page config)

{
  "verticalKey": "faqs",
  "pageTitle": "FAQ Search",
  "componentSettings": {},
  "verticalsToConfig": {
    "faqs": {
      "cardType": "AccordionCard",
      "icon": "callout",
      "label": "Frequently Asked Questions"
    }
  }
}

If you ever want to override any behavior between Universal and Vertical search pages, you’ll specify the override behavior on the Universal page by creating an object for that vertical under verticalsToConfig. If you do this, you need to include the full vertical object – not just the property you want to override. In other words, if you include a vertical in verticalsToConfig on the Universal Page config, it will entirely replace the configuration specified in the Vertical Page config. This is to make it easy for you and other collaborators to see what the full vertical should look like in one place.

Using the example above, let’s say, to appease some stakeholder, you’re being asked to show a different icon and label on Universal search than Vertical search for FAQs. This person wants:

Vertical FAQ page:

icon: “callout”

label: “FAQs”

card: “accordion”

Universal Search page:

icon: “star”

label: “FAQs”

card: “accordion”

In your pages > faqs.json file you would have:

{
  "verticalKey": "faqs",
  "pageTitle": "FAQ Search",
  "componentSettings": {},
  "verticalsToConfig": {
    "faqs": {
      "cardType": "accordion",
      "icon": "callout",
      "label": "Frequently Asked Questions"
    }
  }
}

In your pages > index.json file you would have:

{
  "pageTitle": "Brand Search",
  "componentSettings": {},
  "verticalsToConfig": {
    "Universal": {
      "isFirst": "true"
    },
    "faqs": {
      "cardType": "accordion",
      "icon": "star",
      "label": "FAQs"
    }
  }
}

By default, we will automatically use the Vertical Name that you set in your Search Configuration in the section heads, navigation and no results messaging in your experience. If you want to override this, you can do so by adding the label attribute in verticalsToConfig for your page or you can update the Vertical Name in your configuration directly.

For example, if your Vertical Name is “Locations”, it would look like this in the Search Configuration UI:

Or like this in the JSON Code Editor:

  "faqs": {
      "entityTypes": [
        "faq"
      ],
      "name": "FAQs",

By default, it will appear like this in the Navigation:

If you update the search configuration to change the Vertical Name, you’ll need to redeploy your site in order to see the changes. This is because this data is passed to the frontend through what we refer to as “injected variables”. These variables are injected in the Initial Build phase of the Pages deployment process. If you make an update to a search configuration and want to see it in your live preview, deploy preview, staging site, or production site, you can either go to the Deploys tab and click “Redeploy” on a recent deploy or you can make a commit to force a deploy.

Universal Section Template

As you can see in the table above, universalSectionTemplate is an optional property you can include in your verticalsToConfig object. This property will modify the layout of your resulting cards on Universal Search (it will not impact anything on Vertical Search). This is analogous to how you can modify the page layout by selecting a different page template for your vertical (e.g., vertical-standard or vertical-grid).

Just like cards, you can find the section template options in the theme under themes/answers-hitchhiker-theme/universalsectiontemplates. Your options include templates like:

• standard (paired with the standard card variations, specifically the menuitem-standard card here)

• grid-three-columns (paired with the product-prominentimage card)

• grid-two-columns (paired with the product-prominentimage card)

• grid-four-columns (paired with the product-prominentimage card)

(All templates will stack to one card per row on mobile.)

Over time, we’ll add more built-in options to the theme.

In many cases, you’ll want to stick with the standard stacked layout, like for location or FAQ verticals. However, for verticals like products, menu items, or services, you may want to try one of the additional options. Keep in mind that the standard card variations provide opportunity to display more content due to the horizontal real estate of the card.

The vertical-grid page layout and the grid section template are both paired well with the product-prominentimage and product-prominentimage-clickable cards. If you want to use the grid layout on Universal Search and the standard stacked layout on Vertical Search, no problem! You’ll just want to make sure that you override the vertical in verticalsToConfig.

For example, in the case of menus, let’s say you want to use the two-column grid layout for Universal Search with the product-prominentimage card and you want to use the standard vertical layout with the menuitem-standard card in Vertical Search. Here’s what your config/menuitems.json and config/index.json files would look like:

config/menuitems.json

  "verticalsToConfig": {
    "menuItems": { // The vertical key from your search configuration
      "label": "Menu Items", // The name of the vertical in the section header and the navigation bar
      "cardType": "menuitem-standard", // The name of the card to use - e.g. accordion, location, customcard 
      "icon": "star", // The icon to use on the card for this vertical
      "universalSectionTemplate": "grid-two-columns"
    }
  }

config/index.json

  "verticalsToConfig": {
    "Universal": {
      "isFirst": "true", // Indicates that this should always appear first in the navigation bar
      "label": "All" // The name of the universal tab in the navigation bar
    },
    "menuItems": { // The vertical key from your search configuration
      "label": "Menu Items", // The name of the vertical in the section header and the navigation bar
      "cardType": "product-prominentimage", // The name of the card to use - e.g. accordion, location, customcard 
      "icon": "star", // The icon to use on the card for this vertical
      "universalSectionTemplate": "grid-two-columns"
    }
  }