loading

Customizing Your Pages| 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 (with a verticalKey from the Search Configuration of “locations”):

{
  // top level metadata
  "verticalKey": "locations", 
  "pageTitle": "Location Search", 
  "metaDescription": "Use our search to find locations for our business", 
  "canonicalUrl": "https://answers.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": {
      "title": "Filters", 
      "expand": true, 
      "showMore": true 
    },
    "SearchBar": {
      "placeholderText": "Search" 
    },
    "VerticalResults": {
      "noResults": {
        "displayAllResults": true 
      }
    }
  },

  //Verticals to Configuration
  "verticalsToConfig": {
    "locations": { 
      "label": "Offices", 
      "cardType": "location-standard",
      "icon": "pin", 
      "mapConfig": {
        "mapProvider": "MapBox", 
        "pin": {
            "height": 26,
            "width": 22,
            "backgroundColor": "#009347", 
            "labelColor": "white",
            "strokeColor": "white"
        }
      }
    }
  }
}

Top Level Metadata

For each page, there are a few top level settings that 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://answers.domain.com/search/locations", 
  "keywords": "Yext, Locations, Offices", 
...

These include:

Required Properties

Property Description Example
verticalKey (vertical page only) The verticalKey is the same verticalKey that exists in your Search Configuration, e.g., ‘faqs’ or ‘restaurants’. Make sure this matches the key you specified in the Search Configuration exactly as this is a common mistake. “faqs”



Optional Properties

New optional properties may be defined over time.

Property Description Example
pageTitle While not required, we strongly recommend that you specify the Page Title, which will appear as the page title in the tab on a browser. We recommend something like “[brandName] Search” for Universal search or “[verticalName] Search]” on Vertical search. This is important for SEO, since it helps search engines understand the purpose of the page. “FAQ Search”
metaDescription The Meta Description provides a concise, human-readable summary of your page’s content. Search engines may include the meta description in search results snippets, so it’s important that this is descriptive and reflective of the content on your page. This should be around 50 to 160 characters in length. Note: You only need to fill this out if Yext is hosting the page on a subdomain “Use our search to find frequently asked questions about our business”
canonicalUrl A canonical tag identifies the primary page or data source when multiple copies of a web page exist at different URLs. In the Answers context, it helps to ensure that any URL variants (think query parameters) aren’t separately indexed by search engines. Note: You only need to fill this out if Yext is hosting the page on a subdomain. https://answers.domain.com/search/faqs”
keywords Keywords are optional - they may help in some search engines to rank content. Google has stopped supporting keywords, but other search engines may use them. Note: You only need to fill this out if Yext is hosting the page on a subdomain. “Yext, Knowledge Graph, Answers”


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 Answers Search UI 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 an Answers 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
  • 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:

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

Property Description Example
cardType This is how we know which card to use on your experience. This is not needed on Universal Search. “standard”



Optional Properties

New optional properties may be defined over time.

Property Description Example
icon This is the icon that appears in the vertical’s section header on Universal results, and in the alternate verticals section of no results (if used). If nothing is specified in the config, we will use the “star” icon. This property accepts only one of the enum values available in the SDK. Full list of icon options available in the SDK readme here “briefcase”
iconUrl This is the icon that appears in the vertical’s section header on Universal results, and in the alternate verticals section of no results (if used). If both icon and iconUrl are present, we will use the iconUrl. https://a.mktgcdn.com/p-sandbox/7FGLdYehh9wxKb_FITVC2y2fRfXudwEm-XC8gROksZA/196x196.jpg"
label This is the name of the vertical as it appears in the Vertical section title and in the navigation. If you don’t specify, we will use the vertical name property from the Search Configuration by default. For some verticals, like “faqs”, many customers choose to specify the label, e.g., “Frequently Asked Questions”. “Frequently Asked Questions”
sectionTitle If you only want to override the section title, and not the navigation, you can update this property. “Frequently Asked Questions”
verticalLimit This allows you to set maximum results displayed on Vertical Search. If you have pagination enabled (e.g., you have the component in the handlebars template), this will be the maximum number per page. If you have removed the pagination component or commented it out, this will be the maximum results the user sees. The maximum value is 50. 25
universalLimit This allows you to set the maximum results displayed within the vertical section on universal results. The maximum value is 10. 10
viewAllText This allows you to update the label on Universal results for the link to View More Results from Universal Results. Clicking this link will take you to the Vertical Page by default. “View All Products here”
viewMore This allows you to hide the View More Results link in Universal results. By default, this is set to true. false
universalSectionTemplate This allows you to change the section layout for a vertical on Universal Search, e.g., standard (stacked cards) or grid-three-columns. If left out, it will default to standard (stacked cards) grid-three-columns
mapConfig This allows you to set the configuration for the map, including the mapProvider (Mapbox or Google), pinConfig, and noResults. You can learn more about this in the Customizing Maps module. see code example above
isFirst This is set by default in the theme for the Universal page. It is how we ensure that the Universal page (“All”) is the far left tab in the navigation. true


light bulb
Tip

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: vertical name in UI

Or like this in the JSON Code Editor:

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

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

vertical name in navigation

If you update the search configuration to change the Vertical Name, you’ll need to do a build and publish of 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 fresh at the start of each build. If you make an update to a search configuration and want to see it in your staging site, live preview or production site, you can either go to the Builds tab and click “Rebuild” on a recent build or you can make a commit to force a build.



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"
    }
  }
}

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) standard layout

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

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

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

(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"
    }
  }

unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 3

    What is the verticalsToConfig object used for?

    Error Success Question 2 of 3

    How would you remove a component, like pagination, from a page?

    Error Success Question 3 of 3

    Which of the following properties are defined in the top level of the page.json file (i.e., the top level basic settings)? Select all that apply.

    Wahoo - you did it! 🙌

    You've already completed this quiz, so you can't earn more points.You completed this quiz in 1 attempt and earned 0 points! Feel free to review your answers and move on when you're ready.
1st attempt
0 incorrect
Splash Loading