Freshworks Developer Docs | Custom installation page

A custom installation page contains certain UI elements and workflows that are unavailable in a standard installation page. For example, a custom installation page can:

Contain elements such as nested fields, toggles, sliders, date and time pickers, mappers, and so on.
Make installation forms dynamic; the value of a parameter determines the other parameters to be displayed.
Help perform client-side validation of the installation parameter values entered.

For a demonstration of how custom installation pages are used, see the Custom Installation Page sample app.

To create and use a Custom Installation page:

Create the iparams.html file, specifying all required HTML, CSS, and JavaScript (JS) information.
In the iparams.html file, add the postConfigs method to retrieve the iparams as form fields with values and store them.
In the iparams.html file, add the getConfigs method to retrieve the stored iparams’ values alone and populate the Edit Settings page.
To perform client-side validation of the iparams entered, in the iparams.html file, add the validate method.
Retrieve the stored iparams and use them in apps.

Note:To handle the secure iparam values entered in the Custom Installation page, the Request method is used. In SMI, when a serverless component is invoked, the iparams defined in a custom installation page are passed as a JSON payload.

Create custom iparams

Navigate to the config directory and create an iparams.html file. Note:Ensure that the config directory contains only one of the two files - iparams.json or iparams.html.
In the iparams.html file, include:
1. The required HTML, CSS, and JS dependencies.
2. The appclient through <script src="{{{appclient}}}"></script> if you are building apps by using FDK version 9.0.0 or later with platform version 2.3.
3. A reference to the product style sheet, to maintain design consistency.
To retrieve product account specific information such as the domain name and api key associated with an account, in iparams.html, use a text type input element with the data-bind attribute.
```
<input type="text" name="api_key" data-bind="product.api_key">
<input type="text" name="domain" data-bind="product.domain">
```

Note:You can add external assets, such as .css and .js, in the config/assets folder to render the Custom Installation page.

Sample iparams.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" type="text/css" href="https://static.freshdev.io/fdk/2.0/assets/freshworks_crm.css">
    <script src="{{{appclient}}}"></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" />
    <link rel="stylesheet" type="text/css" href="./assets/iparams.css">
    <script src="./assets/iparams.js"></script>
    <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("#department").select2({
        width: "resolve"
      });
    </script>
    <script type= "text/javascript">
      function getConfigs(configs) {
        jQuery("#error_div").hide();
        jQuery("input[name=api_key]").val(configs["api_key"]);
        jQuery("input[name=first_name]").val(configs.requester["first_name"]);
        jQuery("input[name=last_name]").val(configs.requester["last_name"]);
        for(var i= 0; i < configs.department.length; i++ ) {
          jQuery("#department option[value=" + configs.department[i] + "]").attr("selected",true);
         }
         jQuery("#department").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=api_key]").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 requester = {};
        var department = [];
        var conditions = [];
        var api_key = jQuery("input[name=api_key]").val();
        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("#department option:selected").each(function(){
          company.push(jQuery(this).val());
        });
        jQuery("input[name=\"condition\"]:checked").each(function(){
        conditions.push(jQuery(this).val());
        });
        return {
          __meta: {
            secure: ["api_key"]
          },
          api_key,
          requester,
          department: company,
          conditions: conditions
        }
      }
    </script>
  </head>
  <body>
    <div class="requester-fields">
      <h3>Requester Fields</h3>
        <label for="api_key">API key</label>
        <input type="text" name="api_key">
        <span id="error_div" class="error" style="display: none;">Please enter a valid input. Please enter only alphabets.</span>
        <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>
    <div class="account-fields">
      <h3>Department Fields</h3>
      <select class="select2-fields int-select select2-offscreen" data-disable-field="Department" data-placeholder=" " id="department" multiple="multiple" name="company[]" rel="select-choice" tabindex="-1">
        <option value="Department">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>
        <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>

Use postConfigs method

To store the installation parameter values entered in the installation page, include this method in the iparams.html file. The method is triggered when, on the installation page, Install is clicked. The method stores the iparams and corresponding values entered in the installation page, as JSON key-value pairs. Secure iparam values are passed using the meta tag in this method.

Sample iparams.html

<script type= "text/javascript">
 function postConfigs() {
   var requester={};
   var department = [];
   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("#department option:selected").each(function(){
     department.push(jQuery(this).val());
   });
   jQuery("input[name="condition"]:checked").each(function(){
   conditions.push(jQuery(this).val());
   });
   return {
     requester,
     department: department,
     conditions: conditions
   }
 }
</script>

Use getConfigs method

To retrieve the stored iparams’ values and populate them on the Edit Settings page, include this method in the iparams.html file. The method is triggered when you click the Settings icon on the Installed Apps Listing page.

Sample iparams.html

<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.department.length; i++ ) {
   jQuery("#department option[value=" + configs.department[i] + "]").attr("selected",true);
  }
  jQuery("#department").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>

Use validate method

To validate the values entered on the installation page or the Edit settings page, include this method in the iparams.html file. The method is triggered when:

During installation, users enter iparam values and click Install on the Installation page.
After installation, users edit iparam values and click Save on the Edit Settings page.

If the method returns false, the installation is stopped or the iparam values are not saved.

Sample iparams.html

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;
}

Retrieve

For information on how to retrieve the configured iparams and to use them in the app components, see the Retrieve iparams section.

Test iparams

To test the configured installation parameters:

From the command prompt, navigate to the app project folder, and run the following command:
```
fdk run
```
If the app contains an Installation page, the following message is displayed:
```
To test the installation page, visit - http://localhost:10001/custom_configs
```
Navigate to the specified location. The Installation page is displayed.
Enter appropriate values in the fields and click INSTALL.

Tutorials

Sample apps

Guides

Blogs

Assist catalog

Events

Custom installation page

Create custom iparams

Use postConfigs method

Use getConfigs method

Use validate method

Retrieve

Test iparams

Tutorials

Sample apps

Guides

Blogs

Assist catalog

Events

Custom installation pageOn this page

Create custom iparams

Use postConfigs method

Use getConfigs method

Use validate method

Retrieve

Test iparams

Custom installation page