Build your first Support app - Part 2: Designing the user interface
Follow

In the previous tutorial in this series, you installed the Zendesk app tools and created the starter files for an app named Requester X-ray. In this tutorial, you'll work on the user interface so that it meets the design requirements of your app. The tutorial covers the following tasks:

Reviewing the main HTML file

A Zendesk app lives in an iframe in the product. Like any iframe app, developing a Zendesk app consists of combining static and dynamic elements in the HTML file to be displayed in the iframe.

The ZAT tools created a default HTML file called iframe.html in your assets folder (xr_app/assets/iframe.html). The HTML file defines the visual elements of your app -- such as the header -- that don't change when the app changes states. Open the iframe.html file in your favorite text editor.

To interact with the Apps framework, the HTML file must import the ZAF SDK v2 library in a script tag:

After importing the SDK, you can use the ZAFClient.init() method to create a Zendesk JavaScript API client:

var client = ZAFClient.init();

The client provides an interface between your app and a host application such as Zendesk Support. The client gives you a number of methods to interact with the Apps framework. Use the get() and set() methods to read and write data in the framework APIs. Use the invoke() method to run methods in the framework APIs. Use the request() method to make HTTP requests to any REST API. Use the on() method to listen to events. The starter file gives an example:

client.invoke('resize', { width: '100%', height: '200px' });

Testing the app

Your app doesn't do much yet but you can already run it using the ZAT tools. Run your app often to test your latest changes.

I highly recommend using private browsing or the Incognito mode in your browser when testing and developing apps. Your browser may cache certain files used by the app. If a change is not working in your app, the browser might be using an older cached version of the file. With private browsing, files aren't cached.

To enable private browsing in Chrome, click the menu button on the upper-right corner of the browser window and select New Incognito Window. In Firefox, click the menu button on the upper-right corner and select New Private Window.

Test your app

In your command-line interface, navigate to the xr_app folder. Example if you're in the projects folder:

$ cd xr_app

Start the local HTTP server included in the ZAT tools by running the following command:

$ zat server

After a moment, a status message appears informing you that the server has started (WEBrick::HTTPServer#start).

In your browser's private or incognito window, navigate to any ticket in Zendesk Support. You'll need to sign in as an agent or administrator. The URL should look something like this:

https://subdomain.zendesk.com/agent/tickets/123

Append ?zat=true to the ticket URL, and reload the page.

The URL should look like this:

https://subdomain.zendesk.com/agent/tickets/123?zat=true

Tip: Bookmark the modified URL for easy access in the future. You might also want to create a dummy ticket for app testing.

In your browser's Address bar, click the shield icon on the left (Chrome) or lock icon on the right (Firefox) and agree to load an unsafe script (Chrome) or to disable protection (Firefox). If you don't do this, the browser will block your app.

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

The app should appear in a panel on the right side of the agent interface:

Even if the app appears in a Zendesk Support page, it's actually running locally on your machine.

Note: If nothing happens, check for a shield or lock icon in the Address bar. See step 5.

The framework displays a "Requester X-ray" heading that's not defined in the iframe.html file. The heading is defined in the manifest.json file in your app's root folder.

Open the manifest.json file in your text editor. The file already contains values you supplied when you created the app files.

The heading is defined in the name property ("Requester X-ray").

You're free to change or delete all the HTML markup in the iframe.html file. Review your mockup to identify the changes you need to make:

The review gives you your first to-do list:

Clean up the default code, which includes deleting the "Hello, World!" heading and moving the JavaScript to another file

Add a footer that displays "Report bugs" with a link to your website where users can report bugs.

Add styles to format the footer

Replace the default logo in the header

Note: You can ignore the main content for now. You'll insert it with a template in the next tutorial in the series.

Cleaning up the default code

Start by deleting the <h2> heading in iframe.html.

Create a file named main.js in the assets folder.

In main.js, add the following function, which contains the JavaScript code in iframe.html:

Adding styles

Zendesk Garden is designed to be a common baseline of styles and components between all Zendesk products. You can use the Zendesk Garden stylesheet if you want your app to match the look and feel of Zendesk products.

You don't have to use Zendesk Garden in your future projects. The choice is yours. In this tutorial, you decide to use the popular Bootstrap CSS as the base stylesheet for your app. You'll add any modifications in a separate file named main.css. :

In iframe.html, replace the Zendesk Garden <link> tag with the following Bootstrap <link> tag:

Add a link to a stylesheet named main.css after the Bootstrap <link> tag:

<link href="main.css" rel="stylesheet">

Create a file named main.css in the assets folder.

Add the following rule to main.css to style the footer:

footer {
font-size: 10px;
padding-top: 20px;
}

Save the file and click Reload Apps in Zendesk Support.

The next task is to change the logo.

Changing the logo

By default, the framework displays the image named logo-small.png in your assets folder. To change the logo of the app, just replace the logo-small.png file in the assets folder with your own image.

Your replacement logo-small.png file should meet the following specs:

Size: 128x128 pixels. The CSS will scale the image to fit the header. The same image will also be used in the Zendesk Support user interface later and scaled accordingly.

File format: PNG-24 with transparency.

Border: None because the corners will be rounded by the CSS.

The assets folder also includes a logo.png image. Replace this image with a 320x320 version of your logo. The 320x320 version will be displayed in the Apps Marketplace where admins browse for public and private apps to install.

Change the logo

Right-click each of the following image links and download them into the assets folder in your app folder. If prompted, agree to overwrite the existing version of the files.

To see the updated image, you'll need to do a hard refresh of the page in Zendesk Support. See the instructions for Firefox or Chrome on their respective websites. You can also clear your browser cache or paste the URL into another browser.

If you're moving to the next tutorial, you can leave the ZAT server running. If you're done for this session, you can shut down the server by switching to your command-line interface and pressing Control+C.

In this tutorial, you cleaned up the iframe.html file created by the ZAT tools, moved the JavaScript in a separate file, added a footer, added some styles, and replaced the logo to meet the design requirements of your app.

Wonderful tutorial. I really like how not only instructive you are at every step, but also how you explain the whys and the hows - I've never used Handlbars.js up until now and I found it extremely useful of you to explain what the {{tags}} do!

Could you please specify (if there is a reason) as to why the script tags are in the body and not in the head in iframel.html?

Also, I have managed to complete this tutorial with no problems, however my app's 'name' shows 'Local App' in the browser but my manifest file shows 'Requester X-Ray' - any idea what the problem could be?

Glad the tutorial is helpful, Chris. The reason the script tags are just before the closing body tag is that it can help improve the render time of the page (in the case, the iframe content). The browser stops rendering the page while any JS libraries are being downloaded. With large JS libraries, it could make a difference to the user experience. See this blog post on the Yahoo Developer Network for more info.

As for "Local App" showing up in the browser, do you mean the heading of the app displayed in the sidebar?

Ok, I updated my ZAT gem and I see what you mean about "Local App" showing up in the header of the app. In fact, the 'name' property in manifest.json isn't used at all at this point. There's an open ticket with the framework engineering team to investigate the issue.

Instead of doing a hard refresh or clearing the cache after making changes to your app, you can just disable the cache while you have your browser's developer tools open. With that setting enabled, you only need to click the "Reload all apps" button in Zendesk. I usually have the dev tools open anyway, but it's also pretty easy to shrink them down or pop them out to another window if they're in your way.

Here are the instructions on how to enable the setting in Chrome and Firefox.

Chrome

Open the developer tools (command + option + i on Mac; ctrl + shift + i on Windows).

Select "Settings" from the dev tools menu or press F1.

On the Preferences tab under "Network", check "Disable cache (while DevTools is open)".

Firefox

Open the developer toolbox (command + option + i on Mac; ctrl + shift + i on Windows).

hello Charles hope you're doing well, i was just reading this article to create my new app(Zendesk App) and this article is helping me a lot for getting done my part.

I just want to confirm if i create Application on my local instance (Localhost in my local machine) . Will it work with my domain which is created by zendesk on live server i just getting confused. Can you please help me out with this issue !

Sorry to sound like an utter noob here. I am trying to integrate this with a react framework and I really just can't follow how to get this running, what the goals are, etc. I've created the app in my react framework, and incorporated the script in my HTML file. Every time I try to run the zat server and go to the URL It gives me a Sinatra error. Is there any information on how to get this running in react? The docs are very thorough but I am utterly confused by everything.

Thanks for writing in. May I ask you please share what the error being thrown by Sinatra is? We don't have documentation specific to using Reactjs in your application, but the error should be a good place to start troubleshooting.

That looks like the Sinatra web server is running correctly on port 4567 with no error. The message used in this article may be dated, so it's best to follow that output there. Is it possible you didn't allow unsafe scripts in your browser?

@Joe- I am going to create a ticket for your issue, please be on the lookout for it.