NEW 2022/11

Calculated fields

Docs moved from here

This new feature allows you to define functions for automatically calculated fields on client side.

Client side calculated fields automatically update their content whenever you change values of related fields.

For example:

• On change of any of the following fields...
• Last Name
• Middle Names
• First Name
• ...automatically calculate a value for field...
• Full Name

This is different from calculated fields, configured in your model (SQL query), being calculated on serverside whenever a user can see a record of that table.

Client side calculated fields automatically show their new values even before you save the record.

---

Prerequisites

Create a new VarChar field, editable (not readonly).

---

Join multiple fields' values

Calculate field full_name. Join values of fields last_name, first_name, middle_names. Default separator: ,

// file: hooks/contacts-dv.js
// get a handle to detail view
var dv = AppGiniHelper.dv;

dv.getField("full_name")
    .setFunction(["last_name", "first_name", "middle_names"]);

Note

Missing part will be left out automatically

Join multiple fields' values

with different separator ("glue")

See 2nd parameter:

// custom separator: " / "
var glue = " / ";
dv.getField("full_name")
    .setFunction(["last_name", "first_name", "middle_names"], glue);

Output

---

Calculate field by custom function

Instead of passing an array of strings, representing the fieldnames, we can pass a custom function to the field.setFunction()-method:

// file: hooks/contacts-dv.js
var dv = AppGiniHelper.dv;

// calculate field "full_name"
// concat values of last_name, first_name, middle_names 
// readable version for beginners
dv.getField("full_name").setFunction(function (data) {
    var result = data.last_name;
    if (result && data.first_name) result += ", " + data.first_name;
    if (result && data.middle_names) result += ", " + data.middle_names;
    return result;
});

We can return a string containg the new value for the full_name-field.

Tips

Tip 1: Always check your variables

Please note the data parameter. You can check the values by printing out that variable:

This is the console-output:

Tip 2: Here is a different code returning similar results for more advanced Javascript users:

// using array, filter and join
dv.getField("full_name").setFunction(function (data) {
    var parts = [data.last_name, data.first_name, data.middle_names].filter(x => x);
    return parts.join(", ").trim();
});

Another example: Calculation function for identifier field

In this example I join Last Name, First Name, Middle Names (if exist) and Date of Birth (if exists), formatted as YYYY-MM-DD.

This means I cannot just take an existing value of Date of Birth but I have to convert the value at runtime, using a custom function.

This is the code behind. I have added comments for better understanding.

// file: hooks/contacts-dv.js
// get a handle to detail view
var dv = AppGiniHelper.dv;

dv.getField("identifier").setFunction(function (data) {
    // if day_of_birth is defined
    //      then use moment.js library for formatting date into YYYY-MM-DD
    let date_string = data.day_of_birth 
        ? new moment(data.day_of_birth).format("YYYY-MM-DD") 
        : null;

    // get values of last_name, first_name, middle_names and date_strint into an array
    var parts = [data.last_name, data.first_name, data.middle_names, date_string]
        .filter(x => x) /* filter out empty values */
        .map(function (part) { /* convert values to uppercase */
            return part.toUpperCase();
        });

    let result = parts.join("-"); /* glue parts together using "-" character */
    return result; /* return the new string */
});

See also

• Field Helpers