Building your first Sell app - Part 1: Laying the groundwork
In this five-part tutorial series, you'll learn how to build a Zendesk Sell app from start to finish. The app you'll build is called Learn about Sell. This tutorial covers the first steps to building the app:
The other tutorials in the series teach you how to build and install the app:
- Part 2: Designing the user interface
- Part 3: Creating and inserting templates
- Part 4: Getting data
- Part 5: Installing the app in Zendesk Sell
Because the tutorials build on each other, tackle them in order and finish each tutorial before moving on to the next one.
To download the completed source code of the app in this tutorial, click learn_about_sell.zip. You can review the code as you follow along or check your work.
Note: Zendesk provides this article for instructional purposes only. Zendesk does not provide support for the content. Please post any issue in the comments section below or in the Zendesk Apps community, or search for a solution online.
To build and upload a private app in Sell, you must have Zendesk Sell on the Professional plan or above.
You should have a good idea of how your app will look and work before you start working on it. The app you'll build in this tutorial is called Learn about Sell and is designed to list articles about deals in the Zendesk Help Center. It'll have a simple interface consisting of a button. Here's a mockup of the user interface:
The app will appear in the right sidebar when viewing a deals card in Sell.
The app should work as follows:
- When a user opens a deal card, the app will display the deal card name in the app window
- The user clicks Get docs
- The app makes an HTTP request to the Help Center API for articles related to deals
- The app lists deal article links in the app sidebar
In this section, you'll install the Zendesk app tools (also known as ZAT). Among other tasks, the tools let you perform the following tasks:
- Automatically create all the necessary files and folders for a new app
- Test your app locally in a browser
- Validate your app
- Package your app for upload
Installing the tools is a one-time task. Once installed, you can use ZAT for all your Zendesk app projects.
Follow the instructions in Installing and using the Zendesk apps tools. After you're done, return here to continue the tutorial.
If you have already installed Zendesk app tools, make sure you are using the latest version. To update, in your command-line interface, run
$ gem update zendesk_apps_tools.
After installing the Zendesk app tools, you're ready to start building the Sell app. The first step is to create the starter files for a new app called Learn about Sell in a folder called learn_about_sell.
To create the app files
In your command-line interface (the command prompt in Windows or Terminal in Mac OS X), navigate to the folder where you want the app files to be saved in a subfolder. Use the cd command (for change directory) to navigate to a child folder. Example:
$ cd projects
Tip: To go back up to a parent directory, use cd followed by a space and two periods. Example:
Run the following ZAT command:
$ zat new
If you get an error that the command doesn't exist, make sure the Zendesk app tools are installed. See Installing the Zendesk app tools.
At the prompts, enter the following values:
- author's name - your name
- author's email - your email
- author's url - your website url if you have one, or press Enter to leave it blank
- app name - Learn about Sell
- iFrame URI - press Enter to leave it blank. You'll use the default local iframe file
- directory name - learn_about_sell
The ZAT tool creates and lists the directory and files. The window should look as follows in Mac OS X:
Open your file browser and navigate to the files. The folder contains an assets and translations folder, plus a manifest.json and README.md file. You can add as many files as you need when you're building your app, but for now it's all you need to start building an app. Because it's an iframe app, you can host the app in the Zendesk server infrastructure or on a remote server with any technology stack you prefer. If you're only using client-side technologies like Handlebars and jQuery, as you will be here, you can simply host it in your Zendesk account.
Everything is in place to start building. In the next tutorial, you'll learn more about the HTML file to be iframed into the Sell window. You'll change the heading, add a footer, and add some styles to meet the design requirements specified in Planning the app above. Get started: Part 2: Designing the user interface.