As mentioned in Overview of Results Pages, the JSON file is where you can customize the settings of a page.
The JSON file has a few important sections:
- Top Level Metadata
- Page Settings
- Component Settings
- Verticals to Configuration
Here's a sample page file for a locations vertical using the vertical-full-page-map template and a verticalKey from the Search configuration of "locations". You can take a look at this file in the Code Editor of any experience by navigating to the theme file (themes/answers-hitchhiker-theme/templates/[[template]]/page-config.json).
{
"verticalKey": "locations", // The vertical key from your search configuration
"pageTitle": "Location Search", // !!!REPLACE THIS VALUE!!! The contents of the title tag and meta open graph tag for title
// "metaDescription": "", // The meta tag for open graph description
// "canonicalUrl": "", // The link tag for canonical URL as well as the meta tag for open graph url
// "keywords": "", // The meta tag for keywords
"pageSettings": {
"search": {
"verticalKey": "locations", // The vertical key from your search configuration
"defaultInitialSearch": "" // Enter a default search term
}
},
"componentSettings": {
/**
"QASubmission": {
"entityId": "", // Set the ID of the entity to use for Q&A submissions, must be of entity type "Organization"
"privacyPolicyUrl": "" // The fully qualified URL to the privacy policy
},
**/
/**
"Facets": {
"expand": false, // Allow the user to expand and collapse the facets
"showMore": false, // Display a link to see more facet options within a facet
"searchOnChange": true // Will automatically run a search as facets are selected or unselected. Set to false to only trigger updates with an Apply button.
// Additional options are available in the documentation
},
**/
"FilterLink": {
"changeFiltersText": "filter results", // Text that displays by default
"resetFiltersText": "reset filters", // Text when filters are applied
"clearSearchText": "clear search" // Text when there are no results, conducts an empty search
},
"AppliedFilters": {
"removable": true
},
"VerticalResults": {
"noResults": {
"displayAllResults": false // Optional, whether to display all results in the vertical when no results are found.
},
"hideResultsHeader": true
},
"SearchBar": {
"placeholderText": "Search for locations", // The placeholder text in the answers search bar
"allowEmptySearch": true, // Allows users to submit an empty search in the searchbar
"loadingIndicator": {
"display": true //Optional, whether to include a loading indicator on seachbar
// "iconUrl": "" //Optional, use custom icon url instead of the default loading indicator animation
},
"voiceSearch": {
"enabled": false // Whether or not voice search is enabled
// "customMicIconUrl": "", // Path to override the voice start icon
// "customListeningIconUrl": "" // Path to override the voice stop icon
}
},
"Pagination": {
"noResults": {
"visible": false
}
}
},
// Configuration used to define the look and feel of the vertical, both on this page and, by default,
// on the universal page.
"verticalsToConfig": {
"<REPLACE ME>": { // The vertical key from your search configuration
// "label": "", // The name of the vertical in the section header and the navigation bar
// "verticalLimit": 15, // The result count limit for vertical search
"universalLimit": 4, // The result count limit for universal search
"cardType": "location-standard", // The name of the card to use - e.g. accordion, location, customcard
// "icon": "pin", // The icon to use on the card for this vertical
"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"
}
}
},
"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 vertical key) or for search engines (like meta description).
These appear at the top of the default files in the page templates in the Theme.
{
"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 properties like:
- Page Title
- Meta Description
- Keywords
To see a full list of properties along with their descriptions, see the Top Level Meta Data reference doc.
Page Settings
Page settings are things you can control from the SDK that aren't official component settings (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.
"pageSettings": {
"search": {
"verticalKey": "faqs", // The vertical key from your search configuration
"defaultInitialSearch": "" // Enter a default search term
}
},
Component Settings
Component settings are just as they sound – where you specify the settings for the components from the SDK. These were the components you just learned to add in Update Page Components.
"componentSettings": {
/**
"QASubmission": {
"entityId": "", // Set the ID of the entity to use for Q&A submissions, must be of entity type "Organization"
"privacyPolicyUrl": "" // The fully qualified URL to the privacy policy
},
**/
/**
"Facets": {
"expand": false, // Allow the user to expand and collapse the facets
"showMore": false, // Display a link to see more facet options within a facet
"searchOnChange": true // Will automatically run a search as facets are selected or unselected. Set to false to only trigger updates with an Apply button.
// Additional options are available in the documentation
},
**/
"FilterLink": {
"changeFiltersText": "filter results", // Text that displays by default
"resetFiltersText": "reset filters", // Text when filters are applied
"clearSearchText": "clear search" // Text when there are no results, conducts an empty search
},
"AppliedFilters": {
"removable": true
},
"VerticalResults": {
"noResults": {
"displayAllResults": false // Optional, whether to display all results in the vertical when no results are found.
},
"hideResultsHeader": true
},
"SearchBar": {
"placeholderText": "Search for locations", // The placeholder text in the answers search bar
"allowEmptySearch": true, // Allows users to submit an empty search in the searchbar
"loadingIndicator": {
"display": true //Optional, whether to include a loading indicator on seachbar
// "iconUrl": "" //Optional, use custom icon url instead of the default loading indicator animation
},
"voiceSearch": {
"enabled": false // Whether or not voice search is enabled
// "customMicIconUrl": "", // Path to override the voice start icon
// "customListeningIconUrl": "" // Path to override the voice stop icon
}
},
"Pagination": {
"noResults": {
"visible": false
}
}
},
For the most part, you will find that many of the commonly used components are in the config by default, sometimes commented out, for easy reference. In order to update settings for a component you may need to first comment in those lines of code if they are relevant. Then you will need to update the inputs for those settings. There are settings that aren't shown by default but you can check out the SDK component reference docs to view additional properties for each component.
You'll learn more about some components in detail in their own dedicated units, which includes:
There are also some components that have special treatment within the 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 can learn about in the Maps doc.
Shared Vertical Config (verticalsToConfig)
The verticalsToConfig object is meant to represent any settings that are shared across the vertical and universal pages, 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": { // The vertical key from your search configuration
// "label": "", // The name of the vertical in the section header and the navigation bar
// "verticalLimit": 15, // The result count limit for vertical search
"universalLimit": 4, // The result count limit for universal search
"cardType": "location-standard", // The name of the card to use - e.g. accordion, location, customcard
// "icon": "pin", // The icon to use on the card for this vertical
"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"
}
}
},
"universalSectionTemplate": "standard"
}
}
Why is This Important?
In many cases, you want universal search results to look and behave similarly 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 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 universal and vertical search. Settings for components that are only on one or the other typically are not in verticalsToConfig.
Here are some properties you can specify in the verticalsToConfig object:
- Card Type
- Icon
- Label
To see a full list of properties and descriptions, see the Shared Vertical Settings (verticalsToConfig) doc.
Vary Behavior Between Universal & Vertical Search
In the universal search page, 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": "faq-accordion",
"icon": "callout",
"label": "Frequently Asked Questions"
}
}
}
If you want to override any behavior between the 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, the verticalsToConfig object specified on the universal page will entirely replace the configuration specified in the vertical page config, so you'll need to include the full verticalsToConfig object for that vertical – not just the property you want to override. 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: "Frequently Asked Questions"
- card: "faq-accordion"
Universal Search page
- icon: "star"
- label: "FAQs"
- card: "faq-accordion"
In your pages > faqs.json file you would have:
{
"verticalKey": "faqs",
"pageTitle": "FAQ Search",
"componentSettings": {},
"verticalsToConfig": {
"faqs": {
"cardType": "faq-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": "faq-accordion",
"icon": "star",
"label": "FAQs"
}
}
}
Note: By default, we will automatically use the vertical name in your Search configuration as the label. To override this, you can either add the
labelattribute inverticalsToConfigor you can update the vertical name in your configuration directly.
If you update the config, you'll need to redeploy your site to see the changes by either going to the Deploys tab and clicking "Redeploy" on a recent deploy or you can make a commit to force a deploy. This is because this data is passed to the frontend as "injected variables" in the initial build phase of the Pages deployment process.