Introduction to Jambo| 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?
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 Answers, 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?
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:
Jambo vs. the Theme
Unlike you, it doesn’t know anything about the Yext Answers 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, Answers from the Answers 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 Answers Search UI SDK or Answers 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 Answers 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 an Answers 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, an Answers Jambo 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.
The Theme exists as part of the repository. When you create an Answers site using the Answers Jambo Template, you will automatically have the Answers Hitchhiker Theme.
The Theme serves two main functions:
- A translation layer between the configuration files in your code repository and the Answers 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 Answers. 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.
In the ‘static’ directory, you’ll find the ability to do things like:
- Update the SCSS
- Add image assets
- Add fonts
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.
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 Answers 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.
||Use this to fork a card from the theme and customize it. Use this if you want to modify a card from what’s in the Theme to modify layout or data mappings|
||Use this to fork a Direct Answers Card from the theme and customize it. Use this if you want to modify how we handle direct answers by Entity Type or Field Type (for field-value structured direct answers) or to modify the featured snippet card, like modifying the CTAs.|
||Use this to add a page to your search experience. You’ll be prompted to pick a page layout from the theme, like
||Use this to add as a faster way to add vertical pages by creating the page and setting the verticalKey and cardType all at once. Note: This is only available in the new code editor and once you’ve upgraded to the Theme 1.20 EA branch.|
||Use this to override any of the files from the Theme. This will create a copy of the file(s) in your top level directory and update jambo.json to know that you are providing an override. This is commonly used to override things like component behavior in the page templates.|
||Use this command to upgrade to the latest version of the theme. By default, it will upgrade to the master branch of the latest Theme version (recommended) but for more advanced users you can choose to upgrade (at your own risk) to a branch that is still under development, like the early-access branch during the early-access period.|
||Use this if you are adding translation strings to your site to easily extract the strings that need to be translated into a .pot file. You can then upload this file to your favorite translation SaaS (like Smartling) to produce the needed .po files that you can save to your repo’s translation directory. The command will analyze the usage of translated strings throughout your repo and save you some time!|
||Use this if you are starting from a fully blank repo to add the scaffolding / core files Jambo needs for a Jambo Build to work. You’d want to follow with Import Theme to use the Answers Hitchhiker Theme.|
||Use this command with Initialize Jambo if you start from a fully blank repo in order to import the Answers Hitchhiker Theme.|
||Use this if you are developing locally to run Jambo Build. This should automatically be triggered when you change a relevant file if you are using the typical Jambo/Theme setup.|