Add a multicurrency field to a record page

Advanced

Example. Add an Amount multicurrency field to the project page.

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 "Project."
- Set Title to "Project."
- Select "Project" 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 Lookup in the drop-down menu.
3. Fill out the properties of the added column.
  - Set Code to "UsrCurrency."
  - Set Title to "Currency."
  - Set Lookup to "Currency."
  - Set up the Default value property.
    1. Click in the Default value field.
    2. Select "System setting" in the Default value type property.
    3. Select "Base currency" (PrimaryCurrency code) in the System setting property.
View the column properties in the figure below.

Add columns that contain the total amount, the amount in base currency, and the exchange rate similarly. View the column properties in the table below.

Properties of the columns to add

Data type)	Code	Title
Currency	"UsrAmount"	"Amount"
Currency	"UsrPrimaryAmount"	"Amount, base currency"
Decimal (0.0001)	"UsrCurrencyRate"	"Exchange rate"

Click Save then Publish on the Object Designer's toolbar.

2. Create a replacing view model schema of the project 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 "ProjectPageV2."
- Set Title to "Project edit page."
- Select "ProjectPageV2" in the Parent object property.
Add the MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities modules as dependencies to the declaration of the view model class.

Set up the layout of the multicurrency field.

Add the following attributes to the attributes property:
- UsrCurrency. The currency. Corresponds to the UsrCurrency column.
- UsrCurrencyRate. The exchange rate. Corresponds to the UsrCurrencyRate column.
- UsrAmount. Total amount. Corresponds to the UsrAmount column.
- UsrPrimaryAmount. The amount in base currency. Corresponds to the UsrPrimaryAmount column.
- Currency. The currency. Corresponds to the Currency column. The multicurrency module interacts with this column. Declare a virtual column in the Currency attribute and link the column to the UsrCurrency column using the handler method.
- CurrencyRateList. The collection of exchange rates. Required for the multicurrency module to operate as intended.
- CurrencyButtonMenuList. The collection for the currency selection button. Required for the multicurrency module to operate as intended.
Add the MultiCurrencyEditUtilities mixin to the mixins property.
Implement the following methods in the methods property:
- onEntityInitialized(). Overloads the base virtual method. Called after Creatio initializes the object schema of the record page.
- setCurrencyRate(). Sets the currency exchange rate.
- recalculateAmount(). Recalculates the total amount.
- recalculatePrimaryAmount(). Recalculates the amount in base currency.
- onVirtualCurrencyChange(). Handles the changes to the virtual currency column.
Add a configuration object with the settings that determine the layout of the multicurrency field to the diff array of modifications.

View the source code of the replacing view model schema of the project page below.

ProjectPageV2

/* Specify the MoneyModule, MultiCurrencyEdit, and MultiCurrencyEditUtilities modules as dependencies. */
define("ProjectPageV2", ["MoneyModule", "MultiCurrencyEdit", "MultiCurrencyEditUtilities"],
    function(MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities) {
        return {
            /* The name of the record page's object schema. */
            entitySchemaName: "Project",
            /* The attributes of the view model. */
            attributes: {
                /* The currency. */
                "UsrCurrency": {
                    /* The data type of the view model column. */
                    "dataValueType": this.Terrasoft.DataValueType.LOOKUP,
                    /* The configuration of the currency lookup. */
                    "lookupListConfig": {
                        "columns": ["Division", "Symbol"]
                    }
                },
                /* The exchange rate. */
                "UsrCurrencyRate": {
                    "dataValueType": this.Terrasoft.DataValueType.FLOAT,
                    /* The array of configuration objects that define the [UsrCurrencyRate] column dependencies. */
                    "dependencies": [
                        {
                            /* The [UsrCurrencyRate] column value depends on the [UsrCurrency] column value. */
                            "columns": ["UsrCurrency"],
                            /* The handler method. */
                            "methodName": "setCurrencyRate"
                        }
                    ]
                },
                /* The total amount. */
                "UsrAmount": {
                    "dataValueType": this.Terrasoft.DataValueType.FLOAT,
                    "dependencies": [
                        {
                            "columns": ["UsrCurrencyRate", "UsrCurrency"],
                            "methodName": "recalculateAmount"
                        }
                    ]
                },
                /* The amount in base currency. */
                "UsrPrimaryAmount": {
                    "dependencies": [
                        {
                            "columns": ["UsrAmount"],
                            "methodName": "recalculatePrimaryAmount"
                        }
                    ]
                },
                /* Currency is a virtual column for compatibility with the MultiCurrencyEditUtilities module. */
                "Currency": {
                    "type": this.Terrasoft.ViewModelColumnType.VIRTUAL_COLUMN,
                    "dataValueType": this.Terrasoft.DataValueType.LOOKUP,
                    "lookupListConfig": {
                        "columns": ["Division"]
                    },
                    "dependencies": [
                        {
                            "columns": ["Currency"],
                            "methodName": "onVirtualCurrencyChange"
                        }
                    ]
                },
                /* The collection of exchange rates. */
                "CurrencyRateList": {
                    dataValueType: this.Terrasoft.DataValueType.COLLECTION,
                    value: this.Ext.create("Terrasoft.Collection")
                },
                /* The collection for the currency selection button. */
                "CurrencyButtonMenuList": {
                    dataValueType: this.Terrasoft.DataValueType.COLLECTION,
                    value: this.Ext.create("Terrasoft.BaseViewModelCollection")
                }
            },
            /* The mixins of the view model. */
            mixins: {
                /* The mixin that manages multiple currencies on the record page. */
                MultiCurrencyEditUtilities: "Terrasoft.MultiCurrencyEditUtilities"
            },
            /* The methods of the record page's view model. */
            methods: {
                /* Overload the Terrasoft.BasePageV2.onEntityInitialized() base method. */
                onEntityInitialized: function() {
                    /* Call the parent implementation of the method. */
                    this.callParent(arguments);
                    this.set("Currency", this.get("UsrCurrency"), {silent: true});
                    /* Initialize the mixin that manages multiple currencies. */
                    this.mixins.MultiCurrencyEditUtilities.init.call(this);
                },
                /* Set the exchange rate. */
                setCurrencyRate: function() {
                    /* Load the exchange rate on the project start date. */
                    MoneyModule.LoadCurrencyRate.call(this, "UsrCurrency", "UsrCurrencyRate", this.get("StartDate"));
                },
                /* Recalculate the amount. */
                recalculateAmount: function() {
                    var currency = this.get("UsrCurrency");
                    var division = currency ? currency.Division : null;
                    MoneyModule.RecalcCurrencyValue.call(this, "UsrCurrencyRate", "UsrAmount", "UsrPrimaryAmount", division);
                },
                /* Recalculate the amount in base currency. */
                recalculatePrimaryAmount: function() {
                    var currency = this.get("UsrCurrency");
                    var division = currency ? currency.Division : null;
                    MoneyModule.RecalcBaseValue.call(this, "UsrCurrencyRate", "UsrAmount", "UsrPrimaryAmount", division);
                },
                /* The handler of changes to the virtual currency columns. */
                onVirtualCurrencyChange: function() {
                    var currency = this.get("Currency");
                    this.set("UsrCurrency", currency);
                }
            },
            /* Display the field on the record page. */
            diff: /**SCHEMA_DIFF*/[
                /* The metadata to add the multicurrency 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": "UsrAmount",
                    /* The properties to pass to the element's constructor. */
                    "values": {
                        /* Bind the value of the control to the view model column. */
                        "bindTo": "UsrAmount",
                        /* Set up the field layout. */
                        "layout": { 
                            /* The column number. */
                            "column": 0, 
                            /* The row number. */
                            "row": 2, 
                            /* The column span. */
                            "colSpan": 12 
                        },
                        /* The name of the column that contains the amount in base currency. */
                        "primaryAmount": "UsrPrimaryAmount",
                        /* The name of the column that contains the currency of the amount. */
                        "currency": "UsrCurrency",
                        /* The name of the column that contains the exchange rate. */
                        "rate": "UsrCurrencyRate",
                        /* The property that flags the field of the amount in the base currency as editable. */
                        "primaryAmountEnabled": false,
                        /* The view generator of the control. */
                        "generator": "MultiCurrencyEditViewGenerator.generate"
                    }
                }
            ]/**SCHEMA_DIFF*/
        };
    });

Click Save on the Designer's toolbar.

Outcome of the example

To view the outcome of the example, refresh the Projects section page.

As a result, Creatio will add an Amount multicurrency field.

Creatio recalculates the field value automatically after you select the currency in the drop-down list.

Resources

Package with example implementation