Your First App

The goal of this tutorial is to help you understand the basics of app development. Here, you will build an app using the Freshworks platform.

For this tutorial, choose the your_first_apptemplate. This app will be visible on the Lead landing page and will display the name of the lead along with sample text as shown.


Create

Note:
Before proceeding, ensure that you have installed Node.js and the Freshworks CLI.

To get started, open the terminal window, navigate to the directory under which you want to create your app, and type the following command. Note that this directory must be empty. $ fdk create --products freshsales your_first_app The app is created with the following directories and files.

Code Walkthrough

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

README.md

Developers need to maintain a proper README file so when there is a change in ownership of the code base, a new developer can easily understand the various nuances of the code.

manifest.json

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

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
{ "platform-version": "2.0", "product": { "freshsales": { "location": { "lead_entity_menu": { "url": "template.html", "icon": "icon.svg" } } } } }
EXPAND ↓

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

The product key is used to specify the product and location in which the app is rendered. This app is to be rendered in the lead_entity_menu location in the Lead Details page. url and icon specify the path (from the /app directory) to the template and icon files rendered in that location.

You can view the complete list of where apps can be rendered in the App Locations section.

app/icon.svg

This is the app icon specified in the manifest file. It is displayed inside the app. The app icon file is of SVG type with a resolution of 64 x 64 pixels.

app/freshsales_logo.png

This is the Freshsales logo that is displayed by the app.

app/template.html

Apps in the Freshsales UI are rendered inside an IFrame. This file contains the HTML markup for the app. It is a simple template that displays an image along with text which is dynamically generated in the app.js file.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous"> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.0/jquery.min.js"></script> <script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/async/2.6.0/async.min.js"></script> <script src="app.js"></script> <script type="text/javascript"> var client; $(document).ready(function(){ app.initialized() .then(function(_client) { client = _client; }) }) function openModal(){ client.interface.trigger("showModal", {title: "Sample Modal", template: "modal.html"}) } </script> </head> <body> <div class="container"> <div class="align-middle text-center" style="margin-top: 50px"> This is your sample app. You can utilise this space to build your app. <br/> You can add your own element here. <br/><br/> Click the below button. </div> <br/> <div class="text-center"> <button onclick="openModal();" class="btn btn-warning " style="margin-top:20px"> Open Modal </button> </div> </div> </body> </html>
EXPAND ↓

The template.html file includes the following:

  • fresh_client.js - This JS library enables the app to communicate with the parent page. The file is mandatory as the app runs in an IFrame and needs to communicate with the parent page in order to access data, listen to events, and trigger interface actions.
  • jquery - This is used by app.js.
  • app.js - Establishes connection with the parent page to retrieve information about the lead ID.
  • freshsales.css - Importing this css file ensures that the app maintains a UI that is consistent with the parent page. Anytime the parent page is redesigned, we update this stylesheet so that the app remains consistent.
  • style.css - App specific stylesheet that contains style information for various UI components of the app.

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
$(document).ready( function() { app.initialized() .then(function(_client) { var client = _client; client.events.on("app.activated", function() { //Your code here }); }); });

When the Lead page is loaded for the first time, the app.js registers for the app.initialized() method. In the callback, it receives a client object and registers for the app.activated() method.

As apps are rendered within an IFrame, the app and underlying page communicate through APIs by using the client object.

app/style.css

The app specific stylesheet contains style information for various UI components of the app. For this app, the file contains style information for the Freshsales logo which is part of the app as well as the div block that contains the image and the accompanying text.

Copied Copy
1
2
3
4
5
6
7
.logo { background: url("freshsales_logo.png"); background-repeat: no-repeat; background-size: contain; height: 25px; margin-top: 25px; }
Next Steps

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

If you run into any issues, you can reach us at support@freshsales.io.