WIZARD_UIFILES

install_uifile, upgrade_uifile, and uninstall_uifile are files which describe UI components in JSON format. They are stored in the “WIZARD_UIFILES” folder. During the installation, upgrading, and un-installation processes, these UI components will appear in the wizard. Once these components are selected, their keys will be set in the script environment variables with true, false, or text values.

These files can be regarded as user settings or used to control the flow of script execution.

  • install_uifile: Describes UI components for the installation process. During the process of the preinst and postinst scripts, these component keys and values can be found in the environment variables.
  • upgrade_uifile: Describes UI components for the upgrade process. During the process of the preupgrade, postupgrade, preuninst, postuninst, preinst and postinst scripts, these component keys and values can be found in the environment variables.
  • uninstall_uifile: Describes UI components for the un-installation process. During the process of the preuninst and postuninst scripts, these component keys and values can be found in the environment variables.

If you would like to run a script to generate the wizard dynamically, you can add install_uifile.sh, upgrade_uifile.sh and uninstall_uifile.sh files, they are run before installing, upgrading, and uninstalling a package respectively to generate UI components in JSON format and write to SYNOPKG_TEMP_LOGFILE. Script environment variables in these scripts can be gotten in these scripts. Please refer to "Script Environment Variables" for more information.

If you would like to localize the descriptions of UI components, you can add a language abbreviation suffix to the file “install_uifile_[DSM language],” “upgrade_uifile_[DSM language]”, “uninstall_uifile_[DSM language]”, “install_uifile_[DSM language].sh,” “upgrade_uifile_[DSM language].sh” or “uninstall_uifile_[DSM language].sh” in this folder. For example, in order to perform installation in Traditional Chinese, [DSM language] should be replaced with “cht” as follows: “install_uifile_cht”.

Example of the file in JSON format:

[{
    "step_title": "Step1",
    "items": [{
        "type": "singleselect",
        "desc": "a radio group",
        "subitems": [{
            "key": "radio1",
            "desc": "Radio button 1",
            "defaultVaule": false
        }, {
            "key": "radio2",
            "desc": "Radio button 2",
            "defaultVaule": true
        }]
    }]
}, {
    "step_title": "Step2",
    "items": [{
        "type": "multiselect",
        "desc": "a check group",
        "subitems": [{
            "key": "check1",
            "desc": "Check button 1"
        }, {
            "key": "check2",
            "desc": "Check button 2",
            "defaultVaule": true,
            "validator": {
                "fn": "{var v=arguments[0]; if (!v) return 'Check this';return true;}"
             }
        }]
    }, {
        "type": "textfield",
        "desc": "textfield",
        "subitems": [{
            "key": "textfield1",
            "desc": "textfield 1",
            "defaultVaule": "default",
            "validator": {
                "allowBlank": false,
                "minLength": 2,
                "maxLength": 10
            }
        },{
            "key": "textfield2",
            "desc": "textfield 2",
            "emptyText": "abc1@cde.com",
            "validator": {
                "vtype": "email",
                "regex": {
                    "expr": "/[0-9]/i",
                    "errorText": "Error"
                }
            }
        }]
    }]
}, {
    "step_title" : "Step 3",
    "invalid_next_disabled": true,
    "activeate": "{console.log('activeate', arguments);}",
    "deactivate": "{console.log('deactivate', arguments);}",
    "items" : [{
        "type" : "singleselect",
        "desc" : "Check it",
        "subitems": [{
                "key": "id1",
                "desc": "Not choose it",
                "defaultValue": true
            },
            {
                "key": "id2",
                "desc": "Choose it",
                "defaultValue": false,
                "validator": {
                    "fn": "{return arguments[0];}"
                }
            }]
        }]
}]

Example of using a script to generate a file in JSON format:

#!/bin/sh

/bin/cat > /tmp/wizard.php <<'EOF'
<?php
$ini_array = parse_ini_file("/etc.defaults/synoinfo.conf");
$unique=$ini_array["unique"];
echo  <<<EOF
[{
    "step_title": "Step 1",
    "items": [{
        "type": "textfield",
        "desc": "model name",
        "subitems": [{
            "key": "pkgwizard_db_name",
            "desc": "name",
            "defaultValue":"$unique"
        }]
    }, {
        "type": "combobox",
        "desc": "Please select a volume",
        "subitems": [{
            "key": "volume",
            "desc": "volume name",
            "displayField": "display_name",
            "valueField": "volume_path",
            "editable": false,
            "mode": "remote",
            "api_store": {
                "api": "SYNO.Core.Storage.Volume",
                "method": "list",
                "version": 1,
                "baseParams": {
                    "limit": -1,
                    "offset": 0,
                    "location": "internal"
                },
                "root": "volumes",
                "idProperty": "volume_path",
                "fields": ["display_name", "volume_path"]
            },
            "validator": {
                "fn": "{console.log(arguments);return true;}"
            }
        }]
    }]
}];
EOF;
?>
EOF

/usr/bin/php -n /tmp/wizard.php > $SYNOPKG_TEMP_LOGFILE
rm /tmp/wizard.php
exit 0
  • Here are the properties for each step in the wizard in JSON format:
Property Description DSM Requirement
step_title Optional. Describes the title of the current step performed in the wizard. 3.2-1922
items Describes an array containing the components of “singleselect”, “multiselect”, “textfield”, “password”, or “combobox” type. 3.2-1922
type Must be “singleselect”, “multiselect”, “textfield” “password” or “combobox”.
singleselect” type represents the components in the sub-items which are all radio buttons. You can select only one radio box with a unique key.
multiselect” type represents the components in the sub-items which are all checkboxes. You can check more than one checkbox.
textfield” type represents the components in the sub-items which are all text fields. You can type text.
password” type represents the components in the sub-items which are all password fields. You can type passwords.
combobox” type represents the components in the sub-items which are all combobox fields. The user can choose a item in the combobox field.
Note: “combobox” type is only available in DSM 5.2 or newer.
3.2-1922
desc Optional. Describe a component in the label text. 3.2-1922
subitems Describe an array containing radio buttons, checkboxes, text fields, or password components. 3.2-1922
activeate JSON-style string to describe a function which is run after the step of the wizard has been visually activated. 5.2
deactivate JSON-style string to describe a function which is run after the step of the wizard has been visually deactivated. 5.2
invalid_next_disabled If set to true, the next button in the step of the wizard will be disabled by default. It will be enabled if all items are validated scucuessfully by validator in this step. 5.2
  • Here are the properties for components in subitems in JSON format:
Property Description DSM Requirement
key A unique component key value represents a UI component. If you select a component, this key will be set in the script environment variables of preinst, postinst, preupgrade, postupgrade, preuninst, postuninst, start-stop-status (the string value of the selected checkbox or radio button is always “true”.). 3.2-1922
defaultVaule Optional. true/false value to initialize “singleselect” or “multiselect” component, or a string value to initialize “textfield” or “password” component. 4.2-3160
emptyText Optional. The prompt text to place into an empty “textfield” or “password” component to prompt the user how to fill in if defaultVaule is not set. 4.2-3160
validator JSON-style object to describe validation functions. If the validation fails with the user's value, the user cannot go to the next step of the wizard. More detailed properties of validator are given in the validator table. 4.2-3160
disabled true to disable the field (defaults to false). 6.0
height The height of this component in pixels. 6.0
hidden true to hide this component. 6.0
invalidText The error text to use when marking a field invalid and no message is provided. 6.0
preventMark true to disable marking the field invalid. Defaults to false. 6.0
width The width of this component in pixels. 6.0
  • Here are the properties of validator:
Property Description Value
allowBlank Specify false to validate that the value's length of “textfield” or “password” component is > 0 true/false
minLength Minimum length of “textfield” or “password” component Number
maxLength Maximum length of “textfield” or “password” component Number
vtype Specify pre-defined validation function,
"alpha": validate alpha value
"alphanum": validate alphanumeric value
"email": validate email address
"url": validate URL
"alpha", "alphanum", "email", "url"
regex Describe validation function in regular expression and invalid message. Properties contain:
"expr": Javascript Regular Expression
"errorText": invalid string
JSON-style object
fn Describe the Javascript function which is encoded by JSON-style string with curly brackets. In this function, you can use arguments[0] to get the value of the component. In addition, this function will return true if the value is valid or as an invalid string if the value is invalid. String
  • Here are the other properties for textfield, password or combobox component in subitems in JSON format:
Property Description DSM Requirement
blankText The error text to display if the allowBlank validation fails 6.0
grow true if this field should automatically grow and shrink to its content 6.0
growMax The maximum height to allow when grow is true 6.0
growMin The minimum height to allow when grow is true 6.0
htmlEncode false to skip HTML-encoding the text when rendering it (defaults to false). 6.0
maxLengthText Error text to display if the maximum length validation using maxLength fails. 6.0
minLengthText Error text to display if the minimum length validation using minLength fails. 6.0
  • Here are the properties for combobox component in subitems in JSON format:
Property Description DSM Requirement
api_store JSON-style object to describe to send a WebAPI request and store the response in the data strusture for combobox use. More detailed properties of api_store are given in the store table.
Example:
{
   "api": "SYNO.Core.XXX",
   "method": "list",
   "version": 1,
    "baseParams": {
      "offset": 0,
      "limit":-1,
   },
   "root": "items",
   "idProperty":"name",
   "fields": ["name"]
}
6.0
autoSelect true to select the first result gathered by the data store (defaults to true). A false value would require a manual selection from the dropdown list to set the components value. 6.0
displayField The underlying data field name to bind to this combobox. 6.0
editable false to prevent the user from typing text directly into the field, the field will only respond to a click on the trigger to set the value. (defaults to true). 6.0
forceSelection true to restrict the selected value to one of the values in the list, false to allow the user to set arbitrary text into the field (defaults to false). 6.0
handleHeight The height in pixels of the dropdown list resize handle if resizable is true. 6.0
listAlign A valid anchor position value. 6.0
listEmptyText The empty text to display in the data view if no items are found. 6.0
listWidth The width of the dropdown list. 6.0
maxHeight The maximum height in pixels of the dropdown list before scrollbars are shown. 6.0
minChars The minimum number of characters the user must type before autocomplete and typeAhead activate 6.0
minHeight The minimum height in pixels of the dropdown list when the list is constrained by its distance to the viewport edges. 6.0
minListWidth The minimum width of the dropdown list in pixels. 6.0
mode Set to 'loacl' to load local store to load local JSON-array data. More detailed properties of local store are given in the store table.
Example:
{
   "mode": "local",
   "valueField": "myId",
   "displayField": "displayText",
   "store": {
      "xtype": "arraystore",
      "fields": ["myId", "displayText"],
      "data": [[1, "item1"], [2, "item2"]]
   }
}
6.0
pageSize If greater than 0, a paging toolbar is displayed in the footer of the dropdown list and the filter queries will execute with page start and limit parameters. Only applies when using api_store (defaults to 0). 6.0
queryDelay The length of time in milliseconds to delay between the start of typing and sending the query to filter the dropdown list. 6.0
resizable true to add a resize handle to the bottom of the dropdown list (Defaults to false). 6.0
selectOnFocus true to select any existing text in the field immediately on focus. Only applies when editable is true (defaults to false). 6.0
store A data structure to store data in combobox (defaults to undefined). It can't be used with api_store at the same time. Acceptable values for this property are:
1-dimensional array : e.g., ["Foo","Bar"]
2-dimensional array : For a 2-dimensional array, the value in index 0 of each item will be assumed to be the valueField, while the value at index 1 is assumed to be the displayField, e.g., [["f","Foo"],["b","Bar"]].
6.0
title If supplied, a header element is created containing this text and added into the top of the dropdown list 6.0
typeAhead true to populate and autoselect the remainder of the text being typed after a configurable delay (typeAheadDelay). 6.0
typeAheadDelay The length of time in milliseconds to wait until the typeahead text is displayed. 6.0
valueField The underlying data value name to bind to this combobox. 6.0
  • Here are the properties for api_store or store data structure in JSON format:
Property Description DSM Requirement
baseParams An object containing properties which are to be sent as parameters for every WebAPI request in api_store. 6.0
data An inline data object readable by the reader in local store to load local JSON-array data. 6.0
displayField The underlying data field name to bind to this combobox. 6.0
fields defined fields for the data stored in this store or api_store. 6.0
idProperty Identity of the property within data that contains a unique value. 6.0
root The name of the property which contains the array of data. Defaults to undefined. 6.0
valueField The underlying data value name to bind to this combobox. 6.0
xtype Only support arraystore type for local store to load local JSON-array data. 6.0

Note:

  1. All words are case sensitive.
  2. In DSM 4.0 or above, if both the type and subitems properties are empty, text in the desc property will be displayed as one of the steps of wizard.
  3. install_uifile.sh, upgrade_uifile.sh ,uninstall_uifile.sh and *.sh scripts to gernate the wizard dynamically are only supported in DSM 5.2 or newer.