Extensions Dialog PropertyEditor

The Dialog Property Editor allows to create a flexible dialog that allows the user to enter data.
The structure and content of the Dialog is defined with a JSon.

It is useful for extensions settings and in particulary in the  settingsDialog() function.

createPropertyEditor(title, params, [dialogId])

Create a dialog to set given params. To display the dialog use the method exec(). To get the modified parameters use the method getParams(). The structure of params is described in the openPropertyEditor paragraph.

Public slots:

• void addCustomCommand(functionName, commandLabel)
  //allows to call a function of the script from a command in the dialog
• void addImportCommand()
  //allows to import the extension's settings from other files
• QJSValue getParams()
  //returns the params of the dialog
• void setParams(QSJValue params)
  //allows to set the params of the dialog

function exec(inData, options) {
    let params = {};
    params.version = '1.0';
    params.data = [];
    let editor = Banana.Ui.createPropertyEditor('Dialog Title', params, 'pageAnchor');
    let param = {};
    param.name = 'header';
    param.title = 'header';
    param.type = 'string';
    param.value = 'this is an example of header';
    param.defaultvalue = 'my header';
    param.readValue = function () {
        param.header = this.value;
    }
    params.data.push(param);
    editor.setParams(params);
    editor.addImportCommand();
    editor.addCustomCommand("functionName1", "label pushbutton 1");
    editor.addCustomCommand("functionName2", "label pushbutton 2");
    let rtnValue = editor.exec();
    if (parseInt(rtnValue) === 1) {
        // Read data from dialog
        params = editor.getParams();
        Banana.console.debug(JSON.stringify(params));
    }
}
function functionName1(params) {
    Banana.console.debug("called functionName1");
    Banana.console.debug(JSON.stringify(params));
    for (var i = 0; i < params.data.length; i++) {
        if (params.data[i].name === 'header') {
            params.data[i].value = 'hello world';
        }
    }
    return params;
}
function functionName2(params) {
    Banana.console.debug("called functionName2");
    Banana.console.debug(JSON.stringify(params));
    return params;
}

openPropertyEditor(title, params, [dialogId])

Show the user a dialog asking to set given params.

Return the modified params or undefined if the user clicked cancel.
See Invoice Extension containing examples with this method.

Params is an object containing:

• version
  A string with a version number. Required '1.0';
• data
  An array containing the elements of the property editors.

Element properties of the array

• name: param's key (unique id)
• title: param's title, which appears in the left column "property"
• parentObject (optional):
  • Should be the name (id) of the parent's element.
  • It let you define a tree structure, as the following one:

see the structure example on GitHub

• type (optional):
  • string (default)
    A single line of text
  • multilinestring
    A text area with multiple lines
  • bool 
    checkbox for setting true/false value
  • date
    calendar popup for date selection
  • combobox
    Use the property items for setting a list of values
  • color
    Color dialog box for color selection
  • font
    Combobox that lets the user select a font family
     
• value: the value, which appears in the right column "value". For type bool: true/false, for type string and multilinestring a text. For type combox the selected text.
• defaultvalue (optional): value used by Restore Defaults button. If the param has this property the button Restore Defaults will be available.
• items:  array of strings. Used by type combobox.
• collapse (optional): true/false. By default the dialog expand all items. If collapse is true the item will not be expanded.
• enabled (optional): true/false. If false the value will appears grey and the user cannot change the value (default: true)
• editable (optional): true/false. If false the user cannot change the value, available only for string and multilinestring types (default: true)
• tooltip (optional): text which appears over the item without clicking on the item
• errorId (optional): error id that identify an error. The error id is used to link the error to the corresponding help page
• errorMsg (optional): error string that describe an error. If a parameter has this property set, the label will be show in red and the error showed on the right of the name.

Validating data

Before accepting data you can validate them using the method validateParams(). If this method returns false the dialog will prevent to close.

function validateParams(params) {
   for (var i = 0; i <  params.data.length; i++) {
       if (params.data[i].value != "myValue") {
          params.data[i].errorMsg = "this object is not valid";
          return false;
       }
   }
   return true;
}

Example code openPropertyEditor

var paramList = {};
paramList.version = '1.0';
paramList.data = [];
// bool
var param = {};
param.name = 'print_header';
param.title = 'print header';
param.type = 'bool';
param.value = true;
param.readValue = function() {
  param.print_header = this.value;
}
paramList.data.push(param);
// combobox
var param = {};
param.name = 'methodId';
param.title = 'Method ID';
param.type = 'combobox';
param.value = 'item01';
param.items = ['item01', 'item02', 'item03'];
param.readValue = function () {
  param.methodId= this.value;
}
paramList.data.push(param);
var dialogTitle = 'Settings';
var pageAnchor = 'dlgSettings';
if (Banana.Ui.openPropertyEditor(dialogTitle, paramList, pageAnchor))) {
   for (var i = 0; i < paramList.data.length; i++) {
      // Read values to param (through the readValue function)
      paramList.data[i].readValue();
   }