Versions Compared

Version Old Version 13 New Version 14
Changes made by

Team Kolibri (Unlicensed)

Team Kolibri (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


...

hiddentrue

...

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 ...

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 to be 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. 

...

bordertrue
Column

Table of Contents

Table of Contents
exclude(Table of Contents|Read on|Another Tutorial|Another Concept Article|Another interesting Tutorial)

Introduction

In yuuvis® Momentum client, you can use executable scripts to:

  • validate data
  • change data, for example by calculating a value based on other values
  • change field properties, such as read-only and visibility
  • show context-related messages.

Some things to note about script properties:

  • Client scripts in yuuvis® Momentum architect are written in JavaScript (ECMAScript).
  • Client scripts execute in the user's browser using the browser's native JavaScript runtime.
  • You can define client scripts by object type and form situation.

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

...

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).

...

scope.data

A value of a system property of an object can be read using scope.data['system:<property name>']. These system properties are available here:

...

Name

...

Description

...


Page Properties
hiddentrue

Status

Status
colourRed
titleSTUB

Priority2.3
NoteMartin / Manuel / Stevan

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 ...


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 to be 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. 


Section
bordertrue


Column

Table of Contents

Table of Contents
exclude(Table of Contents|Read on|Another Tutorial|Another Concept Article|Another interesting Tutorial)


Introduction

In yuuvis® Momentum client, you can use executable scripts to:

  • validate data
  • change data, for example by calculating a value based on other values
  • change field properties, such as read-only and visibility
  • show context-related messages.

Some things to note about script properties:

  • Client scripts in yuuvis® Momentum architect are written in JavaScript (ECMAScript).
  • Client scripts execute in the user's browser using the browser's native JavaScript runtime.
  • You can define client scripts by object type and form situation.

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

apiSupplies 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.
dataSupplies all object fields defined in the object or process activity. The fields offer read-only access using the technical name. Available for release 2017-09-27 (3.22.x) or later.
modelSupplies 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).

objectIdSupplies 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 system properties are available here:

Name

Description

system:objectIdunique ID of the object
system:objectTypeIDtechnical name of the object-type, e.g. 'tenMytenant:customer'
system:baseTypeIdspecifies whether an object is of type 'folder' or 'document'
system:createdBythe title of the user that created the object in the format <name>,<surname> (<loginname>)
system:lastModificationDatethe date and time of last modification in the forma '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:versionNumbercurrent version number of the object
system:tenantthe 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. 

Todo: which else e.g. retention properties


Code Block
languagejava
titleEvaluate on data
linenumberstrue
variablename = scope.data['system:objectId']

...

This section describes how to access all form elements of objects or processes.

Field properties

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

Column "Binding"

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

Each field has the following properties:

NameDescriptionBinding
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*
labelThe display name of the type in the current user locale. Used as a field identifier.RO
descriptionA 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
readonlyIf the readonly property is set to 'true,' the user cannot change the field value.RW**
requiredFlags a field as mandatory. If this property is set, the user must make an entry.RW
valueThe 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.

Example: onChange handler for form validation and user input

Data type-specific properties

STRING

NameDescriptionBindingmaxlenThe maximum number of characters permitted as a value in this field.ROminlenThe minimum number of characters permitted as a value in this field.ROclassification

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.

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Abbreviate with 'm' in the FormModel of the scope.
// You could just use 'scope.model' everywhere instead of 'm'.
var m = scope.model;
// We want to know if the active state changes
// To do so, we register an onchange handler function
m['tenMytenant:aktiv'].onchange=updateActiveState;
// The logic should also run when there are changes in the area, since we want to
// control the error state of the script here.
m['tenMytenant:area'].onchange=updateActiveState;
// When the weekly hours change, we want to know this for our calculation
m['tenMytenant:weekhours'].onchange=updateWeekdays;

// Here is the logic implementation for what happens when the active state changes

function updateActiveState() {

  // Employee initials + status + employee number are required fields,
  // when the employee is active.
  m['tenMytenant:emplshort'].required      = active;
  m['tenMytenant:status'].required         = active;
  m['tenMytenant:personnelno'].required     = active;
    
  // The regulations cannot be changed as long as the employee is active.
  m['tenMytenant:unbefristet'].readonly        = active;
  m['tenMytenant:zielvereinbarung'].readonly   = active;
  m['tenMytenant:altersvorsorge'].readonly     = active;
    
  // Example for a deliberately-set validation error with relevant error message
  // take into account that the error message will be offered for non read-only fields!
  if( active && (!m['tenMytenant:area'].value || m['tenMytenant:area'].value=='') ) {
    m['tenMytenant:area'].error = {msg:'Ein aktiver Mitarbeiter muss einem Bereich zugeordnet sein.'};
  } else {
    // If the validation error does not occur, we may have to reset a previously-set error:
    if (scope.user) {
        m['tenMytenant:area'].error = null;
    }
    m['tenMytenant:aea'].error = null;
  }
}
// Here we calculate the weekdays
function updateWeekdays() {
    m['tenMytenant:weekdays'].value=m['tenMytenant:weekdays'].value / 8;
}

// Since the active/not active logic should already apply during form initialization,
// we call the function here.
updateActiveState();

Data types – field properties

The following table gives an overview of the possible data types per field. The JavaScript data type lists what is expected as the 'value' of an element.

If the 'multiselect' property is set, then the JavaScript data type is an array of the data type.

...

Name

...

Description

...

JavaScript data type

...

Multi-selection

...

33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Abbreviate with 'm' in the FormModel of the scope.
// You could just use 'scope.model' everywhere instead of 'm'.
var m = scope.model;
// We want to know if the active state changes
// To do so, we register an onchange handler function
m['tenMytenant:aktiv'].onchange=updateActiveState;
// The logic should also run when there are changes in the area, since we want to
// control the error state of the script here.
m['tenMytenant:area'].onchange=updateActiveState;
// When the weekly hours change, we want to know this for our calculation
m['tenMytenant:weekhours'].onchange=updateWeekdays;

// Here is the logic implementation for what happens when the active state changes

function updateActiveState() {

  // Employee initials + status + employee number are required fields,
  // when the employee is active.
  m['tenMytenant:emplshort'].required      = active;
  m['tenMytenant:status'].required         = active;
  m['tenMytenant:personnelno'].required     = active;
    
  // The regulations cannot be changed as long as the employee is active.
  m['tenMytenant:unbefristet'].readonly        = active;
  m['tenMytenant:zielvereinbarung'].readonly   = active;
  m['tenMytenant:altersvorsorge'].readonly     = active;
    
  // Example for a deliberately-set validation error with relevant error message
  // take into account that the error message will be offered for non read-only fields!
  if( active && (!m['tenMytenant:area'].value || m['tenMytenant:area'].value=='') ) {
    m['tenMytenant:area'].error = {msg:'Ein aktiver Mitarbeiter muss einem Bereich zugeordnet sein.'};
  } else {
    // If the validation error does not occur, we may have to reset a previously-set error:
    if (scope.user) {
        m['tenMytenant:area'].error = null;
    }
    m['tenMytenant:aea'].error = null;
  }
}
// Here we calculate the weekdays
function updateWeekdays() {
    m['tenMytenant:weekdays'].value=m['tenMytenant:weekdays'].value / 8;
}

// Since the active/not active logic should already apply during form initialization,
// we call the function here.
updateActiveState();

Data types – field properties

The following table gives an overview of the possible data types per field. The JavaScript data type lists what is expected as the 'value' of an element.

If the 'multiselect' property is set, then the JavaScript data type is an array of the data type.


Name

Description

JavaScript data type

Multi-selection

STRINGAny text. See also datatype: STRING.StringYes
NUMBERNumber and floating point number. See also datatype: NUMBER.NumberYes
BOOLEANSimple 'on/off' or 'true/false' value.BooleanNo
DATETIMEA date or a date with time value. See also datatype: DATETIME.DateYes
TABLEA table with values. See also datatype: TABLE.Object Array
Properties of each object are defined by the column elements of the table.		No

Data type-specific properties

STRING

NameDescriptionBinding
maxlenThe maximum number of characters permitted as a value in this field.RO
minlenThe 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.


DATETIME

todo: evalute this section

Expects a JavaScript 'Date' as value.

NameDescription (DMS and BPM)Binding
withtimeIs 'true' or 'false.' If 'true,' a time in seconds is expected in addition to the date.RO*

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

The value is not available in the 'SEARCH' situation.


Sample Script: Specifying a date in the future

When determining a deadline for working on the next process step, you want to make sure the date is not in the past.
Example: Validate 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.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:'Bitte wählen Sei ein Datum in der Zukunft.'};
  } 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);
   
}

DATE

todo: evalute this section

Important to know:

// allowed:
scope.model.datumfeld.value = new Date()
scope.model.datumfeld.value = moment().toDate()
 
// not allowed, sets the date one day into the past after save:
scope.model.datumfeld.value = moment();



Info
iconfalse

Read on

Section


Column
width25%

Another Tutorial

Brief summary of the article linked.


Column
width25%

Another Concept Article

Brief summary of the article linked.


Column
width25%

Another interesting Tutorial

Brief summary of the article linked.