Theme and SDK Upgrade Overview | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• What a new theme and SDK version is
• Where to find information on upcoming or past theme/SDK versions
• A refresh of the frontend
• What a theme upgrade does
• How semantic versioning works for the Search UI SDK

Overview

As you know, Search is an extremely iterative product. Search captures real-time search analytics which allows Hitchhikers to make data-driven decisions, whether that’s adding new entities into the Knowledge Graph or adjusting existing content.

Similarly, the Yext team works hard to make enhancements to the product based on feedback and engagement from both clients and Hitchhikers. The Yext team will periodically release updates to the Search UI SDK (also referred to as the JavaScript Library or the SDK), which include new features, enhancements to existing features, deprecation of old features, and bug fixes. We will also add new functionality, new cards, and new page templates to the Answers Hitchhiker Theme.

As a Hitchhiker, it’s critical that you are aware of any upgrades that are released by the Yext team. Want to take advantage of all of the cool new features that our Product team releases? Then you’ll need to upgrade both the theme and the Search UI SDK in your Search experience.

Note

Solution templates will always be on the latest theme and Search UI SDK versions so that new sites built off of them have the latest and greatest version of Search.

Where to Find Information on Upgrade Versions

Within Search, there are a few pieces that have upgrade versions. Below is a table of them, links to their changelogs, and where to update the version numbers.

In this module, we’ll focus specifically on the first two: upgrades to the Search UI SDK and Hitchhiker Theme.

We use the Hitchhikers Community to communicate infomation about upgrades. Each version update is a separate Community post that links out to Community posts for each new feature, bug fix, or improvement. All posts are in the Product/Library Releases and New Features category and further categorized under sub-categories for “SDK/Theme Updates”, monthly releases, or seasonal releases. The posts are also consolidated into changelog Community posts for the Search UI SDK and Hitchhiker Theme .

You can also search by tags to find relevant theme upgrade posts. The main post for each version is tagged with theme-upgrade, which can be accessed at https://hitchhikers.yext.com/community/tag/theme-upgrade. All posts related to a particular theme upgrade version are tagged with theme-#. Find these tags by using the tag box found on any category page in the Community, or by updating the URL of a tag page, e.g. https://hitchhikers.yext.com/community/tag/theme1-19.

These posts will outline changes and bug fixes included with each version, including any upgrade implications or callouts to be aware of when you make the upgrade. A new Search UI SDK version will always be tied to a new Theme version, but the Theme is updated more frequently than the Search UI SDK. Let’s look at two Community posts as examples:

• This post outlines the changes and new formatters included with the Hitchhiker Theme v1.24, including files you may need to re-fork (more on this later).
  
• This post has changes and upgrade instructions for the Hitchhiker Theme v1.23, but also includes the Search UI 1.10, which means you’ll have to update the Search UI SDK when you upgrade the theme.

Note on the search bar and theme/Search UI SDK upgrades: You’ll notice that the legacy search bar also uses the same changelog as the Search UI SDK. That’s because they are both using the same JavaScript library of components. However, it’s important to note that the search bar version and the library version are distinct because they use different components in the library. That means that upgrading the library version does not require a corresponding update to the search bar version, which would save you or your client the trouble of upgrading the search bar version with every update. Once in a while we may ask you to upgrade your search bar version if it’s no longer supported or if there has been a major change (you’ll learn more about types of changes below). For example, there was a breaking bug in v0.13.0 of the search bar that was fixed in v1.0.0. If your site uses a legacy search bar with a version below v1.0.0, we recommend upgrading the version. You can switch to the speed optimized search bar while you’re at it!

The Community is a great forum to ask any questions you may have about some of the new features or upgrades that are included in a release. Ask questions about a release or ask for help if you’re having issues upgrading by commenting on an existing post or creating your own.

Frontend Refresh

Before we go into the process of a theme upgrade, it’s important to have a conceptual understanding of what the frontend pieces are and how they work together. Once you understand this, the idea of a theme upgrade becomes much more intuitive and the things that can go wrong make much more sense.

Components of the Frontend

As you may recall from Overview of Search Frontend , the Search UI SDK is our JavaScript library of components that define the frontend Search experience, such as the Search Bar, Universal Search Results, and Direct Answers. Developers can build a Search frontend using these JavaScript components directly, allowing them to customize the basic components, create components of their own, and add components from another library.

While using the Search UI SDK directly allows for more customization, it may be more work than necessary for those content with an out-of-the-box experience. These users (including Admins!) can use Jambo and the theme, which pull from the Search UI SDK and provide the framework and assets for a standard experience.

The Answers Hitchhiker Theme is a bundled package of files and code within your repository that sets up the basic structure and functionality for an entire Search experience without you doing anything! The theme is included when you use the Search Jambo Template to create your site (the Jambo Template is a part of the Solution Template). It contains templates for things like pages and cards that you can use in your Search experience. The theme also translates the configuration files in your code repository to be able to use the Search UI SDK components, so that you don’t have to. From there, you can add any customizations, such as changing branding or adding custom cards.

Finally, Jambo is a static site generator that takes all of the files in your repository, including theme files, templates, and customizations, and creates the static HTML pages that an end-user actually sees. Jambo also provides commands that enable you to easily interact with the theme, such as by adding verticals, adding cards, and overriding the theme. The theme itself is complex and fragile, so we don’t want to directly manipulate the theme itself - we let Jambo do it for us.

Why You Need to Update the SDK When Upgrading the Theme

The Search UI SDK documentation walks through everything you need to know about the library, including code to implement components yourself if you’re a developer. If you’re not a developer, the theme takes care of adding components and writing all this code for us.

The theme references the specific code from the SDK to build Search experiences. When you update the theme, you’ll want to also update the SDK version the theme is working with. If there is a new version of the SDK, there may be different code used to implement components. A new theme version will update the theme files to accommodate the changes in the SDK.

Since the theme files are built directly off of the SDK components, you’ll want to make sure they’re compatible with each other by using the latest versions of both.

Understanding What a Theme Upgrade Does

The theme files can be viewed from any Search frontend Code Editor. Navigate to the themes/answers-hitchhiker-theme folder and you’ll see the set of files included in the theme.

Upgrading the theme of your Search experience (i.e. clicking Tools > Jambo Commands > Upgrade Theme) will replace the answers-hitchhiker-theme folder with an updated folder, containing various updates made to files in the updated theme. This allows your Search experience to reference the features of the latest theme.

Any files that are not in this themes folder is considered a top-level file. Barring a few exceptions, top-level files are not touched when you upgrade the theme.

Because of this, it is extremely important to never update the theme files directly. If you update the theme files directly, those updates will be overwritten the next time you go to do a theme upgrade. Instead, if you want to stray from the theme, you should override the file. The Jambo command “Override Theme” will make an exact copy of the file in the top level directory and update jambo.json to say you’re providing an override. You can then make any changes you want to this top-level file.

Note

You might see the terms “fork”, “shadow”, or “override” used in the training and the Community. We use these terms interchangeably to mean making a top-level copy of the theme file that we can customize.

Breaking changes can occur when you upgrade the theme if top-level files are outdated and are not compatible with new theme files. Overriding the theme will shadow that file at that moment in time. This means that if you upgrade the theme after a file has been overridden, it will not automatically pull in updates the next time you do a theme upgrade. Thus, only override the theme if it’s deliberate.

Community posts on new versions will call out which files to check for forked versions. If you previously overrode the theme, you will have to manually add updates yourself (which you should do to stay up-to-date on new features) by either:

1. Referencing the theme file and copying over new lines of code (only recommend for small changes where you know exactly what changed), or
2. Overriding the theme file again and adding in the changes you had made previously.

This also applies for Jambo Commands such as “Add Page” or “Add Card”. Jambo creates new files for the page or card using the theme templates from that moment in time. If you want to add new theme features to pages or cards created before doing the theme upgrade (such as Collapsible Filters in theme v1.14 ), you’ll need to either override those files again or copy the new lines of code over.

If you make updates to customize something that the theme is doing by default, the custom file may be unnecessary. Use the theme when you can to easily take advantage of new features as they come out. A great example of this is Direct Answers: you may have added some additional formatting changes to the allfields-standard card, but as soon as you customize it, you will no longer get changes to the default automatically through theme upgrades.

Keep in mind that the theme itself is a repository of files that can have multiple branches. When you upgrade the theme, it’ll ask you which branch of the theme you’d like to upgrade to. Leave this on master to upgrade to the most recent version of the theme.

Search UI SDK - Pinning to Versions

As you’ll learn in the next unit, the way you upgrade the Hitchhiker Theme version is different from the way you upgrade the Search UI SDK version. For the Hitchhiker Theme, you’ll use a Jambo Command that will automatically upgrade you to the latest version. For the Search UI SDK, you’ll manually change the version number in the Code Editor.

We release updates to the Search UI SDK using semantic versioning , a widely accepted practice in software development, where versions are denoted by three numbers in the form of Major.Minor.Patch, such as v1.21.2. Since the Search UI SDK version is set manually, you choose the level of specificity you want to use by pinning to a specific version. Here are the types of changes you can expect between each and what it means to pin to each:

Patches (e.g. v1.21.2): Changes between patches will be non-breaking bug fixes, including styling regression fixes. When you upgrade patches, you will not see things degrade (there will either be an improvement or no change).

• Pinning to a patch means you’re pinning to an exact version. If there are patch updates, you will need to do work to upgrade to the latest (see Apply a Patch in the next unit).
• Note: If you have custom styling targeting specific classes, these updates might be breaking.
• Pinning to patches is recommended for high profile sites with strict protocols on changes and those with custom styling that could break with automatic updates.

Minor Versions (e.g. v1.21): Changes between minor versions will include new functionality and deliberate styling updates (for example, adding spacing between result cards on verticals). It will not stop your experience from working, but there is a chance of visual impact.

• Pinning to a minor version will use the latest public version that starts with 1.21. This is recommended for most sites as it means you will get patch fixes automatically.

Major Versions (e.g. v1): Changes between major versions include breaking changes such as a changed interface. Be sure to follow the Community post associated with the Search UI SDK version closely for major version upgrades.

• Pinning to a major version will use the latest public version that starts with 1. This is not recommended for production experiences as it could be risky.

So long as you are not providing custom styling or doing custom development work, we recommend pinning to a minor version so you receive any bug fixes automatically without having to redeploy your site! For upgrades, you’ll want to carefully review the changes outlined in the Community post associated with each version release for instructions.

Overall, we recommend upgrading your Search UI SDK version to take advantage of new features as they’re released. If you’re not interested in any of the new features in a version, 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 a few times a month), minor releases every month or so, and major releases a couple times a year.