Theme Repo Structure | Yext Hitchhikers Platform
Remember that a repo is just a collection of files. Structurally, a Search Jambo Template repository will look like something like:
cards
-> card-name
-> component.js
-> template.hbs
ci
-> build.sh
-> serve.sh
config
-> global_config.json
-> locale_config.json
-> some_page.json
layouts
-> footer.hbs
-> header.hbs
pages
-> some_page.html.hbs
static
-> assets
-> js
-> scss
themes
-> answers-hitchhiker-theme
partials
-> some_template.hbs
translations
-> languageCode.poIn the diagram above, the top-level things are folders, with arrows denoting things inside the folder. For example, “cards” is a folder, with a “card-name” folder inside. Inside “card-name” are “component.js” and “template.hbs” files for each card.
The folders you will become most familiar / interact with the most with are: cards, config, pages and static.
We’ll review each of these though, starting with the Theme.
Themes
The theme exists as part of the repository. When you create a search site using the Search Jambo Template, you will automatically have the Frontend Theme.
The Theme serves two main functions:
- A translation layer between the configuration files in your code repository and the Search UI SDK.
- A set of templates for things like Pages and Cards to make it easier for you to develop and customize your experience.
You can browse through and familiarize yourself more with the Theme as you become more familiar with Search. The Theme will change over time and you will learn later about how to update the Theme in your repo so that you have the latest and greatest.
Cards, Config, and Pages
You’ll spend most of your time customizing the Cards, Config, and Pages to suit your brand’s requirements. Let’s define these now.
A “Page” and “Config” are put together to make a static HTML page using Jambo Commands. In the Results Pages Overview module, you will learn how to make a universal Search page and vertical Search page. So, when you want to add a “restaurants” vertical in your search experience, you would add a “page”. When you add a page, Jambo automatically adds both the html.hbs and config.json file you need.
For each vertical, you define the “card” you want to use on a page. Result cards control the way that results look on universal or vertical Search pages. You can specify things like the data mappings for the card’s content, the CTAs to drive conversion, and the layout. You’ll learn how to do all of this in the Result Cards module.
Static Assets
In the ‘static’ directory, you’ll find the ability to do things like:
- Update the SCSS
- Add image assets
- Add fonts
- View Javascript formatters
You’ll learn how to do all of this in the Branding & Styling module .
Overriding Parts of the Theme
You shouldn’t change any of the theme files directly (if you were to do this, there’d be no way to update your theme in the future without breaking things). Instead, Jambo provides a first-class method for overriding, also called ”shadowing”, any file in a theme that has been cloned through Jambo Commands . This allows you to easily override any templates that are part of the theme to better suit your use case or use files in the theme as templates to get started.
When you use Jambo Commands to do things, like add a card or override the layout, you are forking the theme. In other words, you’re taking the file that exists in the theme, making a copy of it, and making it your own. Jambo then knows to use your overridden files instead of the matching file in the Themes folder. You will then make modifications to these new files, instead of those that exist in the Theme directly. For example, if you want to:
- Change the data mappings in the card, so you use delivery hours instead of business hours or update the CTA label from “Call” to “Reach Out” on the Location card. You would “Add a New Card” using the Location Card as your template, and then add your customizations.
- Add hardcoded default config for the Search Bar across all pages generated with the Vertical template. You could override the
SearchBarscript partial.
You’ll learn about each of these in this training.
Note: When you use Jambo Commands to ‘Add a Page’ you are just using the page templates provided by the Theme to create a starting point. You cannot use pages directly from the theme.