Adding & Updating Pages | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How a Page is defined in Search
• How the Config for each page is structured
• How the Handlebars template for each page is structured
• How to add new Pages

What is a Page in Search?

When you run a search on a Search Experience, you’re on a webpage. The Universal Search and each Vertical Search are individual webpages. Yext, unlike other search software, is not just about the algorithm but also includes the Search SDK and Yext Pages to let you create an end-to-end experience for your users.

So, it should go without saying, that your first step after any global settings is adding the pages you need to make your experience.

If you are creating a full, multi-vertical experience, you’ll want to create:

• A Universal Search Page
• A Vertical Search Page for each vertical

If you’re just creating a single vertical search experience, like a Restaurant Locator or a Job Finder, you only need to create one vertical search page.

Each page (whether Universal or Vertical) is defined with two files:

1. A pages > [pageName].html.hbs file (handlebars) that defines the layout of that page
2. A config > [pageName].json file that defines the settings of the page

We will have a number of built-in Page templates in the Answers Hitchhikers Theme for Admins or Developers to easily add to their experience as a convenience layer, including but not limited to:

• Universal-Standard – Universal Page with our standard layout
• Vertical-Standard – Vertical Page with our standard layout
• Vertical-Full-Page-Map – Vertical Page optimized for Map

How to Add a New Page

To add a new page, you’ll need to navigate to the Code Editor for your site. From here:

1. Click on Tools > Jambo Commands
2. Select Add Page
3. Choose the Page template you’d like to use
4. Name the Page. Note that the name you select will be the url path for that page.
5. Click save
6. Jambo will fork the page template defined in the theme so can then customize as needed. You will see two new files in your repository:
   • pages > [pageName].html.hbs
   • config > [pageName].json

Note: If you’re adding a new vertical page, you’ll need to update the verticalKey and cardType in the config.json file.

Pages - Handlebars File

Handlebars is a templating language used by Jambo to make it easy and fast to build and deploy page layouts. The Pages handlebars file in the Answers Hitchhiker Theme may look something like this:

Pages > index.html.hbs

{{#> layouts/html }}
    {{#> script/core }}
      {{> cards/all}}
      {{> templates/universal/script/searchbar }}
      {{> templates/universal/script/spellcheck }}
      {{> templates/universal/script/navigation }}
      {{> templates/universal/script/directanswer }}
      {{> templates/universal/script/universalresults }}
      {{> templates/universal/script/locationbias}}
      {{!-- {{> templates/universal/script/qasubmission }} --}}
    {{/script/core}}
    <div class="Answers AnswersUniversalStandard">
      <div class="Answers-navWrapper">
        <div class="Answers-container">
          {{> templates/universal/markup/searchbar }}
          {{> templates/universal/markup/navigation}}
        </div>
      </div>
      {{> layouts/overlay-suggestions }}
      <div class="Answers-container Answers-resultsWrapper">
        {{> templates/universal/markup/spellcheck }}
        {{> templates/universal/markup/directanswer }}
        <div class="Answers-filtersAndResults">
          {{> templates/universal/markup/universalresults }}
        </div>
        {{!-- {{> templates/universal/markup/qasubmission }} --}}
      </div>
    </div>
    <div class="Answers-footer">
      {{> layouts/yext-logo }}
      {{> templates/universal-standard/markup/locationbias }}
    </div>
{{/layouts/html}}

You’ll see that this is really just a collection of the different components from the Search SDK, with some HTML notations to define where the components should go on the page.

The top half of the template is creating the script tags needed to add the various SDK components at run-time. Here, the components all specified by /script/ e.g.,

{{> templates/universal/script/searchbar }}
{{> templates/universal/script/spellcheck }}
{{> templates/universal/script/navigation }}

Below that, you’ll see the markup associated with each of these components to describe where these should go in HTML. For example,

 <div class="Answers-navWrapper">
  <div class="Answers-container">
    {{> templates/universal/markup/searchbar }}
    {{> templates/universal/markup/navigation}}
  </div>
</div>
<div class="Answers-container Answers-resultsWrapper">
  {{> templates/universal/markup/spellcheck }}
</div>

Let’s say you want to remove a component, like Pagination or Location Bias, from a page – it’s so easy! All you need to do is add or remove the component script line as well as the markup line. Or, you can simply comment them out by surrounding the line with {{!-- and --}} per standard handlebars notation, e.g.,

...
{{!-- {{> templates_vertical_script_searchbar}} --}}
...
{{!-- {{> templates_vertical_markup_searchbar }} --}}
...

When you comment something out, the code will be ignored and the component will not render in your experience.

You’ll learn more about handlebars and how to modify these pages in the Advanced Search track. You don’t need to know anything more than this to build a great experience.

Pages - JSON file

The JSON file for each Vertical page controls the settings for that vertical. By default, most of the settings you specify for the vertical, including the card type, will carry over into the Universal search page as well. This is to help make sure you don’t have to specify the same configuration multiple times.

The JSON file for the Universal page controls settings for that page, as well as any overrides for a vertical on Universal search, e.g., if you want the vertical to look different. But, more on that later.

The Vertical JSON file for a Vertical with Map page may look like this:

Config > vertical-map.json

{
  "verticalKey": "restaurants",
  "pageTitle": "Restaurant Search",
  "componentSettings": {
    "Map": {
      "mapProvider": "MapBox",
      "apiKey": "pk.eyJ1IjoieWV4dCIsImEiOiJqNzVybUhnIn0.hTOO5A1yqfpN42-_z_GuLw"
    }
  },
  "verticalsToConfig": {
    "restaurants": {
      "cardType": "LocationCard"
    }
  },
  "metaDescription": "",
  "canonicalUrl": "",
  "keywords": ""
}

Note: The actual files have additional properties commented out for your convenience to make it easier for you. There are also descriptions of the properties, in case you need a reminder after this training!

Creating Universal Search Page

When you’re just getting started, you’ll want to create a Universal Search page. To do this, use Jambo Commands to “Add Page” and select a Universal template.

As you recall, the page name dictates the url pages for that page. Your Universal page should be named “index” and thus your Universal Search files named pages > index.html.hbs and config > index.json. In web development, index.html is your root page recognized almost universally by browsers and applications. This means that when a user visits the domain you provide, like search.yourbranddomain.com, it is equivalent to visiting the /index.html page, or search.yourbranddomain.com/index.html. To read more about how index.html works, we recommend reading this article which gives a well-rounded tutorial.

Note: If you are building only a single vertical experience with no Universal Search, you would want to name that vertical page “index” instead.

Creating Vertical Search Page(s)

You’ll also need to create a page for each vertical search. Using Jambo Commands, you will Add a Page by selecting one of the vertical templates.

As a reminder, this is what it looks like:

We recommend you name the Vertical page a user-friendly name, like “faqs”, “locations”, “doctors”, or “branches”. Keep in mind that the name you select will be used in the URL path for the vertical page.

Renaming a Page

If you ever want to rename a page and therefore update the URL path, you can do so by renaming both the config > [pageName].json file and the pages > [pageName].html.hbs file. Make sure to rename them both at the same time to avoid any issues. Also note that the old url will not redirect to the new url, so rename with caution.