Your First App

The goal of this tutorial is to help you understand the basics of app development using the Freshdesk app development platform.

To do this, we will create a new app and understand how it works. Every time you create a new app using the Freshdesk SDK, it will create a simple fully functional app to help you get started. This app will be visible on both the ticket details and contact details page showing the Freshdesk logo along with the name of the ticket requester as shown below.

Ticket Details Page

Contact Details Page

Create

Note:
Before proceeding to create this sample app, ensure that you have installed Node.js and the Freshdesk SDK and Developer Extension.


Let’s get started by creating the app. First open the terminal window, and navigate to the directory under which you want to create your apps. Next, type in the following: $ frsh init my_first_app my_first_app is an optional argument that denotes the directory in which the app’s files will be stored.

Once init is successful, you can run the following command to view the app's folder structure:

$ tree my_first_app

The "my_first_app" directory will be created with the app files as shown below:

Code Walkthrough

Let’s take a closer look at the files that were created in the my_first_app folder.


README.md

It is considered a sacred pact amongst developers to maintain a proper README file so that when there is a change in ownership of the code base, the new developer will have an easier time understanding various nuances of the code.


manifest.yml

The manifest file is used to store configuration information for your app.

Copied Copy
1
2
3
4
platform-version: "1.0" pages: - ticket - contact

The platform-version key is automatically generated and used to infer the platform version that your app uses. This will be used to ensure backward compatibility when a new version of the framework is released.

The pages key provides a list of pages where your app is to be rendered. The setting here denotes that the app will be rendered on both the ticket details page and the contact details page.


app/style.scss

This file contains CSS definitions that can be used in your app's HTML.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
.logo { background: url("{{'logo.png' | asset_url}}"); background-repeat: no-repeat; background-size: 33% 64%; background-position: center; height: 41px; } .app-box { border-radius: 3px; background-color: #f5f5f5; height: 70px; padding: 15px 0px; } .app-text { padding: 10px; color: black; font-size: 14px; }
EXPAND ↓

Notice that the file has a .scss extension. SCSS is a enhanced version of css that supports the SASS language. SASS definitions can be used in this file and they will be compiled into CSS by the SDK.

For example, take a look at the background property on line 2. Notice that it makes use of the image file logo.png from the assets/ directory using the liquid notation {{‘logo.png’ | asset_url}}.


assets/logo.png

The assets directory typically contains image, stylesheets and JS library files that are a part of your app. In our example, this folder contains the freshdesk logo file that was referred to in the style.scss file.

External vendor CSS files such as BootStrap (a CSS framework) and HoverCSS (a pure CSS tooltip library) can also be placed here.

Only PNG, JPEG, GIF, JS, and CSS files are allowed in this folder.


app/template.html

This file contains the HTML markup for your app.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
<div class="widget"> <h3>My First App</h3> <div class="content"> <div class="app-box"> <div class="logo"></div> <p id="apptext" class="app-text text-center"> </p> </div> </div> </div>
EXPAND ↓

This file contains the HTML markup for your app. It is a standard HTML file which will be rendered on the user's UI on pages mentioned in manifest.yml. Once this HTML is rendered on a page, the app.js will be invoked.

This file has access to the CSS definitions in your app/style.sccs file.


app/app.js

This file exposes a function initialize that is called whenever your app is rendered in the user's UI on pages given in the manifest. It is expected to be written in standard ES5 JS.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
(function() { "use strict"; return { initialize: function() { console.log("My First App!"); if(page_type == "ticket") { var requesterName = domHelper.ticket.getTicketInfo() .helpdesk_ticket.requester_name; jQuery(this.$container).find('#apptext').text("Ticket created by " + requesterName); } else if(page_type == "contact"){ var agentName = domHelper.contact.getContactInfo().user.name; jQuery(this.$container).find('#apptext').text("Hello " + agentName); } } }; })();
EXPAND ↓

In our sample app, the initialize function makes use of the page_type variable available globally, variable available globally, to display either the ticket requester's name (if we are in the ticket details page) or the contact's user name (if we are in the contact details page).

The app uses the domHelper data API (line 7,12) to retrieve the ticket information or contact information. DOM helper is a library that enables the app to retrieve information, listen for events, and trigger interface actions in the underlying page without manipulating the DOM. This protects your app from any changes in the underlying page.

Once the app has retrieved the necessary information, it then uses JQuery to place the text in the correct class. The this.$container here refers to your app's outer div element.

Next Steps

Now that you understand the basic components of an app, why not build your own?

You can also check out our collection of sample apps. These demonstrate the many features of the app framework such as Request API, Data storage, Oauth, Backend capabilities, and much more.

If you run into any issues, you can reach out to us at support@freshdesk.com or via the chat icon at the bottom right corner of the screen.

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.