Versions Compared

Key

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


Statusstatus
Page Properties
hiddentrue
id
DONE

colourBlue
titlereview
Priority2.3
Product Version2020 Autumn / 2.4
Report Notepublished - language check outstanding
AssigneeMartin
Ressources

Resources & Remarks

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

Remarks

2020 Autumn

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

Modification History

NameDateProduct VersionAction
Antje08 FEB 20212.4New page properties macro.



Info

This documentation is valid from yuuvis® Momentum, Version 2.3 (Autumn 2020)2020 Autumn.


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

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

...

For scope.api please refer to "Client Plugin Scripting 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"

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

...

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();

...

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. DateYes
ORGANIZATIONA string field for saving user IDs. The title of the user is shown, or the ID if no title exists.StringYes
IDA string field for saving object IDs. The IDs can be restricted to the specified object types defined in the classification - tag 'id:reference[object type 1, object type 2, ...]. The title of the object is shown, or the ID if no title exists, or '!******' if the object can't cannot be accessed.StringYes
CATALOGA string field for saving elements of a given array in the classification - tag 'catalog[value1, value2, ...]'StringYes
TABLEA table with columns of the above datatypesdata typesTableNo

STRING

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

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.

NUMBERS

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

NameDescriptionBinding
maxvalueThe maximum number permitted as a value in this field.RO
minvalueThe 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 ) {
    
  // Todo: rework not available moment to a different function:
    var date = new Date();
    var today = moment(date).startOf('day');
    return moment(pDate).isBefore(today);
   
}

...

// 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();

TABLE

Expects a JavaScript 'As of version 2.4, tables are supported.

Expects a JavaScript 'Object Array' as a 'value.' The properties of each object are defined by the column elements of the table. See the following example.

...

Code Block
languagejs
titleExample: Manipulating table data
linenumberstrue
/**
 * Example script: Manipulating table data based on index data change.
 */
// Add change listener to field 'myTenant:number'
scope.model.['myTenant:number'].onchange=function() {
     
    // The current user input on field with the internal name 'myTenant:number'
    var num = scope.model.['myTenant:number'].value;
     
    // Shortcut to access the table
    var table = scope.model.['myTenant:changes'];
     
    if(num>0 ) {
        // If 'myTenant:number' is set (greater than 0) we automatically fill the table
        if( !table.readonly ) {
            // The user may not modify the table
            table.readonly=true;
            // Copy the current values to a property using lodash
   
        table.old_value=_.map(table.value, _.clone);
        }
    } else {
        // If 'myTenant:number' is not set (less than 0) we let the user fill the table
        if( table.readonly ) {
            // Copy The user may modify the oldtable
values back to values using lodash       table.readonly=false
     table.value=_.map(table.old_value, _.clone);  }
    }
     // Theautomatically userfills maythe modifytable the table
   if 'myTenant:number' is greater than 0
    // and add  table.readonly=false;
  num rows to the table
    if(num>0) {
   // Cleanup    // Clean up the table by setting a empty deletearray
		table.old_value.length=0;   // changes of a single cell }must be done in an }array variable first, 
 								// automaticallyand fillsthen thethis tablearray if 'myTenant:number' is greater than 0
 has to be pushed back to the table.
  // and add num rows to the table
    if(num>0for( i=0; i<num; i++ ) {
        // Clean up the table by setting a empty array
		table.value.length=0; // For each 'myTenant:number' add a row
            // changesEach ofrow ais singlean cellobject mustdefined beby donethe ininternal annames arrayof variablethe first,column 
								// and then this array has to be pushed back to the table.elements.
            table.value.push(
        for( i=0; i<num; i++ ) {        {
               //   For each 'myTenant:numberaccepted' add a row: i%2,                   // Each row is an object defined by the internal names of// theBoolean
column elements.             table.value.push(      'myTenant:created': new Date() ,        // {Date
                    ['myTenant:acceptedactivedate']: i%2new Date(),     // Another date
                      // Boolean
 'myTenant:author': 'Marie Curie '+i,                   ['myTenant:created']: moment().add(i,'day').toDate(),   // String: Author name with //i Datepostfix
                    ['myTenant:activedateprio']: moment().add(i,'day').toDate()i+.42,     // Another date                     ['myTenant:author']: 'Marie Curie '+i,                       // String:Decimal
Author name with i postfix                     ['myTenant:priocompany'] : i+.42,    'OSVH'                                // DecimalCodesystem - the 'data' values must be used.
              ['myTenant:company'] : 'OSVH'}
            )
        } // end for num
    } // Codesystemend -if the 'data' values must be used.
                }
            )
        } // end for num
    } // end if num>0
}

...

num>0
}
Callback for tables
NameDescription
onroweditThis callback is called when the user starts to edit a table row. Like 'onchange,' the first parameter contains the field element (the table itself). The second parameter contains a 'row' object, which describes the row the user wants to edit.

...

NameDescriptionBinding
indexRow index: '-1' for newly - created rowrows. The first row has the value '0'.RO*
copyEnabledControls whether the "Copy and create as new row" function is enabled. You can only edit this synchronously inside the onrowedit.RW**
deleteEnabledControls whether the "Delete row" feature is enabled. You can only edit this synchronously inside the onrowedit.RW
saveEnabledControls whether the "Save row" feature is enabled. You can only edit this synchronously inside the onrowedit.RW
persistedIs 'false' if the edited file was newly created. The property remains 'false' for new rows until the index data is saved. You can use this property to differentiate between a row that has been saved or newly created by the user during the current index data editing.RO
modelProvides access to the model of the current row. With this model, the script can access and modify the values and element properties of the current row.RW

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

See how the 'row' object is used in the following example.

...

Code Block
languagejs
titleExample: onChange handler for a table cell
linenumberstrue
scope.model.['myTenant:mytable'].onrowedit = function(table, row){
	// On this element we register a value change handler
	row.model.number.onchange = function(el, rowmodel) {	
		// The rowmodel provides access to the other elements
		// '['myTenant:number2']' is another element of type 'NUMBER' that is contained in the table element
		// On Forthis theelement sakewe ofregister examplea thisvalue fieldchange is set to readonly, if the user inputs a special number in 'elementNumber'
handler
	row.model.['myTenant:number'].onchange = function(el, rowmodel) {	
		// The rowmodel provides access to the other elements
		rowmodel.['myTenant:number2number'].readonly = ( el.value == 42 );
	}
}

...

If we deal with more complex table value manipulation, we need to create a copy of the values. Once the values are written, the table gets is populated and changes will get be lost. Once all the cell manipulations are done, we can assign the manipulated values to the table values.

Code Block
languagejs
linenumberstrue
// see Manipulating table data
...
let tableCopy = JSON.parse(JSON.stringify(['myTenant:mytable'].value)); //create a copy
for ( i = 0; i < num; i++ ) {
	if (i === 0) {
			tableCopy[i].['myTenant:accepted'] = !i%2,                               // Boolean
            tableCopy[i].['myTenant:created'] = moment().add(i+5,'day').toDate'] = new Date(),    // Date
            tableCopy[i].['myTenant:activedate'] = momentnew Date().add(i+5,'day').toDate(), // Another date
			tableCopy[i].['myTenant:author'] = 'Pierre Curie '+i,                    // String: Author name with i postfix
            tableCopy[i].['myTenant:prio'] = i+.00,                                  // Decimal
            tableCopy[i].['myTenant:company'] = 'OSVH'                               // Codesystem - the 'data'Catalog values must be used.
	} else {
    	// For each number add a row
	    // Each row is an object defined by the internal names of the column elements.
    	tableCopy.push({
            	['myTenant:accepted']: i%2,                              // Boolean
	            ['myTenant:created']: new momentDate().add(i,'day').toDate(),    // Date
            	['myTenant:activedate']: momentnew Date().add(i,'day').toDate(), // Another date
        	    ['myTenant:author']: 'Marie Curie '+i,                   // String: Author name with i postfix
    	        ['myTenant:prio']: i+.42,                                // Decimal
	            ['myTenant:company']: 'OSVH'                             // String: Element of a catalog
    	    });
	}
	// do even more fancy data manipulations
} // end for num
table.value = tableCopy;
...
// see Manipulating table data

...

scope.api.<more>

Please refer to the Client Plugin Scripting API documentation for more features you may use for specific requirements like notifying the userusers, getting information about the current user, or calling other services via http.