Creatio development guide
PDF
This documentation is valid for Creatio version 7.10.0. We recommend using the newest version of Creatio documentation.

How to add multi-currency field

Glossary Item Box

One of the common configuration tasks is adding a "multi-currency field" control element on a page. The multi-currency field enables users to enter monetary sums, specify currencies and exchange rates. If a user changes the currency of a multi-currency field, the amount in it will be automatically re-calculated according to the current exchange rate. Fig. 1 shows an example of a multi-currency field in the system interface.

Fig.1 — Multi-currency field

 

How to add a multi-currency field on an edit page

  1. Add 4 fields to the view model:
    • [Currency]
    • [Exchange rate]
    • [Amount]
    • [Amount in base currency]

    The object itself must contain only the [Amount] field. The rest of the fields can be virtual, unless the business task requires their values to be stored in the database.

  2. Specify 3 modules in the view model class declaration as dependencies:
    • MoneyModule,
    • MultiCurrencyEdit,
    • MultiCurrencyEditUtilities.
  3. Connect Terrasoft.MultiCurrencyEditUtilities mixin to the view model and initialize it in the overridden init method.
  4. Add a configuration object with the multi-currency field settings to the diff array of the edit page schema. In addition to common control element properties, the values property must contain:
    • primaryAmount – name of the column that contains the amount in the base currency
    • currency – name of the column that references the currency lookup
    • rate – name of the column that contains the currency exchange rate
    • generator – control element generator. Specify "MultiCurrencyEditViewGenerator.generate".
  5. Add recalculation logic. Apply the calculated field mechanism, as described in the How to add a computed field article.

Below is a multi-currency field implementation example.

Case description

Add a multi-currency [Amount] field to the project edit page.

Case implementation

1. Create replacing Project object and add [Currency], [Amount] and [PrimaryAmount] columns

For more information on creating replacing objects and adding columns, please refer to the "Adding a new field to the edit page" article.

Column properties are available on Fig. 2, 3 and 4,

Fig. 2. [Currency] column properties

Fig. 3. [Amount] column properties

Fig. 4. [PrimaryAmount] column properties

2. Create a replacing edit page for the [Projects] section in the custom package

Create a replacing client module and specify [ProjectPageV2] as the parent object (Fig. 5).

For more information on creating replacing pages, please refer to the "Creating a custom client module schema" article.

Fig. 5. Properties of the replacing project edit page

3. The [Currency rate] field must be declared directly in the attributes value of the edit page schema

"CurrencyRate": {
    dataValueType: Terrasoft.DataValueType.FLOAT, 
}

4. Specify the following modules as dependencies when declaring view model class:

  • MoneyModule,
  • MultiCurrencyEdit,
  • MultiCurrencyEditUtilities.
define("ProjectPageV2", ["MoneyModule", "MultiCurrencyEdit", "MultiCurrencyEditUtilities"],
    function(MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities) {

5. Connect the Terrasoft.MultiCurrencyEditUtilities mixin to the view model

mixins: {
    /**
    * Multi-currency management mixin in the record edit page.
    */
    MultiCurrencyEditUtilities: "Terrasoft.MultiCurrencyEditUtilities"
}

Additionally, initialize the mixin in the overridden init method:

// Overriding the Terrasoft.BasePageV2.init base method
init: function() {
    // Initializing the multi-currency management mixin.
    this.mixins.MultiCurrencyEditUtilities.init.call(this);
    // Calling parent implementation of the init method.
    this.callParent(arguments);
},

6. Add a configuration object with multi-currency field settings to the diff array

diff: /**SCHEMA_DIFF*/[
    {
        "operation": "insert",
        // Parent container name. 
        "parentName": "Header",
        "propertyName": "items",
        // Control element name.
        "name": "Amount",
        "values": {
            // View model column name in which the binding is done.
            "bindTo": "Amount",
            // Item location in container.
            "layout": {"column": 0, "row": 2, "colSpan": 12},
            // Name of the column, which contains amount in base currency.
            "primaryAmount": "PrimaryAmount",
            // Name of the column, which contains the currency of the amount. 
            "currency": "Currency",
            // Name of the column, which contains the currency rate.
            "rate": "CurrencyRate",
            // The property that determines if the base currency amount field is editable. 
            "primaryAmountEnabled": false,
            // Control element view generator.
            "generator": "MultiCurrencyEditViewGenerator.generate"
        }
    }
],/**SCHEMA_DIFF*/

7. Implement the amount recalculation logic

In the attributes property, add dependencies for the [CurrencyRate] and [Amount] attributes. Add handler methods for these dependencies to the methods collection.

Below is the complete source code of the edit page.

// Specify modules as dependencies in the view model class declaration
// MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities
define("ProjectPageV2", ["MoneyModule", "MultiCurrencyEdit", "MultiCurrencyEditUtilities"],
    function (MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities) {
        return {
            // Edit page object schema name.
            entitySchemaName: "Project",
            // The attributes property of the view model.
            attributes: {
                // View model column name.
                "CurrencyRate": {
                    // Data type of the view model column.
                    dataValueType: Terrasoft.DataValueType.FLOAT,
                    // Array of configuration objects that determine the dependencies of the [CurrencyRate] column.
                    dependencies: [
                        {
                            // The [CurrencyRate] column value depends on the [Currency] column value.
                            columns: ["Currency"],
                            // Handler method that is called when the value in the [Currency] column changes.
                            methodName: "setCurrencyRate"
                        }
                    ]
                },
                // View model column name.
                "Amount": {
                    // View model column data type.
                    dataValueType: Terrasoft.DataValueType.FLOAT,
                    // Array of configuration objects that determine dependencies of the [Amount] column.
                    dependencies: [
                        {
                            // Value in the [Amount] column.
                            columns: ["Amount"],
                            // Handler method, which is called when the value in the [Amount] column changes.
                            methodName: "recalculatePrimaryAmount"
                        }
                    ]
                }
            },
            // Collection of view model mixins.
            mixins: {
                // Multi-currency management mixin on the edit page.
                MultiCurrencyEditUtilities: "Terrasoft.MultiCurrencyEditUtilities"
            },
            // Collection of page view model methods.
            methods: {
                // Overriding base method Terrasoft.BasePageV2.init.
                init: function () {
                    // Initialize multi-currency management mixin.
                    this.mixins.MultiCurrencyEditUtilities.init.call(this);
                    // Calling parent implementation of the init method.
                    this.callParent(arguments);
                },
                // Handler method, which is called on changing the currency.
                setCurrencyRate: function () {
                    // Calling the LoadCurrencyRate function of the MoneyModule, which calculates 
                    // currency exchange rate. [Currency] and [CurrencyRate] are passed as parameters.
                    MoneyModule.LoadCurrencyRate.call(this, "Currency", "CurrencyRate", this.get("StartDate"),
                        function () {
                            var division = this.getCurrencyDivision();
                            MoneyModule.RecalcCurrencyValue.call(this, "CurrencyRate", "Amount", "PrimaryAmount",
                                division);
                        }
                    );
                },
                // Auxiliary method, which returns delimiting coefficient for a currency.
                getCurrencyDivision: function () {
                    var currency = this.get("Currency");
                    return currency && currency.Division;
                },
                // Handler method, which is called if the amount is modified and conducts recalculation of amount
                // in base currency.
                recalculatePrimaryAmount: function () {
                    // Determining the delimiting coefficient for the current currency.
                    var division = this.getCurrencyDivision();
                    // Calling the RecalcBaseValue function of the MoneyModule, which calculates
                    // amount for the [Amount in base currency] field. Column names for
                    // [CurrencyRate], [Amount], [PrimaryAmount], as well as delimiting coefficient are passed as parameters.
                    MoneyModule.RecalcBaseValue.call(this, "CurrencyRate", "Amount", "PrimaryAmount",
                        division);
                }
            },
            // Multi-currency field visualization setup.
            diff: /**SCHEMA_DIFF*/[
                // Metadata to add the [Amount] field.
                {
                    "operation": "insert",
                    // Parent container name. 
                    "parentName": "Header",
                    "propertyName": "items",
                    // Control element name.
                    "name": "Amount",
                    "values": {
                        // View model column name, to which the binding is made.
                        "bindTo": "Amount",
                        // Element position within container.
                        "layout": { "column": 0, "row": 2, "colSpan": 12 },
                        // Name of the column that contains amount in base currency.
                        "primaryAmount": "PrimaryAmount",
                        // Name of the column that contains the currency.
                        "currency": "Currency",
                        // Name of the column that contains exchange rate.
                        "rate": "CurrencyRate",
                        // Property that determines availability of the base currency amount field.
                        "primaryAmountEnabled": false,
                        // Control element view generator.
                        "generator": "MultiCurrencyEditViewGenerator.generate"
                    }
                }
            ],/**SCHEMA_DIFF*/
            details: /**SCHEMA_DETAILS*/{}/**SCHEMA_DETAILS*/
        };
    });

8. Save page replacing schema

After saving the schema and updating the web page, a new multi-currency edit field [Amount] will appear on the page (Fig. 6).

Fig. 6. Case results

 

© bpm'online 2002-2017.

Did you find this information useful?

How can we improve it?