Upgrade the Theme Version | Yext Hitchhikers Platform

What You’ll Learn

By the end of this unit, you will be able to:

• Go through the theme upgrade while accounting for theme branches, breaking changes, and previously overridden files
• List out and resolve breaking changes for a particular theme upgrade
• Override theme files without updating them directly

Overview

The theme files can be viewed from any Search frontend Code Editor. Navigate to the themes/answers-hitchhiker-themes 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. Once you upgrade to the latest version, you will need to click Restart Live Preview in order to review the updates.

Using Top-Level Files

Any files that are not in this themes folder are 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. We will talk more about this in the next sections.

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

Note

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

Breaking Changes

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.

Theme version descriptions in the reference docs for new versions of the theme 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.

Overriding Theme Files using Jambo Commands

Jambo commands such as “Add Page” or “Add Card” create 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 customized pages or cards that were created before doing the theme upgrade, you’ll need to either override those files again or copy the new lines of code over.

You can also use the Jambo command “Override Theme” to make an exact copy of a 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 but keep in mind that you may need to account for later theme changes to the file.

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 fork and customize it, you will not get the card changes from future theme upgrades.

Theme Branches

Keep in mind that the theme itself is a repository of files that can have multiple branches as mentioned in the Intro to Search Frontend Theme unit. 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.