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

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.

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
<div class="requester-fields"> <h3 class="leftselect2">Requester fields 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"> <div id="error_div" class="error hide">Please enter a valid input</span> </div> <div class="account-fields"> <h3 class="leftselect2">Department Fields</h3> <select class="select2-fields int-select select2-offscreen" data-disable-field="Department" data-placeholder=" " id="department" multiple="multiple" name="department[]" rel="select-choice" tabindex="-1"> <option value="Department" selected="selected">Department</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> </select> </div> <br> <br> <label class="checkbox-inline"><input name="condition" type="checkbox" value="order"> Display orders from sample app</label> <br> </div> </li> </ul> <input type="text" value="given"></input> <span class="hide">Enter a valid input</span> <style> .dropdown { width: 10%; color: black; border: 5; } .select2-container { width: 50%; } .select2-locked { padding: 0px !important; } </style>
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 requester={}; var deparment = []; var conditions = []; var first_name = jQuery("input[name=first_name]").val(); var last_name = jQuery("input[name=last_name]").val(); requester["first_name"] = first_name; requester["last_name"] = last_name; jQuery("#deparment option:selected").each(function(){ deparment.push(jQuery(this).val()); }); jQuery("input[name="condition"]:checked").each(function(){ conditions.push(jQuery(this).val()); }); return { requester, deparment: deparment, 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.deparment.length; i++ ) { jQuery("#deparment option[value=" + configs.deparment[i] + "]").attr("selected",true); } jQuery("#deparment").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.