Gadget API

Class: Form

otris.gadget.gui. Form

Constructors

Name Type Description
viewId string optional

the viewId of the form (The viewId specifies the destination in the DOM. This destination must exist otherwise the gadget is not rendered.)

Extends

Methods

addAutoCompleteField(name, label, value, autoCompleteConfig){otris.gadget.gui.Element}

Adds an autoComplete field to the form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string | object

the predefined value of the autoCompleteField. Type object if autoCompleteConfig.isReference is used. See example for details.
autoCompleteConfig string | object optional

autocomplete config object or only the name of the autoComplete script (string)

Name Type Default Description
scriptName string

the name of the autoComplete script to execute.
maxResults number 10 optional

max results
minQueryChars number 3 optional

min query length
queryDelay number 0.5 optional

delay in seconds
autoSelectFirstResult boolean true optional

auto select first result
scriptParams object optional

optional script parameter
isReference boolean optional

Use the autocomplete field as reference field. See example for details (since: Documents 5.0e)
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form
Examples
var autoCompleteConfig = {
	 scriptName: "autoCompleteScript",
	 maxResults: 10,
	 minQueryChars: 3,
	 queryDelay: 0.5, // in seconds
	 autoSelectFirstResult: true,
	 scriptParams: {
		optionalParameter: "1",
		anotherParam: "sample value",
		booleanFlag: true
	 }
};
var autoCompleteField = form.addAutoCompleteField("fieldName", "Field label", "Default value", autoCompleteConfig);
// AutoComplete field as reference field (since: `Documents 5.0e`)
var autocompleteConfig = {
			scriptName: "autocompleteScript",
			isReference: true,
			// ...other params
};
var refObject = { label: "Angus MaxGyver", id: "9347" };
form.addAutoCompleteField("otrGadgetForm_contact", "Ansprechpartner", refObject, autocompleteConfig);
// Example code for the autocomplete script
var json = [{
  value: 'First GmbH',
  fields: [
    { name: 'otrGadgetForm_contact', value: { id: "1", label: "One" } }
  ]
},
{
  value: 'Third GmbH & Co KG',
  fields: [
    { name: 'otrGadgetForm_contact', value: { id: "3", label: "Three" } }
  ]
}
// ...more entries
];
return JSON.stringify(json);

addButton(name, label, onClickHandler){otris.gadget.gui.Element}

Adds a button to the form with an user defined onClickHandler.

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
onClickHandler string

the NAME of a JavaScript function which is available at client side (called when the button is clicked)
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addCheckbox(name, label, value, checked){otris.gadget.gui.Element}

Adds a checkbox to the form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string

the predefined value of the form field
checked boolean

the initial check state
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addCheckboxList(name, label, selectableValues){otris.gadget.gui.SelectableElement}

Adds a CheckboxList (a list of checkboxes where multiple checkboxes can be checked) to the form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
selectableValues Array

the predefined values that can be selected (an array of arrays containing values and labels, e.g.: [['value1', 'label1'],['value2', 'label2']])
Returns:
Type Description
otris.gadget.gui.SelectableElement element representing the form field added which can be further manipulated before transfering the form

inherited addClientFunction(clientFunction)

Adds a JavaScript Function to this Transferable Object. When the Object is transfered to the client the functions added to this Object will be available on the client side.

Name Type Description
clientFunction function

The function to be added to the clientFunctions of this Object. (Can be a JavaScript Function or an Object returned by otris.gadget.util.FunctionUtils.getFunctionObject)

inherited addContainerButton(buttonConfig){object}

Adds a container button.
If the gadget is displayed in a dialog the container buttons are rendered as dialog buttons (bottom right corner of the dialog).
Otherwise the container buttons are ignored

Name Type Description
buttonConfig object

button config object

Name Type Default Description
id string

button id
label string

button label
clickFunction string

name of the client function to execute on click
disabled boolean false optional
  • Since:
    • Documents 5.0e
Returns:
Type Description
object buttonConfig
Example
// Alternative gadget action button
gadgetForm.addContainerButton({ id: "myCustomSaveButton", label: "Speichern", clickFunction: "saveGadgetData" });
gadgetForm.addClientFunction(function saveGadgetData(event) {
  var gForm = documentsContext.getGadgetContext().getClientObject();
  gForm.submitForm({ gadgetAction: "processForm" }, { showBusyPanel: true });
});

addCustomField(name, label, data, loader){otris.gadget.gui.Element}

Adds a custom Component as form field to the form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
data any

the data that the loader function will get as its argument
loader function

the function that will be called when the component is loaded into the form
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addDateField(name, label, value, addTime){otris.gadget.gui.Element}

Adds a date field with a date picker to the Form

Name Type Default Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string | date

the predefined value of the form field
addTime boolean true optional

add hours and minutes
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addDependency(controller, condition, value, fields)

Adds a dependency describing a relation between form fields

Name Type Description
controller string

the controller form field which affects other form fields
condition string

the condition to be tested ("==", "!=", "any", "non-any")
value string

the value to test the controller for
fields Array

the fields that are affected if the condition yields true

addDoubleSelectList(name, label, selectableValues){otris.gadget.gui.SelectableElement}

Adds a double Select field to the Form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
selectableValues Array

the predefined values that can be selected (an array of arrays containing values and labels, e.g.: [['value1', 'label1'],['value2', 'label2']])
Returns:
Type Description
otris.gadget.gui.SelectableElement element representing the form field added which can be further manipulated before transfering the form

addDropzone(name, label, dropzoneValues, dropzoneConfig){otris.gadget.gui.Element}

Adds a dropzone to the Form. The uploaded files could be accessed through the
portal script method context.getTempPathByToken(accessToken).

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
dropzoneValues DropzoneValue | Array.<DropzoneValue> optional

list of the uploaded files (see: DropzoneValue)
dropzoneConfig object optional

the dropzone configuration

Name Type Default Description
multiple boolean true optional

allow multiple uploads
height number optional

height in pixel
style string optional

additional css styles (e.g.: background-color:#333;color:#fff;)
icon string ionicons:ion-md-cloud-upload optional

icon for the dropzone
label string Dropzone optional

label for the dropzone
labelStyle string optional

additional css styles for the label (e.g.: font-size:32px;font-weight:bold;)
extensions Array.<string> optional

allowed extensions
maxSize number optional

max file size (in bytes)
  • Since:
    • Documents 5.0d
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form
Example
var myDropzoneConfig = {
       multiple: false,
       height: 120,
       icon: "ionicons:ion-md-cloud-upload;font-size:64px;",
       label: "UploadArea",
       extensions: ["jpg", "jpeg", "png", "gif"], // only allow image formats
       maxSize: 2000000 // restrict filesize to a maximum of 2MB
};
var myDropzoneElement = form.addDropzone("myDropzone", "My dropzone", null, myDropzoneConfig);

addEMailField(name, label, value){otris.gadget.gui.Element}

Adds an E-Mail field to the Form (can only contain valid e-mail adresses)

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string

the predefined value of the form field
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addExtComponent(name, label, extComponent)

Adds an ext Component as form field to the form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
extComponent otris.gadget.gui.ExtComponent

the extComponent
  • Deprecated
    • Yes

addGadgetActionButton(name, label, gadgetConfig, options){otris.gadget.gui.Element}

Adds a button to the form which will call another gadget

Please note that since version 2.3.3 the signature of this function has changed. The old signature
addGadgetActionButton(name, label, gadgetConfig, newWindow, windowOptions)
is still supported but should not be used anymore.

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
gadgetConfig object optional

the gadget config for the gadget to be called when the button is pressed
options object optional

additional options

Name Type Default Description
newWindow boolean optional

open the gadget in a new window
windowOptions object optional

the options to configure the appearance of the new window
validateForm boolean true optional

whether the actionButton validates the form
showBusyPanel boolean false optional

Lock the target gadget container after clicking the button. (since: Documents 5.0e)
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form
Example
form.addGadgetActionButton('customerTableButton','Customers',{gadgetScript: 'CustomerGadgets', gadgetAction: 'showCustomerTable', myFilter: 'Peach*'});

 //In the called gadget the parameters in the configuration can be accessed by
 gadgetContext.gadgetParams.myFilter
 //or
 gadgetContext.gadgetParams['myFilter'];

 //The values of the form fields of the form can be accessed by
 $FORM.myFormField
 //or
 $FORM['myFormField']

addHeadLine(value){otris.gadget.gui.Element}

Adds a html headline to the form

Name Type Description
value string

the text of the headline
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addHiddenField(name, value){otris.gadget.gui.Element}

Adds a hidden form field to the form

Name Type Description
name string

the technical name of the field
value string

the value of the form field
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addHtmlField(name, label, value, editorConfig){otris.gadget.gui.Element}

Adds a html field to the Form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string optional

the predefined value of the form field
editorConfig object optional

editor configuration

Name Type Description
ckEditor object

configuration for the CKEditor (https://ckeditor.com/)
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addImage(id, src, onClickHandler){otris.gadget.gui.Element}

Adds an image to the form

Name Type Description
id string

the technical name of the image
src string

the path to the image file
onClickHandler string

the NAME of a JavaScript function which is available at client side (called when the image is clicked)
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addNumberField(name, label, value){otris.gadget.gui.Element}

Adds a number field to the Form (a text field which can only contain numbers)

Name Type Description
name string

the technical name of the form field
label string

(visible) label of the form field
value string

the predefined value of the form field
Returns:
Type Description
otris.gadget.gui.Element
  • The representing the form field added which can be further manipulated before transfering the form

addPasswordField(name, label, value){otris.gadget.gui.Element}

Adds a password field to the Form (the content will be hidden with asterisks while typing)

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string

the predefined value of the form field
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

inherited addPdfButton(config)

Adds a button to download the displayed gadget as pdf. The button will show on hover in the left top corner of the gadget.

Name Type Description
config object optional

config object

Name Type Default Description
filename string content.pdf optional

filename of the pdf for download
buttonStyle string left: 200px; optional

style for the pdf button to be applied to
  • Since:
    • Documents 5.0d
Example
myGadget.addPdfButton({filename: "myCustomFilename.pdf", buttonStyle: "left: 200px; });

addRadiobuttonList(name, label, selectableValues){otris.gadget.gui.SelectableElement}

Adds a radioButtonList (a list of radio buttons where only one can be checked) to the form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
selectableValues Array

the predefined values that can be selected (an array of arrays containing values and labels, e.g.: [['value1', 'label1'],['value2', 'label2']])
Returns:
Type Description
otris.gadget.gui.SelectableElement element representing the form field added which can be further manipulated before transfering the form

inherited addSettings(option)

Adds a setting (an option that can be defined by the user) to the gadget.

Name Type Description
option GadgetSetting | Array.<GadgetSetting>

the setting(s) to add to the gadget.
  • Since:
    • Documents 5.0a

addSingleSelectList(name, label, selectableValues, multiple, size){otris.gadget.gui.SelectableElement}

Adds an Select field to the Form. The SingleSelectList is an SelectableElement please see <otris.gadget.gui.SelectableElement> for more information.

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
selectableValues Array

the predefined values that can be selected (an array of arrays containing values and labels, e.g.: [['value1', 'label1'],['value2', 'label2']])
multiple boolean

Enable multiple selection
size number

the number of entries that are displayed by this select list without scrolling or using the dropdown menu
Returns:
Type Description
otris.gadget.gui.SelectableElement element representing the form field added which can be further manipulated before transfering the form

addText(value){otris.gadget.gui.Element}

Adds a html div containing text to the form

Name Type Description
value string

the text content of the div
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addTextArea(name, label, value){otris.gadget.gui.Element}

Adds a text area field to the Form

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string

the predefined value of the form field
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addTextField(name, label, value){otris.gadget.gui.Element}

Adds a text field to the Form (can contain any text)

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string

the predefined value of the form field
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

addURLField(name, label, value){otris.gadget.gui.Element}

Adds an URL field to the Form (can only contain valid URLs)

Name Type Description
name string

the technical name of the form field
label string

the (visible) label of the form field
value string

the predefined value of the form field
Returns:
Type Description
otris.gadget.gui.Element element representing the form field added which can be further manipulated before transfering the form

inherited onGadgetLoad(onloadHandler)

Sets an onLoad handler for the Gadget. The handler is executed when the gadget is displayed at the client.

Name Type Description
onloadHandler function | string

the handler to be executed (must be either a javascript function or a string representing a function)

setAutoOverrideDefaults(active)

Sets the autoOverrideDefaults flag.
Replaces the values of the elements if a fitting value exists in gadgetContext.formParams

Name Type Description
active boolean

the boolean value whether to override the elements values

inherited setContainerButtons(containerButtonConfigs)

Set the container buttons.
Please note that existing default buttons are removed by this operation.

Name Type Description
containerButtonConfigs Array.<object>

array of button config objects

Name Type Default Description
id string

button id
label string

button label
clickFunction string

name of the client function to execute on click
disabled boolean false optional

inherited setContextData(contextData)

Set additional data which is serialized with JSON.stringify() and then transferred to the client
On the client side the the context data is accessible with the GadgetContext

Name Type Description
contextData any

the context data
  • Since:
    • Documents 5.0c
Example
var htmlGadget = new otris.gadget.gui.HTML("<h1>Only a simple example</h1>");
var myGadgetData = {
    mySpecialId: 44137,
    myIndexArray: [1,7,6,3,2],
    myTitle: "A special GadgetTitle"
};
htmlGadget.setContextData(myGadgetData);

setFormValidator(validator)

Applies a validator to the entire form
A validatorFunction is used to validate the content of the input element
The form can only be submitted if all validators are successful

Name Type Description
validator function

function to validate an input field

validatorFunction(field, gadgetForm, options){validationResult}

The validator function
The field object contains a single field if this validator function is used by otris.gadget.gui.Element#setValidator
The field object contains multiple fields if this validator function is used by otris.gadget.gui.Form#setFormValidator

Name Type Description
field Field | object

single input field information or object containing mutliple field informations
gadgetForm GadgetForm

reference to the GadgetForm
options object

options

Name Type Description
documentsContext documents.sdk.DocumentsContext

reference to the documents.sdk.DocumentsContext
Returns:
Type Description
validationResult
  • validation result should be generated via GadgetForm
Example
//validates whether two company fields of the form have the same value
form.setFormValidator(function validateCompaniesEqual(field, gadgetForm, options){
     //this form has two input elements with the ids company1 and company2
     var successful = field.company1.value === field.company2.value;
     return gadgetForm.createFormValidatorResult(successful, "Company1 and Company2 must be equal!");
});

inherited setNavibarEntry(gadgetConfig, label)

Add a navibar entry. Define a gadgetConfig that reloads the gadget.
Only works if the gadget ist displayed in main list view area.

Name Type Description
gadgetConfig object

gadgetConfig
label string optional

label for the navibar entry (defaults to the gadget title)
  • Since:
    • Documents 5.0e

inherited setStyle(name, value)

Sets a style attribute of the html container

Name Type Description
name string

the name of the style parameter (i.e. "height")
value string

the value of the style parameter (i.e. "100px")

inherited setTitle(title)

Sets the Title of the Form

Name Type Description
title string

the title of the form (will be displayed as the window header on dashboards)

inherited store(key, value)

Stores data that can later be accessed on client side.
ATTENTION: The store used in this method is global.
Use setContextData to store data for this gadget instance.

Name Type Description
key string

the key to store the data
value any

the value, or object that should be stored

transfer()

Make this object ready for beeing transferred to the client