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 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 entered parameters.
To create and use a Custom Installation page, follow the steps below:
- Create the template with HTML, CSS, and JavaScript (JS).
- Add a postConfigs method to store installation parameters.
- Add a getConfigs method to retrieve the installation parameters and populate the Edit Settings page.
- [Optional] Perform client-side validation on the entered parameters.
- Retrieve the stored installation parameters and use them in your apps.
Note:
As part of the Custom Installation page, the Request method can be used by initializing the client. For more information, see Request method.
Create
To create a custom installation page:
- In the config directory, 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:
- The required HTML, CSS, and JS dependencies.
- The fresh_client.js file, to enable access to certain platform features within the Installation page.
- A reference to the product style sheet, to maintain design consistency.
1. Use the latest version of FDK to test the Custom Installation page in your computer.
2. You can add external assets, such as .css and .js, in the config/assets folder to render the Custom Installation page.
Sample iparams.html
Copied Copy1 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 115 116 117 118 119 120 121 122 123 124 | <!DOCTYPE html> <html lang="en"> <head> <link rel="stylesheet" type="text/css" href="https://static.freshdev.io/fdk/2.0/assets/freshchat.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" /> <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("#company").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.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=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 contact={}; var company = []; 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(); 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 { __meta: { secure: ["api_key"] }, api_key, contact, company: company, conditions: conditions } } </script> </head> <body> <div class="contact-fields"> <h3>Contact 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>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> |
postConfigs
This method is used to store 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 Copy1 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 | <script type= "text/javascript"> function postConfigs() { var contact={}; var company = []; 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(); 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 { __meta: { secure: ["api_key"] }, api_key, contact, company: company, conditions: conditions } } </script> |
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 Copy1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | <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.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> |
validate
This method can be used to validate input values provided by users during installation. 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 Copy1 2 3 4 5 6 7 8 9 10 11 12 13 14 | <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> |
Retrieve
To fetch installation parameters, see the Retrieve section.
Testing
To test your app in local settings, follow these steps:
- Open your console, navigate to your project folder, and execute the following command: $ fdk run Apps that contain a Custom Installation page display the following: To test the custom installation page, visit - http://localhost:10001/custom_configs
- Enter values in the fields and click the Install button to test the app installation.