Introduction to Jambo | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• What is Jambo
• Why Jambo is so great
• Jambo vs. The Theme
• Overview of Cards, Configs and Pages

What is Jambo?

At its core, Jambo is a static site generator (SSG) that relies on the JAM architecture (outlined here: Jamstack | JavaScript, APIs, and Markup ). Written in Javascript, Jambo operates on a set of JSON files and Handlebars templates to produce static HTML files that can be served from a CDN.

In addition to generating the static files to serve to consumers, Jambo also provides some additional commands to make developing experiences on Yext easier for both Admins and Developers. We call these Jambo Commands.

While this training is going to introduce Jambo and its commands in the context of Search, keep in mind that Jambo in the future will work with any type of page experience.

What is Jamstack and why is it so great?

JAMstack is a modern way of building websites and apps that delivers better performance, higher security, lower cost of scaling, and a better developer experience. This modern architecture enables you to use JavaScript (J), reusable APIs (A) and prebuilt Markup (M) to build digital experiences.

Building with JAMstack enables better performance. With JAMstack, you generate pages at deploy-time since they are mainly stored as Markup and can be delivered over a CDN. As a result, the most recent and up-to-date version of every page is online and accessible from multiple points of presence across the globe. This structure allows you to deliver better performance through fast page load speed, no run-time errors, continuous updates and more.

Running a JAMstack web app also enables low cost of scaling. The cost of running a JAMstack web app uses fewer resources since things like servers and databases are not necessarily needed - these are cumbersome, expensive investments. In addition to providing better performance, CDNs help with scalability too, since they can serve deployments from anywhere.

Building with JAMstack delivers better security due to minimal exposure and ease of maintenance. Traditional server-side and CMS applications expose lots of APIs and services to manage data and content. All of these are at risk of attack and require continuous effort to patch and maintain. In contrast, when using JAMstack, you’re using static files - these are read-only and not susceptible to the same types of attacks. There is no code to run and therefore no vulnerabilities to exploit.

Finally, building with JAMstack delivers a much better experience to developers. With the JAMstack, there is no tight coupling between the application backend and frontend. This means that you can select which solution works best for you among different CMS and content infrastructure options. Developers have access to more targeted development and debugging due to the loose coupling and separation of controls.

Want to know more? You should - it’s awesome! We recommend some of the following additional reading materials when you have the time:

• https://jamstack.org/resources/
• https://jamstack.wtf/#what-is-jamstack
• https://snipcart.com/blog/jamstack
• https://www.freecodecamp.org/news/an-introduction-to-the-jamstack-the-architecture-of-the-modern-web-c4a0d128d9ca/

Jambo vs. the Theme

Jambo itself is not a super complex piece of software. It is a command-line tool that follows a set of generic rules, and uses Javascript and Handlebars (a templating language in Javascript that you’ll learn more about in this training) to take an input set of template files and generate static HTML that can be hosted in a CDN and deployed as your website (aka it takes the code in the code editor and turns it into web pages that you and your consumers are used to).

Unlike you, it doesn’t know anything about the Yext Search UI SDK or that it even exists. Jambo’s sole purpose is to build the website quickly, efficiently and easily. Like other website generators, it doesn’t rely on any magical server-side code that determines what the frontend will render - all of the display code lives entirely in the website’s templates. The backend servers exist only to provide data to the page (in our case, search from the search system).

What does this mean to you (especially if the above statements go over your head)? You have one consolidated place to update the code, improved page loading performance and better scalability!

So, we’re saying Jambo is dumb and it knows nothing about the Search UI SDK or Search API. How is that even possible?!

That is where the Theme comes in.

All of the knowledge about setting up the SDK/API and the workflow to configure it are defined by the Answers Hitchhiker Theme. You can think of the Theme as an architect and Jambo as the contractor. The architect’s role is to specify the overall design with blueprints. The contractor takes material and blueprints and produces the finished product, in this case, web pages. The theme leverages the templating power of the Jambo tool to allow Hitchhikers to work with an intuitive set of markup and configuration files, converting these files into raw html files that make all of the needed, complicated calls to the Search UI SDK. It takes all of the complication out so that you don’t need to be a developer to build an experience!

Jambo has a set of built-in commands, available for any kind of site, like “Add Page”. The Answer’s Theme can additionally add extra, custom commands, such as “Add card”. These are known as Jambo Commands. Everything about the theme exists to streamline the process for Hitchhikers to set up a Search site. It can and will be iterated on in the future as Hitchhikers discover common workflow patterns that would benefit from more automation!

You saw a preview of the end to end process of updating your repo in Unit 1. Now let’s do a deep dive into what the repo looks like.

Jambo/Theme Repo File Structure

Remember that a repo is just a collection of files. Structurally, a Searach 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.po

In 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 Answers Hitchhiker Theme.

The Theme serves two main functions:

1. A translation layer between the configuration files in your code repository and the Search UI SDK.
2. 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

As an Admin, 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 (explained more below). In a future 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 Global Config, Cards & Pages 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, copying it, and making it your own. Jambo then knows to use your overridden files instead of the matching file in the Theme. 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 SearchBar script 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.

Jambo Commands

To do things like add pages or override the theme, you will use “Jambo Commands”. As mentioned, Jambo is a Command-Line-Interface (CLI) and in the Yext UI we are using it under-the-hood in the Code Editor.

Jambo has a number of built-in Commands, plus Themes can add on their own custom commands. The Answers Hitchhikers Theme adds a number of commands to make developing Search faster and easier.

Below are the full list of Jambo Commands available when using Jambo + Answers Hitchhiker Theme together that you will see in the Code Editor UI. Some of these commands you’ll use frequently, while others you may never use. Don’t worry about whether these commands make sense yet – they shouldn’t! You can come back here and reference this later though as you learn more about these commands in-context.