Custom Installation Page

The custom installation page enables developers to build installation pages that contain UI elements and workflows that are unavailable in the standard installation page.

Sample use cases

  • Use interface elements such as nested fields, toggles, sliders, date and time pickers, mappers etc., in the installation page.
  • Build dynamic forms where a value entered for one parameter determines the next parameter that is shown.
  • Perform client side validation of the entered parameters
Take a look at the Custom Installation Page sample app and the Asana sample app for a demonstration of this feature.

Use the steps below to create and use a custom installation page:

  1. Create the template with HTML, CSS, and JS.
  2. Add a postConfigs method to store the installation parameters.
  3. Add a getConfigs method to retrieve the installation parameters and populate the edit settings page.
  4. [Optional] Perform client side validation of the entered parameters.
  5. Retrieve the stored installation parameters and use them in your apps.
Create

To get started, create an iparams.html file and place it within the app’s config/ directory. The custom installation page is sandboxed in an iFrame and hence you must include all the required HTML, CSS and JavaScript.

You must include our fresh_client.js to enable communication between your install page and the parent page, through the sandbox. To maintain design consistency, include a reference to the product style sheet. You can read about our UI guidelines here.

template.html
Copied Copy
1
2
<script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js"></script> <link rel="stylesheet" type="text/css" href="https://static.freshdev.io/fdk/2.0/assets/freshdesk.css">

Sample iparams.html

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
<!DOCTYPE html> <html lang="en"> <head> <link rel="stylesheet" type="text/css" href="https://static.freshdev.io/fdk/2.0/assets/freshdesk.css"> <script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js"></script> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.0/jquery.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/select2/4.0.6-rc.0/js/select2.min.js"></script> <link href="https://cdnjs.cloudflare.com/ajax/libs/select2/4.0.6-rc.0/css/select2.min.css" rel="stylesheet" /> <style> .dropdown { width: 10%; color: black; border: 5; } #error_div { color: red; } .select2-container { width: 70%; } .select2-container--default { width: 80% !important; } .select2-locked { padding: 0px !important; } </style> <script type= "text/javascript"> jQuery("#error_div").hide(); jQuery("#company").select2({ width: 'resolve' }); </script> <script type= "text/javascript"> function getConfigs(configs) { jQuery("#error_div").hide(); jQuery("input[name=first_name]").val(configs.contact["first_name"]); jQuery("input[name=last_name]").val(configs.contact["last_name"]); for(var i= 0; i < configs.company.length; i++ ) { jQuery("#company option[value=" + configs.company[i] + "]").attr("selected",true); } jQuery("#company").select2({ width: 'resolve' }); if(configs.conditions) { jQuery("input[name='condition']").attr("checked",false); for(var a= 0; a < configs.conditions.length; a++ ) { jQuery("input[name='condition'][value="+ configs.conditions[a]+"]").attr("checked",true); } } } </script> <script type= "text/javascript"> function validate() { let isValid = true; var input = jQuery("input[name=last_name]").val(); if(!input.match(/^[A-z]+$/)) { jQuery("#error_div").show(); isValid = false; } else { jQuery("#error_div").hide(); } return isValid; } </script> <script type= "text/javascript"> function postConfigs() { var contact={}; var company = []; var conditions = []; var first_name = jQuery("input[name=first_name]").val(); var last_name = jQuery("input[name=last_name]").val(); contact["first_name"] = first_name; contact["last_name"] = last_name; jQuery("#company option:selected").each(function(){ company.push(jQuery(this).val()); }); jQuery("input[name='condition']:checked").each(function(){ conditions.push(jQuery(this).val()); }); return { contact, company: company, conditions: conditions } } </script> </head> <body> <div class="contact-fields"> <h3>Contact Fields</h3> <label for="first_name">First Name</label> <input type="text" name="first_name"> <label for="last_name">Last Name</label> <input type="text" name="last_name"> <span id="error_div" class="error" style="display: none;">Please enter a valid input. Please enter only alphabets.</span> </div> <div class="account-fields"> <h3>Company Fields</h3> <select class="select2-fields int-select select2-offscreen" data-disable-field="Company" data-placeholder=" " id="company" multiple="multiple" name="company[]" rel="select-choice" tabindex="-1"> <option value="Company">Company</option> <option value="City">City</option> <option value="Country">Country</option> <option value="Email">Email</option> <option value="Phone">Phone</option> <option value="PostalCode">Postal Code</option> <option value="State">State</option> </select> </div> <label class="checkbox-inline"><input name="condition" type="checkbox" value="order"> Display orders from sample app</label> <label class="checkbox-inline"><input name="condition" type="checkbox" value="type"> Display type from sample app</label> </body> </html>
EXPAND ↓

Note:
1. You should either have iparams.json or iparams.html not both.
2. Use v4.2.1 or higher of the FDK to local test the custom installation page.

postConfigs

This method is used to store the key value pairs containing the names and values of iparam fields in JSON format. The postConfigs() method will be triggered when the user clicks the INSTALL button. It is mandatory to include this function inside the iparams.html.

iparams.html

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<script type= "text/javascript"> function postConfigs() { var contact={}; var company = []; var conditions = []; var first_name = jQuery("input[name=first_name]").val(); var last_name = jQuery("input[name=last_name]").val(); contact["first_name"] = first_name; contact["last_name"] = last_name; jQuery("#company option:selected").each(function(){ company.push(jQuery(this).val()); }); jQuery("input[name="condition"]:checked").each(function(){ conditions.push(jQuery(this).val()); }); return { contact, company: company, conditions: conditions } } </script>
EXPAND ↓
getConfigs

This method will be invoked when the user clicks the settings icon in the installed apps listing page for editing the installation parameters. The getConfigs() method is used to retrieve the existing installation parameters and populate them in the edit settings page. It is mandatory to include this function inside the iparams.html.

iparams.html

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<script type= "text/javascript"> function getConfigs(configs) { jQuery("input[name=first_name]").val(configs["first_name"]); jQuery("input[name=last_name]").val(configs["last_name"]); for(var i= 0; i < configs.company.length; i++ ) { jQuery("#company option[value=" + configs.company[i] + "]").attr("selected",true); } jQuery("#company").select2(); if(configs.conditions) { jQuery("input[name="condition"]").attr("checked",false); for(var a= 0; a < configs.conditions.length; a++ ) { jQuery("input[name="condition"][value="+ configs.conditions[a]+"]").attr("checked",true); } } } </script>
EXPAND ↓
validate

This method can be used to validate the input values provided by the users during installation. The validate() method returns true or false based on the validation, if false is returned, users will not be allowed to proceed with the installation.

validate() method will be called in the following scenarios:

  • When the users enter the iparams and click INSTALL during app installation.
  • When the users edit the iparams and click SAVE after app installation.

iparams.html

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
function validate() { let isValid = true; var input = jQuery("input[name=last_name]").val(); if(!input.match(/^[A-z]+$/)) { jQuery("#error_div").show(); isValid = false; } else { jQuery("#error_div").hide(); } return isValid; }
EXPAND ↓
Retrieve

You can retrieve the installation parameters using the format below:

app.js

Copied Copy
1
2
3
4
5
6
7
8
9
10
client.iparams.get().then ( function(data) { // success output // "data" is returned with the list of all the iparams }, function(error) { console.log(error); // failure operation } );

Local Testing

Open your console, navigate to your project folder, and execute the following command: $ fdk run

Apps that contain a custom installation page will output the following URL. To test the custom installation page, visit - http://localhost:10001/custom_configs You can now test out the app installation experience. Once you have filled in the fields, you can press the “Install” button to test the app using the entered values.

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.