How the Frontend Works | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How the Search frontend works
• What the Search UI SDK is and how Jambo interacts with it
• The key steps to developing an Search experience

Frontend of Search with Yext Pages

As a refresher, the frontend of Search controls what the user sees when they ask a question, including how the results page is structured, what each results card looks like, and other optional components you can use like facets or Q&A.

In order to actually build out an Search frontend experience, a developer or system (like Yext Pages) uses components from the Search UI SDK .

While, as an Admin, you will not need to use the Search UI SDK directly to build an Search experience, it’s important to know a few fundamentals, which you’ll learn about in this module. Developers can choose to build on the Search UI SDK, Search Core, or API directly, but our Pages integration with the Search UI SDK _+ Search API makes it easy for someone with basic knowledge of HTML/CSS/JS to build an experience end-to-end in under an hour!

While you learned a lot about how to build pages using the Page Builder in the Pages track , with Search you build using Yext’s Custom Development for Pages. The Search development uses Jambo, a static site generator (SSG) that relies on the JAMStack architecture .

The Search UI SDK

You will build Search frontends using Jambo. Jambo ingests components from the Search UI SDK and responses from the Search API, both of which are built and managed by the Yext Product and Engineering teams. In the Search UI library, we have a number of built-in components that help to create and define an experience. This includes things like:

• Search Bar
• Universal Search Results
• Vertical Search Results
• Direct Answers
• Pagination
• Q&A Submission
• Location Bias
• Sort Options
• Facets
• Filter Box (e.g., Static Filters)
• And more

We release updates to the library using semantic versioning (a widely accepted practice in software development), where each number in the version tells a user more about the version and whether an update is a Major change, Minor change, or a Patch. This system has several benefits: by pinning to a minor version, you’ll receive any bug fixes for free (without having to redeploy your site), and you can easily compare your version to another to see what changes will need to be accommodated in an upgrade.

Pinning to Versions

When you set which version of the Search UI SDK you want to use, you can choose what level of specificity you want to use. We call this pinning.

Here are some examples:

• sdkVersion: 1 - this means you’re pinning to a major version and your experience will use the latest public library version that starts with 1.*. This is not recommended for production experiences as it could be risky.
• sdkVersion: 1.3 - this means you’re pinning to a minor version and your experience will use the latest public version that starts with 1.3.*. This is recommended for most sites as it means you will get patch fixes automatically.
• sdkVersion: 1.3.4 - this means you’re pinning to an exact version. If there are patch updates (e.g., bug fixes), you will need to do work to upgrade to the latest. This is recommended for high profile sites with strict protocols on changes.

In most cases, we’ll recommend pinning to a minor version, such that you get any patch fixes automatically. To do upgrades, you’ll want to carefully review the changes and upgrade instructions, and may want to enlist the help of a developer. Overall, we recommend upgrading to take advantage of new features as they’re released. If you’re not interested in any of the new features in a major or minor release, you can also choose to skip it (our product team won’t be offended!).

In general, you should expect there to be patches as needed (potentially multiple times a week), minor releases every month or so, and major releases a few times a year.

You will learn more about upgrading versions in Upgrading Your Experience module .

Overview of Build Process Using Jambo

If you’re building an Search Experience with Jambo, then congratulations – you’re writing code! These are many of the same steps that developers take when they’re building websites, applications or other software.

1. Create a repository that houses your code
2. Change files in that repository
3. Preview those changes locally
4. Commit your changes
5. The system attempts to “build”
6. The system “deploys” or “publishes”

Sure, that’s simplifying things, but you’re going to be doing these exact same steps as you build your Search frontend. Who knows, maybe you’ll become a bonafide developer soon!

Let’s dig into some more detail for each step:

Step 1: Create a Pages Site with Jambo Repository

We house Search front ends in the Pages architecture. Out of the box, we use Git (a widely accepted version control system) to manage your Search code. When you’re ready to build a search experience, you’ll need to create a Git repository in GitHub. A repository, or “repo”, is a common term in software; it is a group of code/files with version history. In Yext, you can do this by creating a Site in Pages and then adding a repository with the Search Jambo Template, which will generate a GitHub repository with all of the pre-built files you need to create an experience. In many cases, this step will be done for you if you are starting with a Hitchhikers Challenge or a Solution Template, but it’s good to know how to do it in case you want to start a new experience from scratch.

1. Navigate to Pages > All Sites. Click Add New Site in the top right corner.

2. When building with Jambo and the Hitchhikers Theme, choose the option for Yext to manage the GitHub repo. Then click Next.

   

3. Fill in the name of your site. This is only shown internally and used to help you differentiate your sites from each other.

4. Name your repo. This will be the name of the GitHub repo associated with the site, but still essentially internally facing so you may name it what you’d like. This is automatically filled in based on what you named your site and the account ID (found in the URL).

5. Make sure to keep “Search Jambo Template” selected. This will create a repo with all the files you need to easily build your search front end.

   

Once you hit Create Site, you’ll see a build in progress. Once this completes successfully, you’ll have your first deploy with links for preview, staging, and production. You can read more about navigating these deploy screens and managing these links in the Deploy Pages module in the Pages track - we are using Pages architecture after all!

Step 2: Modify the Code

While we like to think that our default experience (part of the Jambo Theme you’ll learn about later) will work just the way it is, we know that each brand is different and has unique requirements. If you navigate to Pages > the Site you created in Yext Pages > Deploys, you’ll find a link to “Code Editor” in the top right. This will take you to a screen showing all the existing branches in your site and the five most recent commits for each branch. Since you just created your site, you’ll just have the master branch with one “Initial commit” by the Yext system when it created your site.

Hover over the master branch and click the pencil icon to access the repo. Here, you can view and modify any of the files in your repository and customize the experience to your brand, just like you would through GitHub directly. Want to modify the colors to match your brand? No problem! Want to change the layout of your card? No problem! Want to adjust how data is pulled in from the Knowledge Graph? No problem! You have control with the Yext Code Editor.

You’ll get a description of all of these files and their purpose in the next unit. For now, you just need to know that you can make changes to your Search Jambo repo straight from the browser, without having to install git and use your terminal.

Step 3: Preview Your Changes

A good developer always previews their changes while they’re developing to catch mistakes or to experiment with different approaches and designs. We also encourage developers to preview their changes in different browsers. When you’re ready to preview your change, you can click Update Preview, check to make sure there aren’t any errors in the console and then refresh your preview page to see the updates. This will make your life infinitely easier, especially as you’re getting started! You’ll learn more about this in the Live Preview unit .

Step 4: Commit Your Changes

Once you’re feeling good with your code, you’ll want to commit these changes. This will update your GitHub repository and kick off a “Build”.

When you commit your changes, you’ll want to include a message reminding yourself and others what the commit was for. You can also optionally add a tag to your commit, making it easier to publish that specific version of your site.

Clicking Confirm commits your changes and opens a new modal telling you there is a build in progress. You have the option of going to the deploys screen to check on the status of your commit or returning to the Code Editor to keep modifying your code.

Let’s go to the deploys screen to see what happens once you commit your code.

Step 5: Yext CI Builds

After you commit your changes to your GitHub repo, the Yext CI will build your site. The Yext CI (CI stands for “Continuous Integration”) monitors your commits and runs a post-processing toolchain as soon as you commit. During the build, we are compiling all of the source code in your repo to get it ready for publishing.

You can monitor your builds in the platform by going to the Deploys tab for your site. You don’t need to know too much about what’s happening in this step, except that there might be errors, typically due to errors in your code. You might need to commit new code to fix these errors or to kick off a new build. You can read more about the deployment process in the Deploy Pages module in the Pages track.

Step 6: Publish Your Page

You are almost ready to have the world see your work! The last step you need to do is publish your page. In the screenshot above, you’ll see a green “Production” pill next to the initial commit, which shows which commit the production link is pinned on. You’ll learn more about this in the Pages Generation unit .