Documents Client SDK

Class: FileContext

documents.sdk FileContext

Constructors

The FileContext provides general information about a document, the possibility to execute scripts, control the edit mode
and gives access to various GUI functions like get/set field values, change the color of fields, change the focus to a
specific field etc.

  • Since:
    • 5.0a

Methods

cancelFileEditMode()

Aborts the file edit mode. Any modifications in the file will be discarded.
This function will work only if the user is already in edit mode.

  • Since:
    • 5.0a

commitFileEditMode()

Stops the file edit mode. Any modifications in the file will be commited.
This function will work only if the user is already in edit mode.

  • Since:
    • 5.0a

executeScript(scriptName, scriptParams, options){Promise|String|undefined}

Executes a server-side file script by its name. Any defined script parameters can be transmitted alike.
The script can either be called synchronous (default) or asynchronous (via options parameter).
If the script result has a defined returnType (defined by context.returnType in the portal script) the
function has no return value and the output depends on the returnType.
With the option dispatch it is possible to always retrieve the script result even if a returnType is defined.
options.dispatch must be set to false (defaults to true) to use the script result as return value.
With option.async = true the function always returns a Promise object. If this option is set it is also
possible to input script parameters defined in the Documents Manager via a dialog. Script parameters added via dialog
will override duplicate scriptParams keys.

Name Type Description
scriptName String

the name of the script
scriptParams Object optional

the input parameters for the script
options Object optional

additional options

Name Type Description
dispatch String optional

default true, if false scriptResult is returned even if the script has a returnType
async String optional

default false, if true the script will be executed asynchronous and will return a promise
useScriptParameterDialog String optional

default false, if true a script parameter dialog will always be displayed if the script has defined parameter, only works if options.async = true
dialogTitle String optional

the title of the script parameter dialog
  • Since:
    • 5.0a
Returns:
Type Description
Promise | String | undefined Promise if options.async === true (see example below), undefined if script result contains returnType, script result String otherwise
Examples
var scriptResult = documentsContext.executeScript("countryScript", { country : "Austria" }, { async : false });
// scriptResult: "Burgenland, Kärnten, Niederösterreich, Oberösterreich, Salzburg, Steiermark, Tirol, Vorarlberg, Wien"
var promise = documentsContext.getFileContext().executeScript("countryScript", { country : "Austria" }, { async : true });
promise.then(function(value) {
	console.log(value); // "Burgenland, Kärnten, Niederösterreich, Oberösterreich, Salzburg, Steiermark, Tirol, Vorarlberg, Wien"
});
var scriptResult = documentsContext.executeScript("aScriptWithReturnType", {param: 'value1'}, { dispatch : false });
// scriptResult is given even if the script has a returnType because dispatch is set to false
---example script---
var capitals = { "Germany" : "Berlin", "Austria" : "Vienna", ... };
return JSON.stringify(capitals);
---example script---

// if options.async === false, the server always returns a string no matter what the original format in the script was. Example to transfer and receive a JSON Object:
var jsonString = documentsContext.getFileContext().executeScript("exampleScript", { }, { async : false });
var capitals = JSON.parse(jsonString);
// capitals: { "Germany" : "Berlin", "Austria" : "Vienna", ... }

getDocumentId(){String}

Returns the id of the current document.

  • Since:
    • 5.0a
Returns:
Type Description
String The id of the current document

getDocumentTitle(){String}

Returns the title of the current document.

  • Since:
    • 5.0a
Returns:
Type Description
String The title of the current document

getFileField$El(fieldName){jQuery}

Returns the jQuery object of a file field's input field by its name.

Name Type Description
fieldName String

the name of the field
  • Since:
    • 5.0a
Returns:
Type Description
jQuery the jQuery object of the input field

getFileFieldEl(fieldName){Element}

Returns the DOM element of a file field's input field by its name.

Name Type Description
fieldName String

the name of the field
  • Since:
    • 5.0a
Returns:
Type Description
Element the DOM element of the input field

getFileFieldElId(fieldName){String}

Returns the DOM element id of a file field's input field by its name.

Name Type Description
fieldName String

the name of the field
  • Since:
    • 5.0b
Returns:
Type Description
String the DOM element id of the input field

getFileFieldId(fieldName){String}

Returns the id of a file field by its name.

Name Type Description
fieldName String

the name of the field
  • Since:
    • 5.0a
Returns:
Type Description
String the id of the field

getFileFieldLabel$El(fieldName){jQuery}

Returns the jQuery object of a file field's label by its name.

Name Type Description
fieldName String

the name of the field
  • Since:
    • 5.0a
Returns:
Type Description
jQuery the jQuery object of the label

getFileFieldNumberValue(fieldName, decimalSeparator, groupingSeparator, options){Number}

Returns the current value of a file field as a number by its name.
If, for any reason, the field is currently not visible, the field value will be retrieved from the file instance on the server. This default fallback behaviour can be disabled by the serverMode option.
If any of the optional decimalSeparator or groupingSeparator parameters is not set, this function will automatically use the default value of the current user locale configured in the Documents Manager.

Name Type Description
fieldName String

the technical file field name
decimalSeparator String optional

the decimal separator character
groupingSeparator String optional

the grouping separator character
options Object optional
Name Type Description
serverMode boolean optional

if true (default) and the field is currently not visible, gets the field value from the server
  • Since:
    • 5.0a
Returns:
Type Description
Number the value of the file field as number
Example
documentsContext.getFileContext().getFileFieldNumberValue("erpNetAmount", ".", ",");

getFileFieldOptions(fieldName){Object}

Gets all available options of a select menu or a double list.

Name Type Description
fieldName String

the file field name
  • Since:
    • 5.0c
Returns:
Type Description
Object An object with the following structure: {"key1":"value1", "key2":"value2",...}
Example
documents.sdk.exitRegistry.registerFileFieldExitCallback("ftRecord", "hrRemarks", function(documentsContext, options) {
	var selectOptions = documentsContext.getFileContext().getFileFieldOptions("hrType"),
		keys = Object.keys(selectOptions);
		values = Object.values(selectOptions);
});

getFileFieldValue(fieldName, options){String}

Returns the current value of a file field by its name.
If, for any reason, the field is currently not visible, the field value will be retrieved from the file instance on the server. This default fallback behaviour can be disabled by the serverMode option.

Name Type Description
fieldName String

the technical file field name
options Object optional
Name Type Description
serverMode boolean optional

if true (default) and the field is currently not visible, gets the field value from the server
  • Since:
    • 5.0a
Returns:
Type Description
String the value of the file field

getFileFieldValues(fieldNames, options){Object}

Gets the values for an array of file fields by their names.

Name Type Description
fieldNames Array.<String>

the file field names
options Object optional
Name Type Description
serverMode boolean optional

get the field value from the server if the field is not visible, default true
  • Since:
    • 5.0a
Returns:
Type Description
Object the current values of the file fields

getFileFormModel(){FileFormModel}

Returns the current file form model.
To modify the current file form before being displayed, it is recommended to use this function
combined with (while not limited to) the exit event File.afterSetModelData.

Returns:
Type Description
FileFormModel the file form model

getFileId(){String}

Returns the id of the current file.

  • Since:
    • 5.0a
Returns:
Type Description
String The id of the current file

getFileProperty(key){String}

Returns the file property for the given key.

Name Type Description
key String

the key of the property
  • Since:
    • 5.0a
Returns:
Type Description
String the file property

getFileRegisterProperty(key){String}

Returns the file register property for the given key.

Name Type Description
key String

the key of the property
  • Since:
    • 5.0a
Returns:
Type Description
String the file register property

getFileTask(){String}

Returns the current file task.

  • Since:
    • 5.0a
Returns:
Type Description
String The current file task

getFileTitle(){String}

Returns the title of the current file.

  • Since:
    • 5.0a
Returns:
Type Description
String The title of the current file

getFileTypeName(){String}

Returns the file type name of the current file.

  • Since:
    • 5.0a
Returns:
Type Description
String The file type name of the current file

getRegisterId(){String}

Returns the id of the current register.

  • Since:
    • 5.0a
Returns:
Type Description
String The id of the current register

getRegisterTitle(){String}

Returns the title of the current register.

  • Since:
    • 5.0a
Returns:
Type Description
String The title of the current register

getRegisterType(){String}

Returns the type of the current register.

  • Since:
    • 5.0a
Returns:
Type Description
String The type of the current register

getScrollPositionLeft(){Number}

Returns the current horizontal scroll position from the left.

  • Since:
    • 5.0a
Returns:
Type Description
Number the current horizontal scroll position

getScrollPositionTop(){Number}

Returns the current vertical scroll position from the top.

  • Since:
    • 5.0a
Returns:
Type Description
Number the current vertical scroll position

isFileEditMode(){Boolean}

Returns if the file is currently in edit mode or not.

  • Since:
    • 5.0a
Returns:
Type Description
Boolean true, if the file is in edit mode, false otherwise

isFileFieldVisible(fieldName){Boolean}

Checks if a file field is currently displayed or not.

Name Type Description
fieldName String

the name of the field
  • Since:
    • 5.0a
Returns:
Type Description
Boolean true if the field is visible, false otherwise

setFileFieldBgColor(fieldName, color)

Sets the background-color of a file field by its name.

Name Type Description
fieldName String

the name of the field
color String

the new color
  • Since:
    • 5.0a
Example
documentsContext.getFileContext().setFileFieldBgColor("erpInvoiceNumber", "#2F4F4F")

setFileFieldBorderColor(fieldName, color)

Sets the border-color of a file field by its name.

Name Type Description
fieldName String

the name of the field
color String

the new color
  • Since:
    • 5.0a
Example
documentsContext.getFileContext().setFileFieldBorderColor("erpInvoiceNumber", "#2F4F4F")

setFileFieldColor(fieldName, color)

Sets the text-color of a file field by its name.

Name Type Description
fieldName String

the name of the field
color String

the new color
  • Since:
    • 5.0a
Example
documentsContext.getFileContext().setFileFieldColor("erpInvoiceNumber", "#2F4F4F")

setFileFieldFocus(fieldName)

Sets the focus to a file field by its name.

Name Type Description
fieldName String

the name of the field
  • Since:
    • 5.0a

setFileFieldLabelColor(fieldName, color)

Sets the text-color of a file field label by its name.

Name Type Description
fieldName String

the name of the field
color String

the new color
  • Since:
    • 5.0a
Example
documentsContext.getFileContext().setFileFieldLabelColor("erpInvoiceNumber", "#2F4F4F")

setFileFieldOptions(fieldName, values, options)

Sets the options for a select menu or the doublelist. This method does not work if the file is not in edit mode.

Name Type Description
fieldName String

the name of the select/doublelist field
values String | Array.<String> | Object

the values for the select/doublelist field
options Object

keepSelected === true: the previously selected value will be kept even if not inside the value String (default),
false: the previously selected value will be removed except when inside the value String
  • Since:
    • 5.0a (select menu) / 5.0c (doublelist)
Example
Possible input for the value parameter
All formats work for both the select menu and the doublelist.
"value,value,..."
"key:value,key:value,..."
"key;locale:value;locale:value,key;locale:value;locale:value,..."
["value1","value2",...]
["key1;value", "key2;value", ...]
["key1;locale1:value;locale2:value", "key2;locale1:value;locale2:value", ...]
{"key1":"value1", "key2":"value2",...}
group and selected are doublelist only parameter, they will be skipped if used for a select menu
{"key1":{"group":"group","selected":true/false,"locale1":"value","locale2":"value"}, "key2":{"group":"group","selected":true/false,"locale1":"value","locale2":"value"}, ...}

setFileFieldReference(fieldName, referenceFileId)

Sets a file reference.
Removing the file reference can be achieved by passing null or "" in referenceFileId.

Name Type Description
fieldName String

the name of the field
referenceFileId String

the id of the reference file, null or "" to reset
  • Since:
    • 5.0b

setFileFieldValue(fieldName, value, options){String}

Sets the value of a file field to the specified value by its name.
Caution: This function will work correctly only if the current file is already in edit mode.
If, for any reason, the field is currently not visible, the field value will be set to the file instance on the server. This default fallback behaviour can be disabled by the serverMode option.

Name Type Description
fieldName String

the technical file field name
value String | Array.<String> optional

the new value of the file field, can be an array if used with a multi-value field type
options Object optional
Name Type Description
serverMode boolean optional

if true (default) and the field is currently not visible, sets the field value to the server
  • Since:
    • 5.0a
Returns:
Type Description
String the old value of the file field

setFileFieldValues(fieldValues, options)

Sets the value of multiple file fields to the specified value by its name.
Caution: This function will work only if the user is already in edit mode.

Name Type Description
fieldValues Object
options Object optional
Name Type Description
serverMode boolean optional

set the field value on the server if the field is not visible, default true
  • Since:
    • 5.0a
Example
documentsContext.getFileContext().setFileFieldValues({"hrFirstName":"value1","hrLastName":"value2"})

setScrollPositionLeft(value)

Sets the horizontal scroll position from the left.

Name Type Description
value Number

the new horizontal scroll position
  • Since:
    • 5.0a

setScrollPositionTop(value)

Sets the vertical scroll position from the top.

Name Type Description
value Number

the new vertical scroll position
  • Since:
    • 5.0a

startFileEditMode()

Starts the file edit mode.
This function will work only if the user is not already in edit mode.

  • Since:
    • 5.0a

toggleMonitorView(action, options)

Opens or closes the file monitor view.

Name Type Description
action String

action the action that should be performed, permitted values: open, close
options Object optional
Name Type Description
animate boolean optional

true (default) if the open or close action should be animated, false otherwise
  • Since:
    • 5.0d

toggleRegisterbarView(action, options)

Opens or closes the file registerbar view.

Name Type Description
action String

action the action that should be performed, permitted values: open, close
options Object optional
Name Type Description
animate boolean optional

true (default) if the open or close action should be animated, false otherwise
  • Since:
    • 5.0d