Versions Compared

Key

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

...


...


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

...

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

...

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

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

    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.


    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'].onchange=updateActiveState;
    // When the weekly hours change, we want to know this for our calculation
    value=='') ) {
        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.
    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:emplshortaea'].required      = active;
    error = null;
      }
    }
    // Here we calculate the weekdays
    function updateWeekdays() {
        m['tenMytenant:statusweekdays'].required         value= active;
      m['tenMytenant:personnelnoweekdays'].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

    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

    ...

    value / 8;
    }

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

    Data types

    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

    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.

    DATETIME

    todo: evalute this section

    ...

    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.

    ...

    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.