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
To set up local theme preview
- If not already done, enable API access in your Zendesk Support account by going to Admin > Channels > API.
- Install the Zendesk apps
tools,
(ZAT).
See Installing and using the Zendesk apps tools in the Develop help center.
- 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
- 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 ..
- Run the following command:
$ zat theme preview
- 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: jdoe@example.com/token Enter your password: e8Pvy0pvGzE8meUQxWgjIYkjr
After successfully signing in, preview mode starts and runs in the background:
- 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.
- 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
- Save the edited file in your editor.
- 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.
92 Comments
Awesome! Much awaited feature. Thank you.
Hi Ryan,
Are there provisions going to be made for accounts that have disabled password based authentication, as this affects API auth as well.
Hey @Dan,
It appears that there is a workaround with using an API token as a password for customers currently using SSO. I am working with some teams internally to get this documented and published and I can let you know when it's published.
Thanks!
How do I get rid of this warning when previewing a theme locally?
Mixed Content: The page at 'https://backlog.zendesk.com/hc/en-us' was loaded over HTTPS, but requested an insecure stylesheet 'http://localhost:4567/guide/style.css'. This content should also be served over HTTPS.
Hey @Shammel,
You'll need to make your browser allow unsafe scripts. In Chrome, it's fairly easy and you can take a look at the screenshot here https://cl.ly/2p0Z0D1e3x0Z
Other browsers should be similar.
Thanks, @Ryan.
But I already did that, which allows the CSS and JS to load. The problem is they are loading over HTTP when the page itself is loading over HTTPS.
When developing locally, you're serving from the filesystem, by default that will be without HTTPS, as no SSL certificates will exist.
This error should be showing when doing local development.
When you upload your theme to Zendesk Guide, the resources will be hosted under HTTPS (assuming you have an SSL certificate), and you should no longer get those errors.
Ok. Thanks @Dan.
@Ryan Is there any documentation on this for users that are using SSO yet?
@Shane,
You need to set up an API token and authenticate with that if you are using SSO.
See more in https://developer.zendesk.com/rest_api/docs/core/introduction#api-token
Your username is: {email}/token and the password is {token}
Hope this helps :)
We've updated the docs for ZAT here - https://developer.zendesk.com/apps/docs/apps-v2/getting_started#create
Hi there,
I am doing local development and every time I am saving changes the live reloading is throwing this error
What is wrong here?
Thanks
@Trapta,
I haven't seen this error before. Have your tried restarting the ZAT preview session to see if that fixes it? You should be able to hit ctrl-c to kill the process, then type zat theme preview again and navigate to the theme preview start URL.
Thanks!
@Ryan,
I did it several times but that doesn't fix the issue.
Thanks
Trapta
@Trapta,
Is it possible something else in your environment is using port 4567 while you're running this? It could be that is colliding with live reload for ZAT. We haven't seen this issue before, unfortunately.
Thanks!
@Ryan,
I have checked that too and there is no other environment using this port.
Thanks
Hmm... I'm not really sure @Trapa. It seems like something on your machine is preventing you from using that port. I haven't seen it reported it by anyone else, so it's hard to diagnose. We're using this library which doesn't have any open issues related to what you're running into - https://github.com/faye/faye-websocket-ruby
Hello folks! I'm running into an issue where I can't get the server to even start running. I have nothing else running on the same port, and I've got root-level permissions on this machine, so I'm not sure the issue.
Here's the error:
(this sets off a slew of other errors, but this seems to be the cause).
I've tried manually setting a different port (with something like zat theme preview -p --port=9200), but I still hit the same error. I've done some googling, but all of the suggestions are coming up useless.
Any advice would be greatly appreciated!
Hi Emily! I'm checking with our Developer Support team to see if they can help out here.
Thanks, you're a hero @Jessie! 🙌
Hi Emily -- sometimes a server can "stick" and still be running in the background -- see if it's still running (where '4567' is the default port number):
You can then kill the process that gets returned using:
Hey Bryan—thanks for following up!
Unfortunately, I don't get any returns when I grep the port number—just comes back with nothing. I tried running a gem update, but no dice on that either. And sadly the restarting didn't come up with anything.
Do you know if this might be IP address related? I've read a few things about the IP address not binding correctly (as shown in one of the answers here: https://stackoverflow.com/questions/27851440/eventmachine-start-tcp-server-no-acceptor-port-is-in-use-or-requires-root), but I wasn't sure if that was entirely accurate in this use case, since the preview URL is hosted by Zendesk.
Thanks again for looking into it!
Hi Emily -- just circling back here... is this still happening? Between the time it worked and stopped working, do you recall anything changing?
I'm thinking maybe your development environment has issues. Maybe it's been a while since you set it up and something has gotten out-of-date between the Ruby version you're running and the expected Ruby gems that ZAT depends on. I've tried running 'zat theme' on a Ruby 2.3 install of my own and it works, so I don't think there's anything fundamentally wrong.
What I'd like you to try is to set up your development environment following the steps in this article (and the subsequent ones it references). It gets you to a stable environment along with installing tools such as rbenv and nodenv that let you switch between Ruby and Node versions easily. Can you set things up using these instructions and give it a try again?
https://develop.zendesk.com/hc/en-us/articles/360001069127-System-prep-for-app-developers-1-Setting-up-your-command-line-interface
Heya! I'm getting an error when running `zat theme preview`. I've installed the `rack` gem in case that might be in, but no change. Any help?
Thanks!
/Users/drewbeck/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:135:in `require': cannot load such file -- rack (LoadError)
from /Users/drewbeck/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:135:in `rescue in require'
from /Users/drewbeck/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:40:in `require'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/sinatra-1.4.8/lib/sinatra/base.rb:2:in `<top (required)>'
from /Users/drewbeck/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:59:in `require'
from /Users/drewbeck/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:59:in `require'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/zendesk_apps_tools-2.9.3/lib/zendesk_apps_tools/theming/server.rb:3:in `<top (required)>'
from /Users/drewbeck/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:59:in `require'
from /Users/drewbeck/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:59:in `require'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/zendesk_apps_tools-2.9.3/lib/zendesk_apps_tools/theme.rb:132:in `start_server'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/zendesk_apps_tools-2.9.3/lib/zendesk_apps_tools/theme.rb:29:in `preview'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor/command.rb:27:in `run'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor/invocation.rb:126:in `invoke_command'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor.rb:369:in `dispatch'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor/invocation.rb:115:in `invoke'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor.rb:242:in `block in subcommand'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor/command.rb:27:in `run'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor/invocation.rb:126:in `invoke_command'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor.rb:369:in `dispatch'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/thor-0.19.4/lib/thor/base.rb:444:in `start'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/gems/zendesk_apps_tools-2.9.3/bin/zat:13:in `<top (required)>'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/bin/zat:23:in `load'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/bin/zat:23:in `<main>'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/bin/ruby_executable_hooks:15:in `eval'
from /Users/drewbeck/.rvm/gems/ruby-2.3.1/bin/ruby_executable_hooks:15:in `<main>'
I have been attempting to login using `zat theme preview` and the following format (with variations) in .zat:
Can someone tell my why this may not be working? This is the error:
@drewbeck Did you have a look https://develop.zendesk.com/hc/en-us/articles/360001075068? Some similar problems are discussed there.
@Maria, Your "username" should be just "mysername@email.com/token" and the password should be "my-token-from-active-api-tokens"
@Augusto: where are "my-token-from-active-api-tokens" found? B/c what you describe is what I have, but perhaps I grabbed the wrong token.
Actually, never mind. I read more closely and realized I had misunderstood the documentation. Here is what is in my .zat file, and it works:
I ended up here while I was trying to troubleshoot the error that Emily mentioned earlier, with
I figured out that there was something wrong with my /etc/hosts file, and "localhost" wasn't routing to 127.0.0.1 properly. So, if you're in the same boat while trying to use zat, try restoring /etc/hosts to default. (I'm on macOS High Sierra)
Thanks for sharing, Collin!
Please sign in to leave a comment.