In the previous tutorial in this series, you installed the Zendesk app tools and created the starter files for an app named Learn about Sell. 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:

  1. Setting the app's location in Sell
  2. Reviewing the main HTML file
  3. Testing the app
  4. Cleaning up the default code
  5. Adding a footer
  6. Adding styles

This tutorial is the second part of a series on building a Zendesk app:

Setting the app's location in Sell

You can run a Zendesk app in different locations in the Zendesk Sell user interface. In this tutorial, you set the app's location to the sidebar of the Deal page that opens after an opening a Deal card:

To set the app location in Sell

  1. In a text editor, open the file named manifest.json in your app folder ( /learn_ about_sell/manifest.json ). The manifest.json file is used to configure the app.

  2. Replace the default value of the location property with the following value:

    "location": {   "sell": {   "deal_card": "assets/iframe.html"  }},
  3. Save the file.

Reviewing the main HTML file

Your Zendesk app will live in an iframe in the deal_card location you specified in the previous section. 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 ( learn_about_sell/assets/iframe.html ). Open the iframe.html file in your favorite text editor.

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

<script src=""></script>

After importing the SDK, you can use the ZAFClient.init() method to create an apps API client:

var client = ZAFClient.init();

The client provides an interface between your app and a host application such as Zendesk Sell. 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.

It is recommended to use 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.

To test your app

  1. In your command-line interface, navigate to the learn_about_sell folder. Example:

    $ cd projects/learn_about_sell

  2. Start the local web server included in the ZAT tools by running the following command:

    $ zat server

    After a moment, a status message appears informing you that a local web server has started.

  3. In your browser's private or incognito window, sign in to Sell.

  4. Go to the Deals page and select a deal from the list to open a deal card. The URL should look something like this:

  5. Append ?zat=true to the deal card URL directly and press Enter. The URL should look like this:

    Tip: Bookmark the modified URL for easy access in the future.

  6. If you're using the Chrome browser, the content of your app may be blocked. Click the lock icon on the left side of the address bar and select Site settings. On the Settings page, scroll to the Insecure Content section, and select Allow.

    Note: Firefox doesn't block app content but Safari does and has no option to disable blocking. You must use Chrome or Firefox to work with the local zat server.

The "Hello, World!" heading of the app is specified in the iframe.html file.

Note: If you don't see "Hello, World!", make sure you've updated the location in the manifest.json file. See Setting the app's location in Sell. If you're an existing app developer, make sure you have the latest version of the Zendesk App Tools. See Updating ZAT. If still nothing happens, make sure your Sell account is on the Professional or Enterprise plan and that it's linked to a Zendesk Support account. Sell apps are only supported on these plans.

Review the default layout of the app against your mockup to identify the changes you need to make:

The review gives you your first to-do list:

  • Change the heading
  • Add a footer that displays "Report bugs" with a link to your website where users can report bugs
  • Add CSS to format the user interface
  • Move the CSS and the JavaScript to separate files

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

Cleaning up the default code

  1. Open the iframe.html file in a text editor and replace the "Hello, World!" header string with "Learn about deals in Sell".

  2. Change the h2 inline class from "u-semibold u-fs-xl" to "u-milli":

    <h2 class="u-milli">Learn about deals in Sell</h2>

    The class is defined in the Zendesk Garden which will be discussed later.

  3. Create a file named main.js in the assets folder. Resources such as HTML, JavaScript, CSS, and image files must be located in the assets folder.

  4. Add the following function to main.js :

    $ (function () {   var client = ZAFClient.init();   client.invoke("resize", { width: "100%", height: "200px" });});

    This jQuery statement $(function() {...}); defines a self-invoking, anonymous function that runs after the document is loaded in the browser. The function's two statements are the same as the ones contained in the script tag in iframe.html.

  5. Back in iframe.html , delete the following <script> tag, which is no longer needed:

    <script> // Initialize Apps framework client. See also:  //  var client = ZAFClient.init();  client.invoke('resize', { width: '100%', height: '200px' });<script>
  6. Replace it with the following <script> tag to import your new script:

    <script src="main.js"></script>

    Insert the tag after the <script> tag that references the ZAF SDK to make sure the SDK is loaded in memory before your script runs.

  7. Because your script uses jQuery, import jQuery into your iframe.html file:

    <script src="[email protected]/dist/jquery.min.js"></script>

    Again, insert the tag before the <script> tag that references your main.js file to make sure that jQuery is loaded in memory before your script runs. The body of your iframe.html file should look as follows:

    <body>   <h2 class="u-milli">Learn about deals in Sell</h2>   <script src="[email protected]/dist/handlebars.min.js"></script>   <!-- -->   <script type="text/javascript" src=""></script>   <script src="[email protected]/dist/jquery.min.js"></script>   <script src="main.js"></script></body>
  8. Save both files.

According to the mockup, the footer should display a Report bugs link. The spec specifies that the link should let the user go to your website to report a bug.

To add a footer link

  1. In the iframe.html file, add the following footer tag before the script tags:

    <footer><a href="" target="_blank">Report bugs</a></footer>
  2. Save the file and click the reload apps button above the app.

In the mockup, the link text in the footer is smaller and uses a different typeface. In the next step, you'll add some CSS to start styling your app.

Adding styles

By default, ZAT imports the Zendesk Garden stylesheet in the iframe file:

<link rel="stylesheet" href="[email protected],npm/@zendeskgarden/[email protected]">

Zendesk Garden is designed to be a common baseline of styles and components between all Zendesk products. The default link above doesn't include all Zendesk Garden assets, only the Garden component CSS and CSS utilities. For your app, you'll also need the Buttons component, which you'll import below. A complete list of assets you can import is available from the jsDelivr CDN. See The jsDelivr files are npm packages that can also be installed from npm. See Use the Zendesk Garden assets 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. For example, you could import the popular Bootstrap CSS.

For this tutorial, you'll stick with the Zendesk Garden styles and add modifications in a separate stylesheet named main.css.

  1. In iframe.html , add the Buttons component, npm/@zendeskgarden/[email protected], to the Zendesk Garden stylesheet link:

    <link rel="stylesheet" href="[email protected],npm/@zendeskgarden/[email protected],npm/@zendeskgarden/[email protected]">

    Be careful not to omit the commas that separate the components. See the Garden documentation for the Buttons component.

  2. Add the following <link> tag after the existing stylesheet tag:

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

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

  4. Add the following rules to main.css :

    footer {font-size: 10px;margin-top: 4px;}
    body {margin: 10px 10px 10px 10px;}
  5. Save the iframe.html and main.css files and click the reload app button on your 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, and added some styles.

In the next tutorial, you'll create templates to display a button and the deal card name in the app. Continue to Part 3: Creating and inserting templates.