hidden	true

Ressources

Page Properties

hidden	true

Status


colour	Blue
title	review

Priority

2.3

Note

published - language check outstanding

Assignee

Martin

Ressources

yuuvis® RAD - Client-side Form Scripting (parts will be taken over and be available with the next version 2.3

Remarks

Martin B. is working on it together with Manuel and Stevan ...

...

Info

title	Beta Version

Most of the parts are validated, some are marked as in progress. You may use the other ones at your own risk. This document will be released with version Autumn 2020 a.k.a released with Version 2.3 (Autumn 2020).

Excerpt
If you configure custom forms for objects, you can additionally use executable scripts to, e.g., validate data, change data, change field properties - such as "read-only" or "mandatory" - and show context-related messages. Form-related scripts enhance your options by adding further functionalities to support your use cases and processes the best.

...

Note: When field data changes are made using a script (i.e., without user action) when loading the form, the Save option is not available. In contrast, you can disable fields to protect against user changes.

Script Scope

The relevant object is given to each client script under the name 'scope.' This object provides the API so the scripts can access the object fields and their properties.

Properties of 'scope'

Name	Description
`api`	Supplies access to the plug-in API, with 'session' (user information), 'dms' (object details, search via DMS-Service), 'http' (connection to any service), 'config', 'util' (helper functions) and 'agent' properties.
`data`	Supplies all object fields defined in the object or process activity. The fields offer read-only access using the technical name. Available for releases 2017-09-27 (3.22.x) or later.
`model`	Supplies the flattened form model and all object fields defined on the form. The fields can be accessed with the technical name. The form groups cannot be accessed in this way.
`situation`	Supplies the current form model situation. Scripts can respond to the relevant situation. Possible values are 'CREATE' (create), 'SEARCH' (search) and 'EDIT' (edit index data).
`objectId`	Supplies the ID of the current DMS object if available (available since version 6.4).

scope.data

A value of a system property of an object can be read using scope.data['system:<property name>']. These are some of the available system properties. You can find more in the browser console when looking for the currently loaded form script and hovering over 'scope' and looking for section 'data':

Name	Description
system:objectId	Unique ID of the object
system:objectTypeID	Technical name of the object type, e.g., 'tenMytenant:customer'
system:baseTypeId	Specifies whether an object is of type 'folder' or 'document'
system:creationDate	The date and time of cration in the format 'yyyy-mm-ddThh-mm-ss.xxxZ'
system:createdBy	The title of the user that created the object in the format <name>,<surname> (<loginname>)
system:lastModificationDate	The date and time of last modification in the format 'yyyy-mm-ddThh-mm-ss.xxxZ'
system:lastModifiedBy	The title of the last user that edited the object in the format <name>,<surname> (<loginname>)
system:versionNumber	Current version number of the object
system:secondaryObjectTypeIds	This array lists all secondary object types that are part of the current object instance
system:tenant	The tenant name as used when created
system:traceId	Trace ID of the object (todo: write about the meaning)
system:parentId	This ID is given if a document object is filed into a folder.

Code Block

language	java
title	Evaluate on data and getUser()
linenumbers	true

// assign the current objectId to a reference field and the current userId to an organisation field:
scope.model['tenMytenant:reference'].value = scope.data['system:objectId'];
scope.model['tenMytenant:user'].value = scope.api.session.getUser().id;

For scope.api see this documentation: please refer to "Client Plugin API".

scope.situation

For object types, you can create a default form to be used for the CREATE, EDIT and SEARCH situations. In each situation, any included scripts are active.
If a general form is used, but different data management is necessary, it is possible to check which situation is given.
For example, how to deactivate a form script to be used in the 'SEARCH' situation.

...

General object field properties

The following table describes object field properties that can be accessed with 'scope.model'.

Column "Binding"

RO (ReadOnly): ReadOnly properties can only be read. Changes to the values of RO properties do not affect the interface.
RW (ReadWrite): ReadWrite properties can also be written. Changes to the values of RW properties affect the interface.

Each field has the following properties:

Name	Description	Binding
name	The normalized name of the fields. Normalized means the simple field name is lower case. The name must not contain special characters except one ':'. This name is used to map the fields to the 'model.'	RO*
label	The display name of the type in the current user locale. Used as a field identifier.	RO
description	A field description. Can be used in tooltips for example.	RO
type	Describes the data type of the field. The possible values here are documented in the description of field data types. Other field attributes may exist, depending on the data type.	RO
readonly	If the readonly read-only property is set to 'true,' the user cannot change the field value.	RW**
required	Flags a field as mandatory. If this property is set, the user must make an entry.	RW
value	The current value of the field.	RW
cardinality	In case of 'multi' instead of 'single' (equal 'undefined') a list of values can be maintained. A JavaScript array is then always expected in 'value.' Not every data type supports the 'multiselect' property.	RO
RO (ReadOnly): ReadOnly properties can only be read. Value changes of RO properties do not affect the interface. *RW (ReadWrite): ReadWrite properties can also be written. Value changes of RW properties affect the interface.

The following example validates dynamic field properties for required fields and write permissions.

...

Name	Description	JavaScript data type	Multi-selection
STRING	Any text. See also datatype: STRING.	String	Yes
NUMBER	Number and floating point number. See also datatype: NUMBER.	Number	Yes
BOOLEAN	Simple 'on/off' or 'true/false' value.	Boolean	No
DATETIME	A date or a date with time value.	Date	Yes

STRING

For fields of type 'string' the following properties are given:

Name	Description	Binding
maxlen	The maximum number of characters permitted as a value in this field.	RO
minlen	The minimum number of characters permitted as a value in this field.	RO
classification	If available, a specific type of text field is described. 'email' to handle this as e-mail input field 'url' to handle this as web address input field 'phone' to handle this as phone number input field 'id:organization' to handle this as user input field 'id:reference [myObjectTpyte,...]' to handle this as object-reference input field catalog[new,draft,review,released,rejected] to handle this as catalog input field	RO
RO (ReadOnly): ReadOnly properties can only be read. Changes to values of RO properties do not affect the interface. *RW (ReadWrite): ReadWrite properties can also be written. Changes to values of RW properties affect the interface.

NUMBERS

For fields of type integer and decimal the following properties are given:

Name	Description	Binding
maxvalue	The maximum number permitted as a value in this field.	RO
minvalue	The minimum number permitted as a value in this field.	RO
classification	If 'digital' is set the numbers are formatted with a thousand separator, e.g. for Din EN 1,569,345.43 and DE 1.569.345,43	RO
RO (ReadOnly): ReadOnly properties can only be read. Changes to values of RO properties do not affect the interface. *RW (ReadWrite): ReadWrite properties can also be written. Changes to values of RW properties affect the interface.

DATE

Sample Script: Specifying a date in the future

...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

var m=scope.model;
// The name of the date field is Deadline
var deadline=m['myTenant:deadline'];

// Register the onchange handler
deadline.onchange=updateDeadlineState;

// Next is the logic for what we want to happen if the state changes
function updateDeadlineState() {

  if( isBeforeToday( deadline.value ) ) {
    deadline.error = {msg:'Please select a date in the future.'};
  } else {
    // If the validation error does not occur, we may have to delete a previously-set error
    deadline.error = null;
  }
}
function isBeforeToday( pDate

26
27

var m=scope.model;
// The name of the date field is Deadline
var deadline=m['myTenant:deadline'];

// Register the onchange handler
deadline.onchange=updateDeadlineState;

// Next is the logic for what we want to happen if the state changes
function updateDeadlineState() {

  //
    var date = new Date();
    var today = moment(date).startOf('day');
    return moment(pDate).isBefore(today);

}

DATETIME

Important to know:

...

// allowed:
scope.model['tenMytenant:datetime'].value = new Date()
scope.model['tenMytenant:datetime'].value = moment().toDate()

// not allowed, sets the date one day into the past after save:
scope.model['tenMytenant:datetime'].value = moment();

scope.api.<more>

Consult the Client API documentation for more features you may use for specific requirements like notifying the user, getting information about the current user, or calling other services via http.

...

icon	false

Read on

...

Column

width	25%

Another Tutorial

Brief summary of the article linked.

Column

width	25%

Another Concept Article

Brief summary of the article linked.

...

width	25%

Another interesting Tutorial

...

if( isBeforeToday( deadline.value ) ) {
    deadline.error = {msg:'Please select a date in the future.'};
  } else {
    // If the validation error does not occur, we may have to delete a previously-set error
    deadline.error = null;
  }
}
function isBeforeToday( pDate ) {

  //
    var date = new Date();
    var today = moment(date).startOf('day');
    return moment(pDate).isBefore(today);

}

DATETIME

Important to know:

// allowed:
scope.model['tenMytenant:datetime'].value = new Date()
scope.model['tenMytenant:datetime'].value = moment().toDate()

// not allowed, sets the date one day into the past after save:
scope.model['tenMytenant:datetime'].value = moment();

scope.api.<more>

Consult the Client API documentation for more features you may use for specific requirements like notifying the user, getting information about the current user, or calling other services via http.

Version	Old Version 38	New Version 39
Changes made by	Technische Redaktion	Technische Redaktion
Saved on	Oct 30, 2020	Oct 30, 2020

Versions Compared

Key

Ressources

Ressources

Remarks

Script Scope

Properties of 'scope'

scope.data

scope.situation

General object field properties

STRING

NUMBERS

DATE

DATETIME

scope.api.<more>

Read on

Another Tutorial

Another Concept Article

Another interesting Tutorial

DATETIME

scope.api.<more>

Page Comparison

Versions Compared

Key

Ressources

Ressources

Remarks

Script Scope

Properties of 'scope'

scope.data

scope.situation

General object field properties

STRING

NUMBERS

DATE

DATETIME

scope.api.<more>

Read on

Another Tutorial

Another Concept Article

Another interesting Tutorial

DATETIME

scope.api.<more>