Custom Installation Page

The custom installation page enables developers to build installation pages that contain UI elements and workflows that are unavailable on the Standard Installation page.

Sample Use Cases

  • Use interface elements such as nested fields, toggles, sliders, date and time pickers, mappers, and more on the Installation page.
  • Build dynamic forms where a value entered for one parameter determines the next parameter that is shown.
  • Perform client-side validation on the entered parameters.

To create and use a Custom Installation page, follow the given steps.

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

Note:
As part of the Custom Installation page, Request API can be used by initializing the client. For more information, see Request API.

Create

To get started, create an iparams.html file and place it in the app’s config/ directory. The Custom Installation page is sandboxed in an iFrame and so you need to include all the required HTML, CSS, and JS.

You must include fresh_client.js to enable communication between the Install page and 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/freshsales.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 a higher version of the FDK to test the Custom Installation page.

Sometimes, you might require certain product settings while installing an app. At present, you can retrieve the product's API key and Domain by using data-bind as shown in the following sample code.

1
2
<input type="text" name="api_key" data-bind="product.api_key"> <input type="text" name="domain" data-bind="product.domain">

Note: If an admin resets the API key after app installation, you need to manually update the API key in the Installation page.

PostConfigs

This method is used to store the key value pairs containing names and values of iparam fields in JSON format and also pass secure iparam keys using the meta tag. The postConfigs() method is triggered when a user clicks the INSTALL button, and it is mandatory to include this function inside 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 is invoked when the user clicks the Settings icon in the Installed Apps Listing page to edit 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 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 input values provided by users during installation, and returns true or false based on the validation. If false is returned, users will not be allowed to proceed with the installation.

The validate() method is invoked in the following scenarios:

  • When users enter iparams and click INSTALL during app installation.
  • When users edit 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

To fetch installation parameters, see the Retrieve section.

Testing

To test your app in local settings, follow these steps:

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

    Apps that contain a Custom Installation page will display the following: To test the custom installation page, visit - http://localhost:10001/custom_configs

  2. Enter values in the fields and click the Install button to test the app installaton.