Navigate the Code Editor | Yext Hitchhikers Platform

What You’ll Learn

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

  • Create and share a new code editor session
  • Define what Live Preview, the console, and Jambo commands are and when to use them
  • Complete the code commit process with properly formatted commit messages and tags

Overview

In the Code Editor, we pull in all of the files from your Github repository so that you can commit changes just like a developer. The Code Editor is similar to a code repository in Github, except it’s even easier to quickly move around and load multiple files at once.

Code Editor initial screen

To open the Code Editor in Pages, navigate to Pages > [[Your Site]] > Deploys and then click the Code Editor button in the top right.

Code Editor Button on Pages Deploys screen

To open the Code Editor in Classic Pages, navigate to Pages > [[Your Site]] and then click the View Code Editor button on the right side of the page next to the Custom Development section.

Code Editor Button on Classic Pages site screen

Branches

One of the first things you will see when opening the Code Editor is a list of branches. A branch is a named version of your repository. By default, you start with only the master branch.

To start editing, hover over the branch name and click the pencil icon that appears to the right. This will open the Code Editor view where you can start modifying code. By default, you should make changes on the master branch, unless you’re working with a developer.

Code Editor default branches list

You can create new branches for your work if you are making complex changes that need extra QA and that you don’t want to make on the main branch. Then you can merge those branches together when you’re ready. To create a new branch in the Code Editor, hover over the “master” branch, select and click Create new branch. In the modal, input a branch name and click Create Branch. In most cases you should be branching off of the master branch.

This is a standard git workflow. If you’re interested in learning more, here’s a  great tutorial .

Session Management

When you open up the Code Editor, you are either starting a new session or resuming a session (you’ll see a small toast message if you are resuming a session). If you leave the Code Editor or hard refresh the page, you don’t lose any of your work! You will still be in your session. Your session will remain active for four hours and in “paused mode” for up to two days. After that, you will automatically start a new session.

You can also share your session with a teammate by copying the URL with the session ID in it.

If you want to discard all of your code edits and begin a new session, you’ll want to terminate your session and then navigate back into the code editor. You can go to Tools > Terminate Session to terminate your session. This is recommended if you have made commits outside of the code editor that you need to retrieve.

Live Preview

The Live Preview compiles the latest information in your Code Editor to show you what it would look like if you were to commit your code and publish your page in its current state. This allows you to catch issues or experiment as you build.

Live Preview to check code changes

View Live Preview

By the time you’ve navigated to the code editor, your preview is already there and ready to go! All you need to do is click View Live Preview at the top of the code editor to open your local site in a new tab in your browser.

light bulb
Note
When you are building a Search site from scratch, you will need to connect a backend experience to the frontend and add a universal search results page before seeing the live preview display properly.

As you’re making changes, click outside of the Code Editor to update your preview. If you refresh your preview tab while an update is in progress, you’ll see an error page – don’t be alarmed! Just wait for your preview update to complete and refresh the page. You will know an update is complete when you open the console (we will talk more about this in the next section of this unit!) and see this “Completed” message:

console task complete message

You can also share your preview link with others or use the link to open up your changes in different browsers. Note that the preview link will expire after a few hours.

Note: If you click “View Live Preview” before an index.html file exists on your site, you will be presented a directory where you can choose which page you want to preview. Keep in mind that if you haven’t actually created any pages yet, you won’t see any HTML files to preview — there’s nothing to preview yet! You need to create at least one page for this to work.

Restarting Live Preview

You’ll need to click “Restart Live Preview” after any time you’ve updated dependencies. A dependency is when one component of software relies on another to work.

For example when you do a theme upgrade , you are updating the library that the Code Editor is pulling from. The files (and therefore the live preview) you are working from in the Code Editor directly rely on the Theme to display the frontend properly so you’ll need to restart preview.

Another example of when you would restart live preview is if you’re updating the experience key in the locale_config.json file since this changes the backend you’re linking to.

The Console

As you’re updating your preview, you can (and should!) view the console in the code editor to see if there are any errors. If you open up the console, you’ll see a preview refresh start building immediately when you have a code change and click out of the code editor. You’ll want to make sure that the console says that the preview is ready before you try to refresh to see your latest changes. As mentioned in the Live Preview section, you will want to keep an eye out for the “Completed” message in the console to indicate you preview is ready.

You can access the console by clicking on Tools > Console. This won’t be selectable unless you’ve started the Live Preview process.

Tools button dropdown with console highlighted

Jambo Commands

To do things like add pages or override the theme, you will use “Jambo Commands”. As mentioned, we use Jambo under the hood in the Code Editor.

Jambo has a number of built-in Commands, such as adding pages and cards. 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.

You can access Jambo Commands by clicking on Tools > Jambo Commands, which will open a modal with all Jambo command options.

To see the full list of commands, view the Jambo Overview reference doc.

Updating Code

To update a file, it’s as easy as navigating to the file you want to update, typing in what you want to change, and committing the code.

The Files section on the left of the Code Editor lists out the folder structure and all the files included in the repo.

When you click on a file name, the file will appear as a tab in your workspace. You can also do things like add new files or delete files by hovering on a directory or file and clicking the add or trash icons.

Update Global and Locale Configs

In order to get search up and running, you need to update up to three properties in the locale_config.json and the global_config.json files.

  1. Connect the Frontend and the Backend

    The experienceKey in the locale_config.json file must be filled out to match what is listed in the backend experience you have created. To find your experience key, go to the Search > [[Your Experience]] > Experience Details screen. To learn more, see the Global Settings and Local Configuration reference doc.

    "default": "en",
    "localeConfig": {
      "en": {
        "experienceKey": "brand-search" //  the unique key of your search configuration for this locale
      }
    }
  2. Update Locale for Non-English Experiences

    If your search experience is not in English, update the locale property in the locale_config.json file. This defaults to ‘en’ out of the box. If your search experience is based in Great Britain, you may decide to use the locale ‘en_GB’ even if it is in English. This locale should tie to what is specified in the corresponding backend config, which in turn specifies which language profiles to pull from entities in Content.

  3. Update Cloud Region if in the EU

    If you are located in the EU and you want your data to be hosted in the EU, update "cloudRegion" to "eu" within the global_config.json file. This defaults to "us".

book
Note
You must be on Theme v1.31 or above to set the cloud region. Check out the Upgrade the Theme and SDK module for more info and the Theme Upgrade guide for step-by-step instructions on upgrading.

Commented Out Code

The code editor will format and color the code to make it easier to read and understand. Any comments or code in green are “commented out”.

Each coding language, and thus each file type (.json, .hbs, .scss), has different syntax for commenting out code. For example, in Handlebars files (.hbs), you encase the code in {{!-- --}}, and in JSON files you’ll see // for single lines or /** **/ for blocks.

When you comment something out or if something is already commented out, the code will be ignored and the component will not render in your experience.

Example of comments in a Handlebars file:

Pages Handlebars file with comments

Example of comments in a JSON file:

Pages JSON file with comments

The comments are there to provide you with more information OR to provide you with sample code that you can easily use. If you want to use the code, simply remove the characters that are creating the comment. Be careful that you remove the whole syntax, otherwise, you’ll run into errors. For example, in a Handlebars file, you need to make sure you remove the characters on both sides of the code:

With comments:

{{!– {{> templates/vertical-standard/script/sortoptions }} –}}

Correctly removed:

{{> templates/vertical-standard/script/sortoptions }}

Incorrectly removed:

{{!– {{> templates/vertical-standard/script/sortoptions }}

or

{{> templates/vertical-standard/script/sortoptions }} –}}

light bulb
Note
You can easily comment-in or comment-out code via keyboard shortcuts. Try cmd + / on a Mac or ctrl + / on a PC.

Reset Changes

You can see a list of all of the files that you’ve updated in the “Staged Changes” section in the top left, including any updated files (yellow), added files (green), or deleted (red) files. If you want to undo changes to any file, you can hover on the file name and click the “X” icon next to the update. To undo all changes, you can click “Reset”.

Staged Changes module with updated files in Code Editor

Troubleshooting Errors

The Code Editor will help you find errors before you commit the code!

Within a file, you’ll notice there is an error in two ways:

  1. Red underlining, typical of an error in any text editing program
  2. A red indicator on the right side

Code error red underline and indicator in the Code Editor

If you hover over the underlined text, you’ll see a message that might be able to help you identify the issue:

Error message on hover for code with red underline

Here, it says “Expected comma” – that’s because there is a missing comma on line 11, directly before the underlined text in line 12.

If you’re not sure which file is causing an error, open the Code Editor console and look for error messages that point you to the right file.

Apply Diffs

You can collaborate with coworkers or share commits between repos easily using “Apply Diffs”. All you need is the diff file and you can view and preview the changes or edits made to your repo.

To use this, navigate to Tools > Apply Diffs, enter a URL, click View to see what the diffs contain, and click Apply to add to your staged changes. All you need is a .diff or .patch file stored in a publicly accessible URL.

Apply Diffs modal view and apply process

Committing your Code

Once you are done making changes to your code, you can click Commit under the “Staged Changes” section. This will start the process of saving your updates by opening the “Commit Changes” modal.

Commit Changes modal with message and tag inputted

Commit Message

The Commit Message lets other users know what the commit was for (i.e., what kind of changes were made) and is a standard practice in development. Keep your commit message succinct but descriptive.

Tag (Optional)

If you add a Tag to a commit, it will be easier to publish these specific changes. You will read more about publishing and deploying experiences in the next unit.

We recommend using something like a date system or a semantic versioning system to keep track of your commit tags, such as these Git conventions . Something like “2020-05-02” is valid but a short phrase such as “starting point” is not a proper name for a tag.

You can always go back to a commit and add the tag later on by clicking into a “recent commit” on a branch (we’ll cover this in the Deploy an Experience unit).

Managing Commits

If you want to view recent commits you can navigate to that first screen of the Code Editor where the list of branches are.

Code Editor recent commits list

Here, you can click into a commit and see the files and lines of code that were changed. You are also able to assign a tag to the commit if you didn’t do it during the original commit process.

Code Editor recent commits list

unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 4

    How do you know if there might be errors in your code?

    Error Success Question 2 of 4

    How often should you use Live Preview?

    Error Success Question 3 of 4

    Can you share your preview link with others?

    Error Success Question 4 of 4

    Which is an example of proper commit tag formatting?

    Soon you'll be your brand's hero! 🎓

    You've already completed this quiz, so you can't earn more points.You completed this quiz in 1 attempt and earned 0 points! Feel free to review your answers and move on when you're ready.
1st attempt
0 incorrect
Feedback