Version: 8.1

Add a calculated field to a record page

Level: intermediate

Example

Add a Payment balance calculated field to the order page. The field must display the difference between the order (the Total field) and payment (the Payment amount field) amounts.

1. Create a replacing object schema

Go to the Configuration section and select a custom package to add the schema.
Click Add → Replacing object on the section list toolbar.
Fill out the schema properties.
- Set Code to "Order."
- Set Title to "Order."
- Select "Order" in the Parent object property.
Add a column to the schema.
1. Click in the context menu of the object structure's Columns node.
2. Click Number → Currency in the drop-down list.
3. Fill out the properties of the added column.
  - Set Code to "UsrBalance."
  - Set Title to "Payment balance."
Click Save then Publish on the Object Designer's toolbar.

2. Create a replacing view model schema of the order page

Go to the Configuration section and select a custom package to add the schema.
Click Add → Replacing view model on the section list toolbar.
Fill out the schema properties.
- Set Code to "OrderPageV2."
- Set Title to "Order edit page."
- Select "OrderPageV2" in the Parent object property.

Set up the layout of the calculated field.

Add the calculateBalance() handler method and the UsrBalance attribute in the attributes property. The attribute must inherit from the Amount and PaymentAmount columns.
Implement the following methods in the methods property:
- calculateBalance(). Handles change events of the Amount and PaymentAmount columns. Required to calculate the value of the UsrBalance column specified in the UsrBalance attribute.
  
  Keep in mind the data type of the calculation results to display in the calculated field. For example, the Decimal (0.01) data type involves a number with 2 decimal places. In this case, convert the data type using the toFixed() function before you pass the outcome to the object field. View the source code of an example that converts the data type below.
  Example that converts the data type
```
/* Calculate the difference between the [Amount] and [PaymentAmount] column values. */
var result = amount - paymentAmount;
/* Assign the calculation results to the [UsrBalance] column. */
this.set("UsrBalance", result.toFixed(2));
```
- onEntityInitialized(). Overloads the base virtual method. Called after Creatio initializes the object schema of the record page. Call the calculateBalance() handler method in the onEntityInitialized() method. The handler method ensures the payment remainder is calculated not only when the dependency columns change but also when the record page opens.
Add a configuration object with the settings that determine the layout of the calculated field to the diff array of modifications.

View the source code of the order page's replacing view model below.

OrderPageV2
define("OrderPageV2", [], function() {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Order",
        details: /**SCHEMA_DETAILS*/{}/**SCHEMA_DETAILS*/,
        /* The view model attributes. */
        attributes: {
            /* The name of the view model attribute. */
            "UsrBalance": {
                /* The data type of the view model column. */
                dataValueType: Terrasoft.DataValueType.FLOAT,
                /* The array of configuration objects that define the [UsrBalance] column dependencies. */
                dependencies: [
                    {
                        /* The [UsrBalance] column value depends on the [Amount] and [PaymentAmount] column values. */
                        columns: ["Amount", "PaymentAmount"],
                        /* The handler method that is called when the [Amount] or [PaymentAmount] column value changes. */
                        methodName: "calculateBalance"
                    }
                ]
            }
        },
        /* The methods of the record page's view model. */
        methods: {
            /* Overload the base Terrasoft.BasePageV2.onEntityInitialized method that is called after Creatio initializes the schema of the record page object. */
            onEntityInitialized: function() {
                /* Call the parent implementation of the method. */
                this.callParent(arguments);
                /* Call the handler method that calculates the [UsrBalance] column value. */
                this.calculateBalance();
            },
            /* The handler method that calculates the [UsrBalance] column value. */
            calculateBalance: function() {
                /* Check whether Creatio initialized the [Amount] and [PaymentAmount] columns when the record page had opened. If not, set their values to 0. */
                var amount = this.get("Amount");
                if (!amount) {
                    amount = 0;
                }
                var paymentAmount = this.get("PaymentAmount");
                if (!paymentAmount) {
                    paymentAmount = 0;
                }
                /* Calculate the difference between the [Amount] and [PaymentAmount] column values. */
                var result = amount - paymentAmount;
                /* Assign the calculation results to the [UsrBalance] column. */
                this.set("UsrBalance", result);
            }
        },
        /* Display the field on the record page. */
        diff: /**SCHEMA_DIFF*/[
            /* The properties to add the calculated field to the record page. */
            {
                /* Add the element to the page. */
                "operation": "insert",
                /* The meta name of the parent container to add the field. */
                "parentName": "Header",
                /* Add the field to the parent element's collection of elements. */
                "propertyName": "items",
                /* The meta name of the field to add. */
                "name": "UsrBalance",
                /* The properties to pass to the element's constructor. */
                "values": {
                    /* Bind the value of the control to the view model column. */
                    "bindTo": "UsrBalance",
                    /* Set up the field layout. */
                    "layout": {
                        /* The column number. */
                        "column": 12, 
                        /* The row number. */
                        "row": 2, 
                        /* The column span. */
                        "colSpan": 12
                    }
                }
            }
        ]/**SCHEMA_DIFF*/
    };
});

Click Save on the Designer's toolbar.

Outcome of the example

To view the outcome of the example:

Clear the browser cache.
Refresh the Orders section page.

As a result, Creatio will add the Payment balance calculated field to the order page. The field value is the difference between the order (the Total field) and payment (the Payment amount field) amounts.

Resources

Package with example implementation

1. Create a replacing object schema​

2. Create a replacing view model schema of the order page​

Outcome of the example​

Resources​

1. Create a replacing object schema

2. Create a replacing view model schema of the order page

Outcome of the example

Resources