Previewing theme changes locally

You can export a theme's files from Guide and work on the files offline in your favorite editor. To avoid zipping and importing the files into Guide every time you want to preview your changes, you can preview each change locally in a web browser using the Zendesk apps tools, (ZAT). To preview a change, you simply save the theme file in your desktop editor and refresh the page in the browser. Example:

ZAT is a collection of developer tools that includes Sinatra, a web server that runs locally on your computer. After starting the preview mode, the process runs in the background. See the command-line interface on the lower side of the image.

Topics covered in this article:

• Setting up local theme preview
• Starting local theme preview
• Previewing changes

Setting up local theme preview

To set up local theme preview

1. If not already done, enable API access in your Zendesk Support account by going to Admin > Channels > API.
2. Install the Zendesk apps tools, (ZAT).

   See Installing and using the Zendesk apps tools in the Develop help center.

3. If you previously installed ZAT to build Zendesk apps, make sure to update it by running the following command in your command-line interface:

   $ gem update zendesk_apps_tools

To install and use ZAT, you'll need a command-line interface, (CLI). In macOS, you can use Terminal in the Applications/Utilities folder. In Windows, you can use the command prompt or Powershell. If you're a Windows 10 user, you can install and use a Bash shell, a more developer-friendly CLI. See Setting up a Bash shell in Windows 10.

Starting local theme preview

You should start local theme preview before you start working on theme files on your computer.

To start local theme preview

1. In your command line interface, navigate to the folder containing the exported and unzipped theme files.

   Use the cd command (for change directory), to navigate to a child folder. Example:

   $ cd guide_themes/newlook_theme

   To back up one directory, use cd followed by a space and two periods. Example:

   cd ..

2. Run the following command:

   $ zat theme preview 

3. At the prompts, enter your Zendesk Support subdomain, as well as the email and password you use to sign in to Zendesk Guide.

   

   The subdomain and email are saved in a text file named .zat in the theme's folder so that you only need to enter your password the next time you start preview mode. If you make a mistake entering your username or password, delete the .zat file and start again. Note that files with leading periods are hidden in macOS by default. See Show Hidden Files in Mac OS X on the osxdaily.com website.

   If you use single sign-on (SSO) to sign in to Guide (such as using Google or Microsoft credentials), you can sign in using an API token that you can get from the Support admin interface. See API token in the REST API docs. When prompted by ZAT to sign in, enter {your_email}/token for your user name, where "/token" is the actual string "/token". Use the actual API token for your password. Example:

   Enter your username: [e-mail]/token
   Enter your password: e8Pvy0pvGzE8meUQxWgjIYkjr

   After successfully signing in, preview mode starts and runs in the background:

   

4. Copy the "Ready" URL in the output and paste it in a browser.

   In the example, the URL is https://nadosolutions.zendesk.com/hc/admin/local_preview/start.

   An unformatted page loads after you sign in. Modern browsers have a security feature that blocks certain local files (known as mixed content) from loading in a page. You can disable the feature in Chrome and Firefox as described in the following step.

5. In Chrome or Firefox, click the shield icon in the Address bar and agree to load an unsafe script (Chrome) or to disable protection on the page (Firefox). In Firefox, the shield icon is located on the left side of the Address bar.

   

   Note: Safari has no option to disable protection. You must use Chrome or Firefox for previewing.

   The correctly formatted page should load automatically. You can start editing theme files in your editor and previewing changes locally in the browser.

Previewing changes

After starting the theme preview mode, you can work on your theme files in your favorite editor. Work iteratively to develop and test your theme. For example, make some changes to your JavaScript, save the changes, then refresh the browser page to test the changes.

To preview changes

1. Save the edited file in your editor.
2. Refresh the page in the browser.

When you're done for the day, you can stop preview mode using one of the following methods:

• Switch to your browser and click the "To exit, click here" link at the top of the previewed page.
• Switch to your command-line interface and press Control+C.