diff --git a/docs/creating-manifest/visual-settings.md b/docs/creating-manifest/visual-settings.md index 5a688f9f..2bc79c2f 100644 --- a/docs/creating-manifest/visual-settings.md +++ b/docs/creating-manifest/visual-settings.md @@ -2918,6 +2918,253 @@ Here, the *main settings* form appears during installation process. ![settingCustom](/img/SettingsCustom.jpg) +## onBeforeInit settings + +**onBeforeInit** can be applied to all settings including the *main settings*. Similar to the [onBeforeInit](https://docs.cloudscripting.com/creating-manifest/events/#onbeforeinit) event, the field value must be a Javascript string or a URL that Javascript returns (URL can be either absolute or relative to [baseUrl](https://docs.cloudscripting.com/creating-manifest/basic-configs/#relative-links)). Inside the Javascript code, global variables are initialized: [jps](https://docs.cloudscripting.com/creating-manifest/events/#accessing-jps-manifest-fields-with-jps-variable) and [settings](https://docs.cloudscripting.com/creating-manifest/visual-settings/#visual-settings). The *jps* variable, like *onBeforeInit* event, allows you to access all the fields of the current manifest. The *settings* variable allows you to access the fields within the context where *onBeforeInit* is specified. The Javascript code should return an object in the format *{* ***result***: *0*, ***settings***: *{...}}*, and the part of the manifest where the context where *onBeforeInit* is specified, will be replaced with the settings value that was returned from *onBeforeInit*. You can use a shorthand and replace the fields inside the *settings* variable and return the same variable *(* ***return*** *settings; )*. + +The *onBeforeInit* event for *main settings* triggers in two cases: + + - when requesting the *GetAppInfo* method (requested before opening the JPS installation dialog) + - when requesting the *GetAppSettings* method (requested when clicking the addon buttons before opening the form) + +For all *settings* other than *main*, the *onBeforeInit* is triggered only when *GetAppSettings* is requested. + +There will be an object received at the output of *onBeforeInit* without the *onBeforeInit* field itself within the response for the methods *GetAppInfo* and *GetAppSettings*. + +The difference from the main *onBeforeInit* event is that when the **Install** method is called, no *onBeforeInit* is triggered for *settings*. + +If the main *onBeforeInit* is described within the global scope of the manifest and *onBeforeInit* in the *main settings*, then when *GetAppInfo* is requested, the main *onBeforeInit* is triggered first, and *onBeforeInit* for *main settings* triggers after that. + +The GetAppSettings method signature: +``` +api.marketplace.jps.GetAppSettings(appUniqueName, [settingsId], [lang]) +``` + +where: + +- `appUniqueName` - install addon's ID +- `settingsId` - settings ID. The default one is *main* +- `lang` - language ID, used when retrieving content with localization (default value is **en**) + +Manifest example with *main settings* only: + +@@@ +```yaml +type: update +name: onBeforeInit settings + +targetNodes: any + +settings: + fields: + - type: string + caption: Field 1 + name: field1 + + onBeforeInit: | + settings.fields.push({ + type: "string", + caption: "Field 2", + name: "field2" + }); + return settings; + +buttons: + - caption: Test + action: apply + settings: main + + +actions: + apply: + log: ${settings.field2} +``` +```json + { + "type": "update", + "name": "onBeforeInit settings", + "targetNodes": "any", + "settings": { + "fields": [ + { + "type": "string", + "caption": "Field 1", + "name": "field1" + } + ], + "onBeforeInit": "settings.fields.push({\n type: \"string\",\n caption: \"Field 2\",\n name: \"field2\"\n}); \nreturn settings;\n" + }, + "buttons": [ + { + "caption": "Test", + "action": "apply", + "settings": "main" + } + ], + "actions": { + "apply": { + "log": "${settings.field2}" + } + } +} +``` +@@! + +A dialog with two fields appears before manifest installation, where the **Field 2** is added via *onBeforeInit*. + +![onBeforeInit-settings](/img/onBeforeInit-settings.png) + +Manifest example with several *settings*: + +@@@ +```yaml +type: update +name: onBeforeInit settings +targetNodes: any + +settings: + main: + fields: + - type: string + caption: Field 1 + name: field1 + onBeforeInit: | + settings.fields.push({ + type: "string", + caption: "Field 2", + name: "field2" + }); + return settings; + + settings2: + fields: + - type: string + caption: Field 3 + name: field3 + onBeforeInit: | + settings.fields.push({ + type: "string", + caption: "Field 4", + name: "field4" + }); + return settings; + + settings3: + fields: + - type: string + caption: Field 5 + name: field5 + +buttons: + - caption: Action 1 + action: action1 + settings: main + + - caption: Action 2 + action: action2 + settings: settings2 + + - caption: Action 3 + action: action3 + settings: settings3 + +actions: + action1: + log: ${settings.field2} + + action2: + log: ${settings.field4} + + action3: + log: ${settings.field5} +``` +```json +{ + "type": "update", + "name": "onBeforeInit settings", + "targetNodes": "any", + "settings": { + "main": { + "fields": [ + { + "type": "string", + "caption": "Field 1", + "name": "field1" + } + ], + "onBeforeInit": "settings.fields.push({\n type: \"string\",\n caption: \"Field 2\",\n name: \"field2\"\n}); \nreturn settings; \n" + }, + "settings2": { + "fields": [ + { + "type": "string", + "caption": "Field 3", + "name": "field3" + } + ], + "onBeforeInit": "settings.fields.push({\n type: \"string\",\n caption: \"Field 4\",\n name: \"field4\"\n}); \nreturn settings; \n" + }, + "settings3": { + "fields": [ + { + "type": "string", + "caption": "Field 5", + "name": "field5" + } + ] + } + }, + "buttons": [ + { + "caption": "Action 1", + "action": "action1", + "settings": "main" + }, + { + "caption": "Action 2", + "action": "action2", + "settings": "settings2" + }, + { + "caption": "Action 3", + "action": "action3", + "settings": "settings3" + } + ], + "actions": { + "action1": { + "log": "${settings.field2}" + }, + "action2": { + "log": "${settings.field4}" + }, + "action3": { + "log": "${settings.field5}" + } + } +} +``` +@@! + +The addon installation results in three buttons available in the UI: + +![onBeforeInit-3-buttons-addon](/img/onBeforeInit-3-buttons-addon.png) + +When the buttons **Action 1** and **Action 2** are clicked, the *GetAppSettings* method is called and the **Retrieving data...** text is displayed before rendering the form: + +![onBeforeInit-retrieving-data](/img/onBeforeInit-retrieving-data.png) + +The rendered form comprises two fields, where the **Field 2** is added dynamically via *onBeforeInit*: + +![onBeforeInit-2field-rendered-form](/img/onBeforeInit-2field-rendered-form.png) + +In case of button **Action 3** is clicked the form is rendered immediately, since the *settings3* doesn't comprise *onBeforeInit*: + +![onBeforeInit-action3-rendered-form](/img/onBeforeInit-action3-rendered-form.png) + + + + ## Success Text Customization It is possible to customize the *success* text that is displayed upon successful installation either at the Dashboard, or via email notification. diff --git a/theme/readthedocs/img/onBeforeInit-2field-rendered-form.png b/theme/readthedocs/img/onBeforeInit-2field-rendered-form.png new file mode 100644 index 00000000..6782a171 Binary files /dev/null and b/theme/readthedocs/img/onBeforeInit-2field-rendered-form.png differ diff --git a/theme/readthedocs/img/onBeforeInit-3-buttons-addon.png b/theme/readthedocs/img/onBeforeInit-3-buttons-addon.png new file mode 100644 index 00000000..2347edb7 Binary files /dev/null and b/theme/readthedocs/img/onBeforeInit-3-buttons-addon.png differ diff --git a/theme/readthedocs/img/onBeforeInit-action3-rendered-form.png b/theme/readthedocs/img/onBeforeInit-action3-rendered-form.png new file mode 100644 index 00000000..dd5f8999 Binary files /dev/null and b/theme/readthedocs/img/onBeforeInit-action3-rendered-form.png differ diff --git a/theme/readthedocs/img/onBeforeInit-retrieving-data.png b/theme/readthedocs/img/onBeforeInit-retrieving-data.png new file mode 100644 index 00000000..e2481cd3 Binary files /dev/null and b/theme/readthedocs/img/onBeforeInit-retrieving-data.png differ diff --git a/theme/readthedocs/img/onBeforeInit-settings.png b/theme/readthedocs/img/onBeforeInit-settings.png new file mode 100644 index 00000000..0bd862d6 Binary files /dev/null and b/theme/readthedocs/img/onBeforeInit-settings.png differ