Field

Guide
Medium

Types of fields and field operations 

Creatio provides the following field types:

  • simple field
  • image field
  • calculated field
  • multicurrency field

Creatio lets you execute the following field operations:

  • implement the field validation
  • set the default field value
  • set up the field requirement
  • set up value filtering for a lookup field
  • set up the field locking conditions
  • set up the field locking exceptions
  • set up the field display conditions
  • add automatic field numbering
  • add an info button to the field
  • add a tooltip to the field
  • calculate the date difference between the fields

Add a field 

You can add a field using the following tools:

  • Section Wizard
  • Creatio IDE

Add a simple field 

You can add a simple field in the following ways:

  • use an existing column
  • use a new column

Add a simple field in the Section Wizard 

To add a simple field in the Section Wizard, follow the instructions in the user documentation article: Set up page fields.

Add a simple field in Creatio IDE 

To add a simple field in Creatio IDE using an existing column:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Set up the field layout in the replacing view model schema. To do this, add a configuration object with the settings that determine the field layout to the diff array of modifications.

You can add a simple field in Creatio IDE using a new column in the following ways:

  • Create a replacing object schema and add a column to it.
  • Create a replacing view model schema of the record page that contains the field. Then create an attribute in the view model schema and add a field to the created virtual column.

This article covers one of the ways below.

To add a simple field in Creatio IDE using a new column:

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add a column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  4. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.
  5. Set up the field position in the replacing view model schema. To do this, add a configuration object with the settings that determine the field layout to the diff array of modifications.

Add an image field 

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add an Image Link type column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  4. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.
  5. Add an image to the schema image collection.

  6. Set up the image field in the replacing view model schema.

    1. Implement the following methods in the methods property:

      • the method that receives the image by link
      • the method that is called before the image selection box opens
      • the method that is called upon the image change
      • the method that saves the link to the changed image in the object column

    2. Add a configuration object with the settings that determine the field layout to the diff array of modifications. Use the auxiliary PhotoContainer wrapper container that has the "image-edit-container" class to add an image field to the page. Implement the following properties in the values property of the diff array of modifications:

      • getPhotoSrcMethod(). Receives the image by link.
      • onPhotoChange. Called upon the image change.
      • beforePhotoFileSelected(). Called before the image selection box opens.
      • readonly. Defines whether the image is modifiable.
      • generator. The control generator. Specify ImageCustomGeneratorV2.generateCustomImageControl for the image field.

Add a calculated field 

A calculated field is a record page control whose value is calculated based on the status and values of other controls of the page.

In Creatio, calculated fields operate based on subscriptions to attribute change events of the page view model schema. When the column values of the object schema change, the current column value changes.

To add a calculated field to the record page:

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add a column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  4. Set up the calculated field in the replacing view model schema.

    1. Add a calculated column (attribute) for which to set dependencies to the attributes property. Declare the dependencies property for the attribute. The property contains the array of configuration objects. The dependencies property includes the following properties:

      • columns. An array of column names. The current column value depends on the values of listed columns.
      • methodName. The name of the handler method that is called when the value of at least one of the listed columns changes.

    2. Implement the following in the methods property:

      • The handler method of the column change event. The calculated column depends on the changed column.
      • onEntityInitialized(). An overrided base virtual method. Called after Creatio initializes the object schema of the record page. Call the handler method in the onEntityInitialized() method. The handler method ensures the field is calculated not only when the dependency columns change but also when the record page opens.
    3. Add a configuration object with the settings that determine the field layout to the diff array of modifications.

Add a multicurrency field 

A multicurrency field is a record page control whose value is calculated based on the status or values of other controls of the page.

Multicurrency field lets you:

  • Enter a monetary amount.
  • Specify the currency of the monetary amount.
  • Record the equivalent of the amount in the base currency specified in Creatio settings.

When the currency changes, Creatio automatically converts the amount based on the currency exchange rates.

To add a multicurrency field to the record page:

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Add the following columns to the replacing object schema:

    • a Lookup type column that stores the currency
    • an exchange rate column
    • a column that stores the total amount in the selected currency
    • a column that stores the amount in base currency

    You can only define a single column in the object schema. The defined column must store the total amount in the selected currency. The rest of the columns can be virtual unless the business task requires their values to be stored in the database. You can define the columns as attributes in the view model schema.

    To do this, follow the guide in a separate article: Develop configuration elements.

  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  4. Add the MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities modules as dependencies to the declaration of the view model class.

  5. Set up the multicurrency field in the replacing view model schema.

    1. Add the following attributes to the attributes property:

      • currency
      • exchange rate
      • total amount
      • amount in base currency
      • exchange rate collection
      • collection for the currency selection button

      Declare the dependencies property for the attributes. The property contains an array of configuration objects. The dependencies property includes the following properties:

      • columns. An array of columns whose values determine the value of the current column.
      • methodName. The name of the handler method that is called when the value of at least one of the listed columns changes.
    2. Add the MultiCurrencyEditUtilities mixin to the mixins property.

    3. Implement the following methods in the methods property:

      • onEntityInitialized(). Overrides 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.

    4. Add a configuration object with the settings that determine the field layout to the diff array of modifications. Implement the following properties in the values property of the diff array of modifications:

      • primaryAmount. The name of the column that contains the amount in base currency.
      • currency. The name of the column that references the currency lookup.
      • rate. The name of the column that contains the exchange rate.
      • generator. The control generator. Specify MultiCurrencyEditViewGenerator.generate for the multicurrency field.

Implement the field validation 

Creatio performs validation by checking whether the filled out fields conform to the specified requirements. Page fields are validated at the column level of the page view models. The custom validator method executes the field validation logic.

To implement the field validation:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add a localizable string that contains the validation message to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.

  3. Set up the field validation in the replacing view model schema.

    To do this, implement the following methods in the methods property:

    • The validator method that checks whether the condition is true. Validator is a view model method that matches the value of the view model column to the business requirements. The method must return the object that contains the validation results.

      • If the field validation is successful, the validator method returns an object that contains an empty string.
      • If the field validation is unsuccessful, the validator method returns an object that contains the invalidMessage property. The invalidMessage property contains a message string displayed below the field when a user attempts to enter an invalid value and in the message box when a user attempts to save a page with the field that did not pass the validation.

    • setValidationConfig() is an overrided base method that binds the validator method to the corresponding column of the record page’s replacing view model schema. The setValidationConfig() method calls the addColumnValidator() method. The addColumnValidator() method has the following parameters:

      • the name of the view model column to bind the validator
      • the name of the method that validates the column value

      If you implement the field validation in the replacing view model schema of the base page, call the parent implementation of the setValidationConfig() method before calling the addColumnValidator() method to ensure the validators of the base page fields are initialized correctly.

Set the default field value 

Creatio lets you set the default field value in the following ways:

  • at the level of business object columns in the replacing object schema

    When you create a new object, some page fields must be populated with the corresponding values. In this case, specify the values of the corresponding object columns as default values in the Object Designer.

  • in the source code of the replacing view model schema of the record page

    In some cases, you cannot set a default value via the object column properties. For example, the values might be calculated based on the values of other object columns. In this case, you can only set a default field value via coding.

View the record page’s default field value types set at the level of business object columns in the replacing object schema in the table below.

Default value types
Default value type
Description
Constant

You can set a constant default value for the following column types:

  • String.
  • Number.
  • Lookup.
  • Boolean.
System setting The System settings section contains system settings. You can add a custom system setting to the section. The system setting value is set at the user level, not the application level.
System variable System variables are global variables that store data about Creatio settings. The system variable value is set at the application core level, not the user level.

To set the default field value:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Set up the default field value in the replacing view model schema.

    To do this, implement the following methods in the methods property:

    • onEntityInitialized(). An overrided base virtual method. Called after Creatio initializes the object schema. Call the handler method in the onEntityInitialized() method. The handler method ensures the field value is set when a record page opens.
    • The handler method that calculates the field value.

Make the field required 

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add the BusinessRuleModule and ConfigurationConstants modules as dependencies to the declaration of the view model class.

  3. Make the field required in the replacing view model schema.

    To do this, take the following steps in the rules property:

    • Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
    • Set the property property to REQUIRED. The value marks the column as required. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
    • Specify the execution conditions of the business rule in the conditions array.

Set up the filtering of lookup field values 

Creatio lets you set up the filtering of lookup field values in the following ways:

  • use the FILTRATION business rule
  • specify the filters explicitly in the attributes property of the column description

To set up the filtering of lookup field values using the FILTRATION business rule:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  3. Set up the filtering of lookup field values in the replacing view model schema.

    1. Take the following steps in the rules property:

      • Set the ruleType property to FILTRATION. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the autocomplete property to true. The value performs inverse filtering.
    2. Add a configuration object with the settings that determine the field layout to the diff array of modifications.

Set up the filtering of lookup field values by specifying the filters explicitly in the column description to apply arbitrary filtering, sorting, and to add extra columns to the query when displaying the drop-down list.

To set up the filtering of lookup field values by specifying the filters explicitly in the column description:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  3. Set up the filtering of lookup field values in the replacing view model schema.

    To do this, take the following steps in the attributes property:

    • Set the dataValueType property to LOOKUP. The value sets the column data type. The Terrasoft.core.enums.DataValueType enumeration represents the column data types.

    • Specify the configuration object of the lookup field in the lookupListConfig property.

      The lookupListConfig property has the following optional properties:

      • columns. An array of column names added to the query besides the Id column and the primary column for display.
      • orders. An array of configuration objects that determine the order of displayed data.

      • The property that sets the filtering:

        • filter. The method that returns the object of the Terrasoft.BaseFilter class or its inheritor. Creatio applies the returned object to the query.
        • filters. The array of methods that return the collection of the Terrasoft.FilterGroup class.

Add the filters to the collection using the add() method. View the parameters of the add() method in the table below.

Parameters of the add() method
Parameter
Data type
Description
key String Key.
item Mixed

Element.

The object of the Terrasoft.BaseFilter class or its inheritor serves as the item parameter. Learn more about setting up filters in a separate article: Data-operations (front-end).

By default, the AND operator combines the filters in the collection. If you need to use the OR operator, specify it explicitly in the logicalOperation property of the Terrasoft.FilterGroup object.
index Number The index to insert. If the index is not specified, it is not rated.

Lock the field based on specific conditions 

Creatio can lock every field and detail of the record page simultaneously if the corresponding conditions are met. This lets you avoid creating a large number of business rules.

You can lock the fields of the following detail types:

  • list detail
  • editable list detail
  • field detail

To lock the field based on specific conditions:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  3. Set up the conditions that lock the field in the replacing view model schema.

    1. Enable locking in the attributes property using the IsModelItemsEnabled attribute.

      You can enable field locking in the following ways.

      • Set the IsModelItemsEnabled attribute to false.
      • Set the IsModelItemsEnabled attribute to the default value.
      • Use the IsEnabled attribute for a field detail.
      this.set("IsModelItemsEnabled", false);

      "IsModelItemsEnabled": {
    dataValueType: Terrasoft.DataValueType.BOOLEAN,
    value: true,
    dependencies: [{
        columns: ["PaymentStatus"],
        methodName: "setCardLockoutStatus"
    }]
}

    2. Take the following steps in the rules property:

      • Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the property property to ENABLED. The value sets the column availability. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
      • Specify the execution conditions of the business rule in the conditions array.

    3. Add a configuration object to the diff array of modifications:

      • Specify the CardContentWrapper global container in the name property to lock all record page fields.
      • Specify the DisableControlsGenerator generator in the generator property of the values property for containers whose fields to lock.
      Example setup of the diff array of modifications
      diff: /**SCHEMA_DIFF*/[
    {
        "operation": "merge",
        "name": "CardContentWrapper",
        "values": {
            "generator": "DisableControlsGenerator.generatePartial"
        }
    }
]/**SCHEMA_DIFF*/

Creatio locks detail buttons and menu items that launch detail operations. However, you can still open the object page of an editable list detail. The fields of the object page are locked based on the business rules.

Creatio does not lock the field if it is bound to the enabled property in the diff array of modifications or business rule.

Keep the field unlocked 

Creatio lets you keep certain fields and details unlocked.

To specify the field to keep unlocked:

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Specify the field to keep unlocked in the replacing view model schema.

    1. Enable locking in the attributes property using the IsModelItemsEnabled attribute.

    2. Implement the methods that return the list of fields and details to keep unlocked in the methods property:

      • getDisableExclusionsColumnTags(). Keeps a column unlocked.
      • getDisableExclusionsDetailSchemaNames(). Keeps a detail unlocked.
      • isModelItemEnabled(). Keeps a column unlocked. Complex exception logic. The method is called for each field. Accepts the name and returns the field availability flag.
      • isDetailEnabled(). Keeps a detail unlocked. Complex exception logic. The method is called for each detail. Accepts the name and returns the detail availability flag.
      getDisableExclusionsColumnTags: function() {
    return ["SomeField"];
}
getDisableExclusionsDetailSchemaNames: function() {
    return ["SomeDetailV2"]
}

      isModelItemEnabled: function(fieldName) {
    var condition = this.get("SomeConditionAttribute");
    if (fieldName === "ExampleField" || condition)) {
        return true;
    }
    return this.callParent(arguments);
}

isDetailEnabled: function(detailName) {   
    if (detailName === "ExampleDetail") {
        var exampleDate = this.get("Date");
        var dateNow = new Date(this.Ext.Date.now());
        var condition = this.Ext.Date.isDate(exampleDate) && exampleDate >= dateNow;
        return condition;
    }
    return this.callParent(arguments);
}
    3. Add a configuration object to the diff array of modifications. The object must contain the settings of the CardContentWrapper container that locks the fields.

To disable field locking, use the corresponding toggle of the CompleteCardLockout item on the Feature toggle page. Learn more about the Feature toggle page in a separate article: Feature toggle mechanism.

Set up the field display conditions 

  1. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add a column that corresponds to the page field of the replacing view model schema to the replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  3. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  4. Set up the field display conditions in the replacing view model schema.

    1. Take the following steps in the rules property:

      • Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the property property to VISIBLE. The value sets the column visibility. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
      • Specify the execution conditions of the business rule in the conditions array.
    2. Add a configuration object with the settings that determine the field layout to the diff array of modifications.

Enable automatic field numbering 

Automatic field numbering generates a record number automatically based on the specified template. Automatic numbering is implemented in the Documents, Invoices, and Contracts sections.

You can enable automatic field numbering in several ways:

  • in the front-end
  • in the back-end

Enable automatic field numbering in the front-end 

  1. Create the following system settings:

    • [Entity]CodeMask. The object number mask.
    • [Entity]LastNumber. The current object number.

    Entity. The name of the object to whose column to apply automatic numbering. For example, InvoiceCodeMask is the invoice number mask and InvoiceLastNumber is the current invoice number.

  2. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  3. Set up automatic field numbering in the front-end in the replacing view model schema.

    To do this, implement the onEntityInitialized() overrided base virtual method in the methods property. Called after Creatio initializes the object schema. Call the getIncrementCode() handler method of the BasePageV2 base record page schema in the onEntityInitialized() method. The handler method assigns a generated number to the Code field.

    The getIncrementCode() method includes the following parameters:

    • callback. The function that is called after receiving the service response. Pass the response to the corresponding column (attribute).
    • scope. The scope to call the callback function (optional).

Enable automatic field numbering in the back-end 

  1. Create the following system settings:

    • [Entity]CodeMask. The object number mask.
    • [Entity]LastNumber. The current object number.

    Entity. The name of the object to whose column to apply automatic numbering. For example, InvoiceCodeMask is the invoice number mask and InvoiceLastNumber is the current invoice number.

  2. Create a replacing object schema. To do this, follow the guide in a separate article: Develop configuration elements.
  3. Add a Before record added event to the replacing object schema.
  4. Implement the event subprocess in the business process.

Add an info button to the field 

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.

  3. Attach an info button to the field in the replacing view model schema.

    To do this, attach a configuration object with the settings that determine the info button layout to the page field in the diff array of modifications. Implement the itemType property in the values property of the diff array of modifications. Set the implemented property to Terrasoft.ViewItemType.INFORMATION_BUTTON.

Add a tooltip to a field 

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.
  2. Add a localizable string that contains the field name to the replacing view model schema (optional). To do this, follow the guide in a separate article: Operations with localizable resources.

  3. Attach an info button to the field in the replacing view model schema.

    To do this, attach a configuration object with the settings that determine the tooltip layout to the page field in the diff array of modifications. Set up the tooltip in the tip property of the diff array of modifications.

Calculate the date difference between the fields 

  1. Create a replacing view model schema of the record page that contains the field. To do this, follow the guide in a separate article: Develop configuration elements.

  2. Calculate the date difference between the fields in the replacing view model schema.

    To do this, implement the following methods in the methods property:

    • onEntityInitialized(). Overrides the base virtual method. Called after Creatio initializes the object schema of the record page.
    • setEndDate(). The auxiliary method that sets the date. Call the getDate() method in the setEndDate() method. The called method retrieves the date.
See also
Set up page fields
Develop configuration elements
Operations with localizable resources
Data-operations (front-end)
Feature Toggle mechanism
Add a field to a record page using a new column
Medium

Example. Add a Meeting place field to the activity page. Before you add the field, add a corresponding column to the activity object schema.

1. Create a replacing object schema 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing object on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "Activity."
    • Set Title to "Activity."
    • Select "Activity" in the Parent object property.

  4. Add a column to the schema.

    1. Click add_button in the context menu of the object structure's Columns node.

    2. Click Text → Text (250 characters) in the drop-down menu.

    3. Fill out the properties of the added column.

      • Set Code to "UsrMeetingPlace."
      • Set Title to "Meeting place."
  5. Click Save then Publish on the Object Designer's toolbar.

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

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ActivityPageV2."
    • Set Title to "Activity edit page."
    • Select "ActivityPageV2" in the Parent object property.

  4. Add a localizable string.

    1. Click the scr_add_button.png button in the context menu of the Localizable strings node.

    2. Fill out the localizable string properties.

      • Set Code to "MeetingPlaceCaption."
      • Set Value to "Meeting place."
    3. Click Add to add a localizable string.

  5. Set up the field layout. To do this, add a configuration object with the settings that determine the field layout to the diff array of modifications.

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

    ActivityPageV2
    define("ActivityPageV2", [], function() {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Activity",
        /* Display the field on the record page. */
        diff: /**SCHEMA_DIFF*/[
            /* The metadata to add the custom field to the 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": "UsrMeetingPlace",
                /* The properties to pass to the element's constructor. */
                "values": {
                    /* Bind the field caption to the localizable schema string. */
                    "caption": {"bindTo": "Resources.Strings.MeetingPlaceCaption"},
                    /* Set up the field layout. */
                    "layout": {
                        /* The column number. */
                        "column": 0,
                        /* The column span. */
                        "row": 5,
                        /* The column span. */
                        "colSpan": 12
                    }
                }
            }
        ]/**SCHEMA_DIFF*/
    };
});
  6. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Clear the browser cache.
  2. Refresh the Activities section page.

As a result, Creatio will add a Meeting place field to the page.

Resources
Package with example implementation
Add a field to a record page using an existing column
Medium

Example. Add a Country field to the contact profile on the contact page. The contact object schema already includes the column that corresponds to the Country field of the contact page.

Create a replacing view model schema of the contact page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ContactPageV2."
    • Set Title to "Display schema - Contact card."
    • Select "ContactPageV2" in the Parent object property.

  4. Set up the field layout. To do this, add a configuration object with the settings that determine the field layout to the diff array of modifications.

    View the source code of the replacement view model of the contact page below.

    ContactPageV2
    define("ContactPageV2", [], function() {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Contact",
        /* Display the field on the record page. */
        diff: [
            /* Metadata to add a [Country] field to the page. */
            {
                /* Add the element to the page. */
                "operation": "insert",
                /* The meta name of the parent container to add the field. */
                "parentName": "ProfileContainer",
                /* Add the field to the element collection of the parent element. */
                "propertyName": "items",
                /* The meta name of the field to add. */
                "name": "Country",
                /* The properties to pass to the element's constructor. */
                "values": {
                    /* Set the field type to lookup. */
                    "contentType": Terrasoft.ContentType.LOOKUP,
                    /* Set up the field layout. */
                    "layout": {
                        /* The column number. */
                        "column": 0,
                        /* The row number. */
                        "row": 6,
                        /* The column span. */
                        "colSpan": 24
                    }
                }
            }
        ]
    };
});
  5. Click Save on the Designer's toolbar.

Outcome of the example 

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

As a result, Creatio will add a Country field to the contact profile on the contact page.

Resources
Package with example implementation
Add an image field to a record page
Advanced

Example. Add an image field to the page of the knowledge base article. Use the image provided below.

1. Create a replacing object schema 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing object on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "KnowledgeBase."
    • Set Title to "Knowledge base article."
    • Select "KnowledgeBase" in the Parent object property.

  4. Add a column to the schema.

    1. Click add_button in the context menu of the object structure's Columns node.

    2. Click Other → Image Link in the drop-down menu.

    3. Fill out the properties of the added column.

      • Set Code to "UsrLogo."
      • Set Title to "Knowledge base article logo."
  5. Click Save then Publish on the Object Designer's toolbar.

2. Create a replacing view model schema of the page of the knowledge base article 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "KnowledgeBasePageV2."
    • Set Title to "Knowledge base edit page."
    • Select "KnowledgeBasePageV2" in the Parent object property.

  4. Add an image.

    1. Click the scr_add_button.png button in the context menu of the Images node.

    2. Fill out the image properties.

      • Set Code to "DefaultLogo."
      • Specify the image field in the Image property.
    3. Click Add to add the image.
  5. Add the KnowledgeBasePageV2Resources and ConfigurationConstants modules as dependencies to the declaration of the view model class.

  6. Set up the image field layout.

    Place the image field at the top of the page of the knowledge base article. If you add an image field, the layout of base page fields can break. To avoid this, change the layout of existing fields at the top of the page besides placing the image field there. These are Name, Type, Modified By fields.

    1. Implement the following methods in the methods property:

      • getPhotoSrcMethod(). Receives the image by link
      • beforePhotoFileSelected(). Called before the image selection box opens.
      • onPhotoChange. Called upon the image change.
      • onPhotoUploaded(). Saves the link to the changed image in the object column
    2. Add a configuration object with the settings that determine the layout of the image field and existing page fields to the diff array of modifications. Use the auxiliary PhotoContainer wrapper container that has the "image-edit-container" class to add an image field to the page.

    View the source code of the replacing view model schema of the page of the knowledge base article below.

    KnowledgeBasePageV2
    define("KnowledgeBasePageV2", ["KnowledgeBasePageV2Resources", "ConfigurationConstants"], function(resources, ConfigurationConstants) {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "KnowledgeBase",
        /* The methods of the section page's view model. */
        methods: {
            /* Call before the image selection box opens. */
            beforePhotoFileSelected: function() {
                return true;
            },
            /* Receive the image by link. */
            getPhotoSrcMethod: function() {
                /* Receive the image link from the object column. */
                var imageColumnValue = this.get("UsrLogo");
                /* If the link is specified, return the image file URL. */
                if (imageColumnValue) {
                    return this.getSchemaImageUrl(imageColumnValue);
                }
                /* If the link is not specified, return the default image. */
                return this.Terrasoft.ImageUrlBuilder.getUrl(this.get("Resources.Images.DefaultLogo"));
            },
            /* Handle the image change. 
			photo is the image file. */
            onPhotoChange: function(photo) {
                if (!photo) {
                    this.set("UsrLogo", null);
                    return;
                }
                /* Upload the file to the database. Call onPhotoUploaded once the upload finishes. */
                this.Terrasoft.ImageApi.upload({
                    file: photo,
                    onComplete: this.onPhotoUploaded,
                    onError: this.Terrasoft.emptyFn,
                    scope: this
                });
            },
            /* Save the link to the changed image. 
			imageId is the ID of the file saved in the database. */
            onPhotoUploaded: function(imageId) {
                var imageData = {
                    value: imageId,
                    displayValue: "Image"
                };
                /* Assign the image link to the image column. */
                this.set("UsrLogo", imageData);
            }
        },
        /* Display the field on the section page. */
        diff: /**SCHEMA_DIFF*/[
            /* The metadata to add the custom image 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 image to the parent element's collection of elements. */
                "propertyName": "items",
                /* The meta name of the image to add. */
                "name": "PhotoContainer",
                /* The properties to pass to the element's constructor. */
                "values": {
                    /* Set the type of the added element to "container." */
                    "itemType": Terrasoft.ViewItemType.CONTAINER,
                    /* The name of the CSS class. */
                    "wrapClass": ["image-edit-container"],
                    /* Set up the image layout. */
                    "layout": { 
                        /* The column number. */
                        "column": 0, 
                        /* The row number. */
                        "row": 0, 
                        /* The row span. */
                        "rowSpan": 3, 
                        /* The column span. */
                        "colSpan": 3 
                    },
                    /* The array of nested elements. */
                    "items": []
                }
            },
            /* The [UsrLogo] field contains the account logo. */
            {
                "operation": "insert",
                "parentName": "PhotoContainer",
                "propertyName": "items",
                "name": "UsrLogo",
                "values": {
                    /* The method that retrieves the image by link. */
                    "getSrcMethod": "getPhotoSrcMethod",
                    /* The method that is called upon the image change. */
                    "onPhotoChange": "onPhotoChange",
                    /* The method that is called before the image selection box opens. */
                    "beforeFileSelected": "beforePhotoFileSelected",
                    /* The property that flags the image as editable. */
                    "readonly": false,
                    /* The view generator of the control. */
                    "generator": "ImageCustomGeneratorV2.generateCustomImageControl"
                }
            },
            /* Change the layout of the [Name] field. */
            {
                /* Execute the operation that modifies the existing element. */
                "operation": "merge",
                "name": "Name",
                "parentName": "Header",
                "propertyName": "items",
                "values": {
                    "bindTo": "Name",
                    "layout": {
                        "column": 3,
                        "row": 0,
                        "colSpan": 20
                    }
                }
            },
            /* Change the layout of the [ModifiedBy] field. */
            {
                "operation": "merge",
                "name": "ModifiedBy",
                "parentName": "Header",
                "propertyName": "items",
                "values": {
                    "bindTo": "ModifiedBy",
                    "layout": {
                        "column": 3,
                        "row": 2,
                        "colSpan": 20
                    }
                }
            },
            /* Change the layout of the [Type] field. */
            {
                "operation": "merge",
                "name": "Type",
                "parentName": "Header",
                "propertyName": "items",
                "values": {
                    "bindTo": "Type",
                    "layout": {
                        "column": 3,
                        "row": 1,
                        "colSpan": 20
                    },
                    "contentType": Terrasoft.ContentType.ENUM
                }
            }
        ]/**SCHEMA_DIFF*/
    };
});
  7. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example, refresh the Knowledge base section page.

As a result, Creatio will add an image field to the page of the knowledge base article. You can change or delete the image.

Resources
Package with example implementation
Add a calculated field to a record page
Medium

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 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing object on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "Order."
    • Set Title to "Order."
    • Select "Order" in the Parent object property.

  4. Add a column to the schema.

    1. Click add_button 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."
  5. Click Save then Publish on the Object Designer's toolbar.

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

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "OrderPageV2."
    • Set Title to "Order edit page."
    • Select "OrderPageV2" in the Parent object property.

  4. Set up the layout of the calculated field.

    1. Add the calculateBalance() handler method and the UsrBalance attribute in the attributes property. The attribute must inherit from the Amount and PaymentAmount columns.

    2. 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.
    3. 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 metadata 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*/
    };
});
  5. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Clear the browser cache.
  2. 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
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 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing object on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "Project."
    • Set Title to "Project."
    • Select "Project" in the Parent object property.

  4. Add a column to the schema.

    1. Click add_button 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 scr_edit_button.png 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.

  5. 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"
  6. Click Save then Publish on the Object Designer's toolbar.

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

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ProjectPageV2."
    • Set Title to "Project edit page."
    • Select "ProjectPageV2" in the Parent object property.
  4. Add the MoneyModule, MultiCurrencyEdit, MultiCurrencyEditUtilities modules as dependencies to the declaration of the view model class.

  5. Set up the layout of the multicurrency field.

    1. 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.
    2. Add the MultiCurrencyEditUtilities mixin to the mixins property.

    3. 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.
    4. 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*/
        };
    });
  6. 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
Implement the validation of a [Date/Time] type field on a record page
Medium

Example. Validate the Created on field of the Date/Time type on the opportunity page. The date value of the Created on field must be earlier than the Closed on date.

Create a replacing view model schema of the opportunity page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "OpportunityPageV2."
    • Set Title to "Opportunity edit page."
    • Select "OpportunityPageV2" in the Parent object property.

  4. Add a localizable string.

    1. Click the scr_add_button.png button in the context menu of the Localizable strings node.

    2. Fill out the localizable string properties.

      • Set Code to "CreatedOnLessDueDateMessage."
      • Set Value to "Created on must be less than Closed on."
    3. Click Add to add a localizable string.

  5. Implement validation of the Date/Time type field.

    To do this, implement the following methods in the methods property:

    • dueDateValidator(). The validator method that checks whether the condition is true.
    • setValidationConfig(). The overloaded base method that binds the validator method to the DueDate and CreatedOn columns.

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

    OpportunityPageV2
    define("OpportunityPageV2", [], function() {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Opportunity",
        /* The methods of the section page's view model. */
        methods: {
            /* The method that validates the [DueDate] and [CreatedOn] column values. */
            dueDateValidator: function() {
                /* The variable that stores the validation error message. */
                var invalidMessage = "";
                /* Check the [DueDate] and [CreatedOn] column values. */
                if (this.get("DueDate") < this.get("CreatedOn")) {
                    /* If the [DueDate] column value is earlier than the [CreatedOn] column value, put the localizable string that contains the validation error message in the invalidMessage variable. */
                    invalidMessage = this.get("Resources.Strings.CreatedOnLessDueDateMessage");
                }
                /* The object whose property contains the validation error message. If the validation is successful, the object returns an empty string. */
                return {
                    /* The validation error message. */
                    invalidMessage: invalidMessage
                };
            },
            /* Overload the base method that initalizes the custom validators. */
            setValidationConfig: function() {
                /* Call the initialization of the parent view model's validators. */
                this.callParent(arguments);
                /* Add the dueDateValidator() validator method for the [DueDate] column. */
                this.addColumnValidator("DueDate", this.dueDateValidator);
                /* Add the dueDateValidator() validator method for the [CreatedOn] column. */
                this.addColumnValidator("CreatedOn", this.dueDateValidator);
            }
        }
    };
});
  6. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Refresh the Opportunities section page.
  2. Enter the date earlier than the Created on field value in the Closed on field.

As a result, Creatio will display the corresponding warning on the opportunity page.

If you try to save an opportunity where the date value of the Closed on field is earlier than the Created on date, a message box will open.

Resources
Package with example implementation
Implement the validation of a [String] type field on a record page
Medium

Example. Validate the Business phone field of the String type on the contact page. The value of the Business phone field must match the +44 XXX XXX XXXX pattern.

Create a replacing view model schema of the contact page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ContactPageV2."
    • Set Title to "Display schema - Contact card."
    • Select "ContactPageV2" in the Parent object property.

  4. Add a localizable string.

    1. Click the scr_add_button.png button in the context menu of the Localizable strings node.

    2. Fill out the localizable string properties.

      • Set Code to "InvalidPhoneFormatMessage."
      • Set Value to "Enter the number in format +44 XXX XXX XXXX.
    3. Click Add to add a localizable string.
  5. Add the ConfigurationConstants module as a dependency to the declaration of the view model class.

  6. Implement the validation of the String type field.

    To do this, implement the following methods in the methods property:

    • phoneValidator(). The validator method that checks whether the condition is true.
    • setValidationConfig(). The overloaded base method that binds the validator method to the Phone column.

    View the source code of the replacement view model of the contact page below.

    ContactPageV2
    define("ContactPageV2", ["ConfigurationConstants"], function(ConfigurationConstants) {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Contact",
        /* The methods of the record page's view model. */
        methods: {
            /* Overload the base method that initializes the custom validators. */
            setValidationConfig: function() {
                /* Initialize the validators of the parent view model. */
                this.callParent(arguments);
                /* Add the phoneValidator() method for the [Phone] column. */
                this.addColumnValidator("Phone", this.phoneValidator);
            },
            /* The method that validates the [Phone] column value. */
            phoneValidator: function(value) {
                /* The variable that stores the validation error message. */
                var invalidMessage = "";
                /* The variable that stores the number validation results. */
                var isValid = true;
                /* The variable that stores the phone number. */
                var number = value || this.get("Phone");
                /* Check whether the number format is valid using the regular expression. */
                isValid = (Ext.isEmpty(number) ||
                    new RegExp("^\\+44\\s[0-9]{3}\\s[0-9]{3}\\s[0-9]{4}$").test(number));
                /* If the number format is invalid, populate the error message. */
                if (!isValid) {
                    invalidMessage = this.get("Resources.Strings.InvalidPhoneFormatMessage");
                }
                /* The object whose property contains the validation error message. If the validation is successful, the object returns an empty string. */
                return {
                    invalidMessage: invalidMessage
                };
            }
        }
    };
});
  7. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Refresh the Contacts section page.
  2. Enter a phone number that does not match the +44 XXX XXX XXXX pattern in the Business phone field.

As a result, Creatio will display the corresponding warning on the contact page.

If you try to save a contact whose phone number does not match the +44 XXX XXX XXXX pattern, a message box will open.

Resources
Package with example implementation
Set the default value for a field on a record page
Medium

Example. Specify the default value for the Deadline field on the page that adds a project. The Deadline field value must be 10 days greater than the Start field value.

Create a replacing view model schema of the project page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ProjectPageV2."
    • Set Title to "Project edit page."
    • Select "ProjectPageV2" in the Parent object property.

  4. Set up the field population logic.

    To do this, implement the following methods in the methods property:

    • onEntityInitialized(). An overloaded base virtual method. Called after Creatio initializes the object schema. Call the setDeadline() handler method in the onEntityInitialized() method. The handler method ensures the Deadline field value is set when a record page opens.
    • setDeadline(). The handler method that calculates the Deadline field value.

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

    ProjectPageV2
    define("ProjectPageV2", [], function() {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Project",
        /* 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 [Deadline] column value. */
                this.setDeadline();
            },
            /* The handler method that calculates the [Deadline] column value. */
            setDeadline: function() {
                /* The [Deadline] column value. */
                var deadline = this.get("Deadline");
                /* Checks whether the mode of the new record is set. */
                var newmode = this.isNewMode();
                /* If the value is not set and the mode of the new record is set. */
                if (!deadline && newmode) {
                    /* Retrieve the [StartDate] column value. */
                    var newDate = new Date(this.get("StartDate"));
                    newDate.setDate(newDate.getDate() + 10);
                    /* Set the [Deadline] column value. */
                    this.set("Deadline", newDate);
                }
            }
        }
    };
});
  5. 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 set the date value of the Deadline field that is 10 days later than the Start date on the page that adds a project.

Resources
Package with example implementation
Make the field on a record page required
Medium

Example. Make the Business phone field on the contact page required. The field must be required for the "Customer" type contacts, i. e., the contacts with "Customer" specified in the Type field.

Create a replacing view model schema of the contact page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ContactPageV2."
    • Set Title to "Display schema - Contact card."
    • Select "ContactPageV2" in the Parent object property.
  4. Add the BusinessRuleModule and ConfigurationConstants modules as dependencies to the declaration of the view model class.

  5. Make the field required.

    To do this, set the rules property for the Phone column:

    1. Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
    2. Set the property property to REQUIRED. The value marks the column as required. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
    3. Specify the execution conditions of the business rule in the conditions array. The Type column value must match the ConfigurationConstants.ContactType.Client configuration constant that includes the ID of the "Customer" record of the Contact types lookup.

    View the source code of the replacement view model of the contact page below.

    ContactPageV2
    /* Specify the BusinessRuleModule and ConfigurationConstants modules as dependencies. */
define("ContactPageV2", ["BusinessRuleModule", "ConfigurationConstants"],
    function(BusinessRuleModule, ConfigurationConstants) {
        return {
            /* The name of the record page object's schema. */
            entitySchemaName: "Contact",
            /* The business rules of the record page's view model. */
            rules: {
                /* The set of rules for the [Phone] column of the view model. */
                "Phone": {
                    /* The requirement of the [Phone] field depends on the [Type] field value. */
                    "BindParameterRequiredAccountByType": {
                        /* The BINDPARAMETER rule type. */
                        "ruleType": BusinessRuleModule.enums.RuleType.BINDPARAMETER,
                        /* The rule controls the REQUIRED property. */
                        "property": BusinessRuleModule.enums.Property.REQUIRED,
                        /* The array of conditions that trigger the rule. Checks whether the [Type] column value is "Customer." */
                        "conditions": [{
                            /* The left side expression of the condition. */
                            "leftExpression": {
                                /* The expression type is attribute (column) of the view model. */
                                "type": BusinessRuleModule.enums.ValueType.ATTRIBUTE,
                                /* The name of the view model column whose value to compare in the expression. */
                                "attribute": "Type"
                            },
                            /* Set the comparison operation type to equal. */
                            "comparisonType": Terrasoft.ComparisonType.EQUAL,
                            /* The right side expression of the condition. */
                            "rightExpression": {
                                /* Set the expression type to constant. */
                                "type": BusinessRuleModule.enums.ValueType.CONSTANT,
                                /* The value to compare to the left side expression. */
                                "value": ConfigurationConstants.ContactType.Client
                            }
                        }]
                    }
                }
            }
        };
    });
  6. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Refresh the Contacts section page.
  2. Select "Customer" in the Type field of the contact page if needed.

As a result, Creatio will make the Business phone field required for the "Customer" type contacts.

If you try to save a "Customer" type contact whose Business phone field is empty, a message box will open.

The Business phone field is optional for other contact types. For example, "Employee."

Resources
Package with example implementation
Set up filtering of lookup field values on a record page
Medium

Example. Set up filtering for contacts that can be selected after you fill out the Owner lookup field of the account page. Display the following in the contact selection box:

  • contacts linked to Creatio users
  • active contacts

Create a replacing view model schema of the account page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "AccountPageV2."
    • Set Title to "Account edit page."
    • Select "AccountPageV2" in the Parent object property.

  4. Implement the filtering of lookup field values.

    To do this, set the attributes property for the Owner column:

    • Set the dataValueType property to LOOKUP. The value sets the column data type. The Terrasoft.core.enums.DataValueType enumeration represents the column data types.
    • Specify the configuration object of the lookup field in the lookupListConfig property.
    • Specify the function that returns the filter collection in the filters array.

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

    AccountPageV2
    define("AccountPageV2", [], function() {
    return {
        /* The name of the record page object's schema. */
        "entitySchemaName": "Account",
        /* The attributes of the view model. */
        "attributes": {
            /* The name of the view model column. */
            "Owner": {
                /* The data type of the view model column. */
                "dataValueType": Terrasoft.DataValueType.LOOKUP,
                /* The configuration object of the LOOKUP type attribute. */
                "lookupListConfig": {
                    /* The array of filters to apply to the query that populates the lookup field with data. */
                    "filters": [
                        function() {
                            var filterGroup = Ext.create("Terrasoft.FilterGroup");
                            /* Add the "IsUser" filter to the resulting filter collection.
                            Select all records with non-null [Id] from the [Contact] root schema to which the [Id] column from the [SysAdminUnit] schema is joined. */
                            filterGroup.add("IsUser", Terrasoft.createColumnIsNotNullFilter("[SysAdminUnit:Contact].Id"));
                            /* Add the "IsActive" filter to the resulting filter collection.
                            Select all records for which Active=true from the [Contact] root schema to which the [Active] column from the [SysAdminUnit] schema is joined. */
                            filterGroup.add("IsActive",
                                Terrasoft.createColumnFilterWithParameter(
                                    Terrasoft.ComparisonType.EQUAL,
                                    "[SysAdminUnit:Contact].Active",
                                    true));
                            return filterGroup;
                        }
                    ]
                }
            }
        }
    };
});
  5. Click Save on the Designer's toolbar.

Outcome of the example 

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

As a result, Creatio will filter contacts on the account page when you fill out the Owner lookup field.

For example, you cannot select the Andrew Z. Barber contact in the Owner lookup field on the account page because the contact is inactive.

You cannot select the Sheldon Mallen contact in the Owner lookup field on the account page because the contact is not linked to a Creatio user.

Resources
Package with example implementation
Set up filtering of bound lookup field values on a record page
Medium

Example. Set up filtering of Country, State/province, City fields on the contact page. The index of selectable states/provinces must depend on the country selected in the Country field. The index of selectable cities must depend on the state/province selected in the State/province field.

Create a replacing view model schema of the contact page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ContactPageV2."
    • Set Title to "Display schema - Contact card."
    • Select "ContactPageV2" in the Parent object property.
  4. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  5. Implement the value filtering for connected lookup fields.

    1. Take the following steps in the rules property for the City and Region columns:

      • Set the ruleType property to FILTRATION. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the autocomplete property to true. The property performs inverse filtering, i. e., populates the Country and State/province fields automatically depending on the selected city.

    2. Add the configuration object with the layout settings of the Country, State/province, City fields to the diff array of modifications.

      The base schema of the contact page has a rule for filtering cities by the country specified for the contact. To enable users to select a city from a country not specified for the contact, add a Country field.

    View the source code of the replacement view model of the contact page below.

    ContactPageV2
    /* Specify the BusinessRuleModule module as a dependency. */
define("ContactPageV2", ["BusinessRuleModule"],
    function(BusinessRuleModule) {
        return {
            /* The name of the record page object's schema. */
            entitySchemaName: "Contact",
            /* The business rules of the record page's view model. */
            rules: {
                /* The set of rules for the [City] column of the view model. */
                "City": {
                    /* The filtering rule by the [Region] column value for the [City] column. */
                    "FiltrationCityByRegion": {
                        /* The FILTRATION rule type. */
                        "ruleType": BusinessRuleModule.enums.RuleType.FILTRATION,
                        /* Perform the inverse filtering. */
                        "autocomplete": true,
                        /* Clean the value when the [Region] column value changes. */
                        "autoClean": true,
                        /* The path to the filtering column in the [City] lookup schema referenced in the [City] column of the record page's view model. */
                        "baseAttributePatch": "Region",
                        /* The comparison operation type in the filter. */
                        "comparisonType": Terrasoft.ComparisonType.EQUAL,
                        /* Set the expression type to attribute (column) of the view model. */
                        "type": BusinessRuleModule.enums.ValueType.ATTRIBUTE,
                        /* The name of the view model column whose value to compare in the expression. */
                        "attribute": "Region"
                    }
                },
                /* The set of rules for the [Region] column of the view model. */
                "Region": {
                    "FiltrationRegionByCountry": {
                        "ruleType": BusinessRuleModule.enums.RuleType.FILTRATION,
                        "autocomplete": true,
                        "autoClean": true,
                        "baseAttributePatch": "Country",
                        "comparisonType": Terrasoft.ComparisonType.EQUAL,
                        "type": BusinessRuleModule.enums.ValueType.ATTRIBUTE,
                        "attribute": "Country"
                    }
                }
            },
            /* Display the fields on the record page. */
            diff: [
                /* The metadata to add a [Country] 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": "ProfileContainer",
                    /* Add the field to the parent element's collection of elements. */
                    "propertyName": "items",
                    /* The meta name of the field to add. */
                    "name": "Country",
                    /* The properties to pass to the element's constructor. */
                    "values": {
                        /* Set the field type to lookup. */
                        "contentType": Terrasoft.ContentType.LOOKUP,
                        /* Set up the field layout. */
                        "layout": {
                            /* The column number. */
                            "column": 0,
                            /* The row number. */
                            "row": 6,
                            /* The column span. */
                            "colSpan": 24
                        }
                    }
                },
                /* The metadata to add a [Region] field to the record page. */
                {
                    "operation": "insert",
                    "parentName": "ProfileContainer",
                    "propertyName": "items",
                    "name": "Region",
                    "values": {
                        "contentType": Terrasoft.ContentType.LOOKUP,
                        "layout": {
                            "column": 0,
                            "row": 7,
                            "colSpan": 24
                        }
                    }
                },
                /* The metadata to add a [City] field to the record page. */
                {
                    "operation": "insert",
                    "parentName": "ProfileContainer",
                    "propertyName": "items",
                    "name": "City",
                    "values": {
                        "contentType": Terrasoft.ContentType.LOOKUP,
                        "layout": {
                            "column": 0,
                            "row": 8,
                            "colSpan": 24
                        }
                    }
                }
            ]
        };
    });
  6. Click Save on the Designer's toolbar.

Outcome of the example 

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

As a result, Creatio will add the Country, State/province, City connected lookup fields to the contact profile on the contact page.

You can change the contact country in the contact profile.

Creatio also filters the country selection box.

The index of selectable states/provinces depends on the country selected in the Country field. Creatio filters both the input field and state/province selection box.

The index of selectable cities depends on the state/province selected in the State/province field. Creatio filters both the input field and city selection box.

Resources
Package with example implementation
Set up the conditions that lock a field on a record page
Medium

Example. Set up the conditions that lock the Business phone field on the contact page. Lock the field if the Mobile phone field is empty.

Create a replacing view model schema of the contact page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ContactPageV2."
    • Set Title to "Display schema - Contact card."
    • Select "ContactPageV2" in the Parent object property.
  4. Add the BusinessRuleModule module as a dependency to the declaration of the view model class.

  5. Set up the conditions that lock the field.

    1. Take the following steps in the rules property for the Phone column:

      • Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      • Set the property property to ENABLED. The value sets the column availability. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
      • Specify the execution conditions of the business rule in the conditions array. The MobilePhone column value cannot be empty.

    View the source code of the replacement view model of the contact page below.

    ContactPageV2
    /* Specify the BusinessRuleModule module as a dependency. */
define("ContactPageV2", ["BusinessRuleModule"], function(BusinessRuleModule) {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Contact",
        /* The business rules of the record page's view model. */
        rules: {
            /* The set of rules for the [Phone] column of the view model. */
            "Phone": {
                /* The requirement of the [Phone] field depends on the [MobilePhone] field value. */
                "BindParameterEnabledPhoneByMobile": {
                    /* The BINDPARAMETER rule type. */
                    "ruleType": BusinessRuleModule.enums.RuleType.BINDPARAMETER,
                    /* The rule controls the ENABLED property. */
                    "property": BusinessRuleModule.enums.Property.ENABLED,
                    /* The array of conditions that trigger the rule. Check whether the [MobilePhone] column contains a value. */
                    "conditions": [{
                        /* The left side expression of the condition. */
                        "leftExpression": {
                            /* The expression type is attribute (column) of the view model. */
                            "type": BusinessRuleModule.enums.ValueType.ATTRIBUTE,
                            /* The name of the view model column whose value to compare in the expression. */
                            "attribute": "MobilePhone"
                        },
                        /* Set the comparison operation type to not equal. */
                        "comparisonType": Terrasoft.ComparisonType.NOT_EQUAL,
                        /* The right side expression of the condition. */
                        "rightExpression": {
                            /* Set the expression type to a constant value. */
                            "type": BusinessRuleModule.enums.ValueType.CONSTANT,
                            /* The value to compare to the left side expression. */
                            "value": ""
                        }
                    }]
                }
            }
        }
    };
});
  6. Click Save on the Designer's toolbar.

Outcome of the example 

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

As a result, Creatio will lock the Business phone field on the contact page if the Mobile phone field is empty.

Resources
Package with example implementation
Keep fields on a record page unlocked
Medium

Example. Set up the conditions that lock the fields on the invoice page. Lock the fields of completely paid invoices, i. e., invoices that have "Paid" selected in the Payment status field. Keep the Payment status field and Activities detail unlocked.

Create a replacing view model schema of the invoice page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "InvoicePageV2."
    • Set Title to "Invoice edit page."
    • Select "InvoicePageV2" in the Parent object property.
  4. Add the InvoiceConfigurationConstants module as a dependency to the declaration of the view model class.

  5. Set up the conditions that lock fields and keep fields unlocked.

    1. Add the IsModelItemsEnabled attribute to the attributes property. The attribute includes the mechanism that locks the fields.

    2. Implement the following methods in the methods property:

      • getDisableExclusionsColumnTags(). Keeps the column unlocked.
      • getDisableExclusionsDetailSchemaNames(). Keeps the detail unlocked.
      • setCardLockoutStatus(). Sets up the conditions that lock fields.
      • onEntityInitialized(). Overloads the base virtual method. Called after Creatio initializes the object schema of the record page.
    3. Add a configuration object to the diff array of modifications. The object must contain the settings of the CardContentWrapper container that locks the fields.

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

    InvoicePageV2
    /* Specify the InvoiceConfigurationConstants module as a dependency. */
define("InvoicePageV2", ["InvoiceConfigurationConstants"], function(InvoiceConfigurationConstants) {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Invoice",
        /* The attributes of the view model. */
        attributes: {
            "IsModelItemsEnabled": {
                /* The data type of the view model column. */
                dataValueType: Terrasoft.DataValueType.BOOLEAN,
                value: true,
                /* The array of configuration objects that define the [IsModelItemsEnabled] attribute dependencies. */
                dependencies: [{
                    /* The [IsModelItemsEnabled] column value depends on the [PaymentStatus] column value. */
                    columns: ["PaymentStatus"],
                    /* The handler method. */
                    methodName: "setCardLockoutStatus"
                }]
            }
        },
        /* The methods of the record page's view model. */
        methods: {
            /* Keep the [PaymentStatus] column unlocked. */
            getDisableExclusionsColumnTags: function() {
                return ["PaymentStatus"];
            },
            /* Keep the [ActivityDetailV2] detail unlocked. */
            getDisableExclusionsDetailSchemaNames: function() {
                return ["ActivityDetailV2"];
            },
            /* Set up the conditions that lock the fields. */
            setCardLockoutStatus: function() {
                var state = this.get("PaymentStatus");
                if (state.value === InvoiceConfigurationConstants.Invoice.PaymentStatus.Paid) {
                    this.set("IsModelItemsEnabled", false);
                } else {
                    this.set("IsModelItemsEnabled", true);
                }
            },
            /* Overload the Terrasoft.BasePageV2.onEntityInitialized() base method. */
            onEntityInitialized: function() {
                /* Call the parent implementation of the method. */
                this.callParent(arguments);
                this.setCardLockoutStatus();
            }
        },
        details: /**SCHEMA_DETAILS*/{}/**SCHEMA_DETAILS*/,
        /* Display the locking container on the record page. */
        diff: /**SCHEMA_DIFF*/[
            {
                /* Execute the operation that modifies the existing element. */
                "operation": "merge",
                /* The meta name of the parent container to lock the fields. */
                "name": "CardContentWrapper",
                /* The properties to pass to the element's constructor. */
                "values": {
                    /* The view generator of the control. */
                    "generator": "DisableControlsGenerator.generatePartial"
                }
            }
        ]/**SCHEMA_DIFF*/
    };
});
  6. Click Save on the Designer's toolbar.

Outcome of the example 

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

As a result, Creatio will lock most fields on the page of the invoice that has "Paid" selected in the Payment status field. The following remain unlocked:

  • the Payment status field
  • the Activities detail
  • the fields that have the enabled property of the diff array of modifications set to true
Resources
Package with example implementation
Set up the display conditions of a field on a record page
Medium

Example. Set up the display conditions of the Meeting place field on the activity page. Creatio must display the field for activities with the "Meeting" category, i. e., the activities that have "Meeting" selected in the Category field.

1. Create a replacing object schema 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing object on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "Activity."
    • Set Title to "Activity."
    • Select "Activity" in the Parent object property.

  4. Add a column to the schema.

    1. Click add_button in the context menu of the object structure's Columns node.

    2. Click Text → Text (250 characters) in the drop-down menu.

    3. Fill out the properties of the added column.

      • Set Code to "UsrMeetingPlace."
      • Set Title to "Meeting place."
  5. Click Save then Publish on the Object Designer's toolbar.

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

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ActivityPageV2."
    • Set Title to "Activity edit page."
    • Select "ActivityPageV2" in the Parent object property.

  4. Add a localizable string.

    1. Click the scr_add_button.png button in the context menu of the Localizable strings node.

    2. Fill out the localizable string properties.

      • Set Code to "MeetingPlaceCaption."
      • Set Value to "Meeting place."
    3. Click Add to add a localizable string.
  5. Add the BusinessRuleModule and ConfigurationConstants modules as dependencies to the declaration of the view model class.

  6. Set up the field display conditions.

    1. Take the following steps in the rules property for the UsrMeetingPlace column:

      1. Set the ruleType property to BINDPARAMETER. The value sets the business rule type. The BusinessRuleModule.enums.RuleType enumeration represents the rule types.
      2. Set the property property to VISIBLE. The value sets the column visibility. The BusinessRuleModule.enums.Property enumeration represents the properties of the BINDPARAMETER business rule.
      3. Specify the execution conditions of the business rule in the conditions array. The ActivityCategory column value must match the ConfigurationConstants.Activity.ActivityCategory.Meeting configuration constant that includes the ID of the "Meeting" record of the Activity types lookup.
    2. Add a configuration object with the settings that determine the layout of the Meeting place field to the diff array of modifications.

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

    ActivityPageV2
    /* Specify the BusinessRuleModule and ConfigurationConstants modules as dependencies. */
define("ActivityPageV2", ["BusinessRuleModule", "ConfigurationConstants"],
    function(BusinessRuleModule, ConfigurationConstants) {
        return {
            /* The name of the record page object's schema. */
            entitySchemaName: "Activity",
            /* Display the field on the record page. */
            diff: /**SCHEMA_DIFF*/[
            /* The metadata to add a [UsrMeetingPlace] 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": "UsrMeetingPlace",
                    /* The properties to pass to the element's constructor. */
                    "values": {
                        /* Bind the field caption to the localizable schema string. */
                        "caption": {"bindTo": "Resources.Strings.MeetingPlaceCaption"},
                        /* Set up the field layout. */
                        "layout": { 
                            /* The column number. */
                            "column": 0, 
                            /* The row number. */
                            "row": 5, 
                            /* The column span. */
                            "colSpan": 12 
                        }
                    }
                }
            ]/**SCHEMA_DIFF*/,
            /* The business rules of the record page's view model. */
            rules: {
                /* The set of rules for the [UsrMeetingPlace] column of the view model. */
                "UsrMeetingPlace": {
                    /* The visibility of the [UsrMeetingPlace] field depends on the [ActivityCategory] field value. */
                    "BindParametrVisibilePlaceByType": {
                        /* The BINDPARAMETER rule type. */
                        "ruleType": BusinessRuleModule.enums.RuleType.BINDPARAMETER,
                        /* The rule that controls the VISIBLE property. */
                        "property": BusinessRuleModule.enums.Property.VISIBLE,
                        /* The array of conditions that trigger the rule. Check whether the [ActivityCategory] column value is "Meeting." */
                        "conditions": [{
                            /* The left side expression of the condition. */
                            "leftExpression": {
                                /* The expression type is attribute (column) of the view model. */
                                "type": BusinessRuleModule.enums.ValueType.ATTRIBUTE,
                                /* The name of the view model column whose value to compare in the expression. */
                                "attribute": "ActivityCategory"
                            },
                            /* Set the comparison operation type to equal. */
                            "comparisonType": Terrasoft.ComparisonType.EQUAL,
                            /* The right side expression of the condition. */
                            "rightExpression": {
                                /* Set the expression type to constant. */
                                "type": BusinessRuleModule.enums.ValueType.CONSTANT,
                                /* The value to compare to the left side expression. */
                                "value": ConfigurationConstants.Activity.ActivityCategory.Meeting
                            }
                        }]
                    }
                }
            }
        };
    });
  7. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Refresh the Activities section page.
  2. Select "Meeting" in the Category field of the activity page if needed.

As a result, Creatio will display the Meeting place field for activities that have the "Meeting" category.

Creatio will not display the Meeting place field for other activity categories. For example, "To do."

Resources
Package with example implementation
Enable the automatic numbering of a field on a page that adds records (front-end)
Advanced

Example. Enable the automatic numbering of the Code field on the page that adds a product. Use the following numbering pattern: ART_0000N, where N is 1, 2, etc. Implement the automatic numbering in the front-end.

1. Create system settings 

  1. Create a system setting that contains the product code pattern.

    1. Click to open the System Designer.
    2. Go to the System setup block → System settings.
    3. Click Add setting on the section toolbar.

    4. Fill out the properties of the system setting.

      • Set Name to "Product code mask."
      • Set Code to "ProductCodeMask."
      • Select "Unlimited length text" in the Type property.
      • Set Default value to "ART_{0:00000}."

  2. Create a system setting that contains the current product code.

    1. Click to open the System Designer.
    2. Go to the System setup block → System settings.
    3. Click Add setting on the section toolbar.

    4. Fill out the properties of the system setting.

      • Set Name to "Product last number."
      • Set Code to "ProductLastNumber."
      • Select "Integer" in the Type property.

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

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ProductPageV2."
    • Set Title to "Edit page - Product.".
    • Select "ProductPageV2" in the Parent object property.

  4. Implement the automatic field numbering.

    To do this, implement the onEntityInitialized() overloaded base virtual method in the methods property. Called after Creatio initializes the object schema. Call the getIncrementCode() handler method in the onEntityInitialized() method. The handler method assigns the generated number to the Code field.

    View the source code of the replacement view model of the product page below.

    ProductPageV2
    define("ProductPageV2", [], function() {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Product",
        /* 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);
                /* Generate the code if a new element or a copy of an existing element is created. */
                if (this.isAddMode() || this.isCopyMode()) {
                    /* Call the Terrasoft.BasePageV2.getIncrementCode base method that generates the number based on the specified pattern. */
                    this.getIncrementCode(function(response) {
                        /* Return the generated number to the [Code] column. */
                        this.set("Code", response);
                    });
                }
            }
        }
    };
});
  5. Click Save on the Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Clear the browser cache.
  2. Refresh the Products section page.

As a result, Creatio will enable the automatic numbering of the Code field on the page that adds a product.

Resources
Package with example implementation
Enable the automatic numbering of a field on a page that adds records (back-end)
Advanced

Example. Enable the automatic numbering of the Code field on the page that adds a product. Use the following numbering pattern: ART_0000N, where N is 1, 2, etc. Implement the automatic numbering in the back-end.

1. Create system settings 

  1. Create a system setting that contains the product code pattern.

    1. Click to open the System Designer.
    2. Go to the System setup block → System settings.
    3. Click Add setting on the section toolbar.

    4. Fill out the properties of the system setting.

      • Set Name to "Product code mask."
      • Set Code to "ProductCodeMask."
      • Select "Unlimited length text" in the Type property.
      • Set Default value to "ART_{0:00000}."

  2. Create a system setting that contains the current product code.

    1. Click to open the System Designer.
    2. Go to the System setup block → System settings.
    3. Click Add setting on the section toolbar.

    4. Fill out the properties of the system setting.

      • Set Name to "Product last number."
      • Set Code to "ProductLastNumber."
      • Select "Integer" in the Type property.

2. Create a replacing object schema 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing object on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "Product."
    • Set Title to "Product."
    • Select "Product" in the Parent object property.

  4. Add an event to the schema.

    1. Open the Events node of the object structure.

    2. Go to the Adding block → select the Before record added checkbox. Creatio names the event ProductInserting.

    3. Click Save on the Object Designer's toolbar.

  5. Implement an event sub-process.

    1. Click Open process on the Object Designer's toolbar.

    2. Click System actions in the element area of the Designer and drag the Event sub-process element to the working area of the Process Designer.

    3. Set the Title property in the element setup area to "Product Inserting Sub-process."

    4. Set up the event sub-process elements.

      1. Set up the Message start event.

        • Set Title to "Before product adding."
        • Set Which message event should start the process? to "ProductInserting."

      2. Add the Exclusive gateway (OR) gateway .

        To do this, select Exclusive gateway (OR) in the menu of the Message start event.

      3. Add the Script task system action.

        1. Click System actions in the element area of the Designer and drag the Script task system action to the working area of the sub-process.

        2. Name the Script task system action "Get entity schema to generate number."

        3. Add the code of the Script task system action.

          Code of the Script task system action
          /* Set the schema that generates the number. */
UserTask1.EntitySchema = Entity.Schema;
return true;

          UserTask1 is the code of the Generate number system action of the User task type. The element setup procedure is covered on the next step. You can edit the code in the advanced setup mode of the User task system action.

        4. Click Save on the Process Designer's toolbar.

      4. Add the User task system action.

        1. Click System actions in the element area of the Designer and drag the User task action to the working area of the sub-process.

        2. Specify the properties of the system action.

          • Set Title to "Generate number."
          • Select "Generate ordinal number" in the Which user task to perform? property. The system action generates the current ordinal number based on the pattern specified in the ProductCodeMask system setting.

      5. Add the Script task system action.

        1. Click System actions in the element area of the Designer and drag the Script task system action to the working area of the sub-process.

        2. Name the Script task system action "Save number to entity column."

        3. Add the code of the Script task system action.

          Code of the Script task system action
          Entity.SetColumnValue("Code", UserTask1.ResultCode);
return true;
        4. Click Save on the Process Designer's toolbar.

      6. Add the Terminate event.

        To do this, click Terminate in the element area of the Designer and drag the event to the working area of the sub-process.

    5. Set up the flows.

      1. Set up the conditional flow between the Exclusive gateway (OR) gateway and Get entity schema to generate number system action.

        1. Click in the menu of the Exclusive gateway (OR) gateway and connect the Exclusive gateway (OR) gateway to the Get entity schema to generate number system action.

        2. Fill out the conditional flow properties.

          • Set Title to "Code is empty."

          • Set up the Condition to move down the flow property.

            1. Click on the element setup area next in the Condition to move down the flow property.

            2. Specify the formula.

              string.IsNullOrEmpty(Entity.GetTypedColumnValue<string>("Code"))
            3. Save the changes.

      2. Set up the default flow between the Exclusive gateway (OR) gateway and Terminate event.

        1. Click in the menu of the Exclusive gateway (OR) gateway and connect the Exclusive gateway (OR) gateway to the Terminate event.

        2. Convert the sequence flow into a default flow. To do this, click in the flow menu → Default flow.

      3. Set up the sequence flows.

        1. Click in the menu of the Get entity schema to generate number system action and connect the Get entity schema to generate number system action to the Generate number system action.
        2. Click in the menu of the Generate number system action and connect the Generate number system action to the Save number to entity column system action.

    View the event sub-process in the figure below

  6. Click Save then Publish on the Process Designer's toolbar.

Outcome of the example 

To view the outcome of the example:

  1. Clear the browser cache.
  2. Refresh the Products section page.
  3. Add and save a new product. For example, Test product.

Creatio generates the code automatically and saves it to the column server-side when the Before Record Saved event is triggered. The event is triggered server-side when the query to add a record is sent from the front-end. As such, Creatio cannot display the code on the page that adds a product immediately. The number will be displayed when you save the product.

As a result, Creatio will enable the automatic numbering of the Code field on the product page.

Resources
Package with example implementation
Attach an info button to a field on a record page
Medium

Example. Attach an info button to the Full name field of the contact profile on the contact page. Add a tooltip to the info button.

Create a replacing view model schema of the contact page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ContactPageV2."
    • Set Title to "Display schema - Contact card."
    • Select "ContactPageV2" in the Parent object property.

  4. Add a localizable string.

    1. Click the scr_add_button.png button in the context menu of the Localizable strings node.

    2. Fill out the localizable string properties.

      • Set Code to "InfoButtonCaption."
      • Set Value to "This is obligatory field."
    3. Click Add to add a localizable string.

  5. Implement the info button.

    To do this, attach a configuration object with the settings that determine the info button position to the page field in the diff array of modifications.

    View the source code of the replacement view model of the contact page below.

    ContactPageV2
    define("ContactPageV2", [], function () {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Contact",
        /* Display the info button next to the record page field. */
        diff: /**SCHEMA_DIFF*/[
            /* The metadata to add the text of the info button. */
            {
                /* Execute the operation that modifies the existing element. */
                "operation": "merge",
                /* The meta name of the parent container to add the info button. */
                "parentName": "ProfileContainer",
                /* Add the info button to the element collection of the parent element. */
                "propertyName": "items",
                /* The meta name of the field to change. */
                "name": "AccountName",
                /* The properties to pass to the element's constructor. */
                "values": {
                    /* Set up the info button layout. */
                    "layout": { 
                        /* The column number. */
                        "column": 0, 
                        /* The row number. */
                        "row": 1, 
                        /* The column span. */
                        "colSpan": 22, 
                        /* The row span. */
                        "rowSpan": 1 
                    }
                }
            },
            {
                /* Add the element to the page. */
                "operation": "insert",
                "parentName": "ProfileContainer",
                "propertyName": "items",
                "name": "SimpleInfoButton",
                "values": {
                    "layout": { 
                        "column": 22, 
                        "row": 1, 
                        "colSpan": 1, 
                        "rowSpan": 1 
                    },
                    /* Set the type of the added element to the information button. */
                    "itemType": Terrasoft.ViewItemType.INFORMATION_BUTTON,
                    /* The tooltip text. */
                    "content": { "bindTo": "Resources.Strings.InfoButtonCaption" }
                }
            }
        ]/**SCHEMA_DIFF*/
    };
});
  6. Click Save on the Designer's toolbar.

Outcome of the example 

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

As a result, Creatio will attach an info button to the Full name field of the contact profile on the contact page.

Resources
Package with example implementation
Add a tooltip to a field on a record page
Medium

Example. Add a tooltip to the Type field of the contact page.

Create a replacing view model schema of the contact page 

  1. Go to the Configuration section and select a custom package to add the schema.

  2. Click Add → Replacing view model on the section list toolbar.

  3. Fill out the schema properties.

    • Set Code to "ContactPageV2."
    • Set Title to "Display schema - Contact card."
    • Select "ContactPageV2" in the Parent object property.

  4. Add a localizable string that contains the tooltip text.

    1. Click the scr_add_button.png button in the context menu of the Localizable strings node.

    2. Fill out the localizable string properties.

      • Set Code to "TypeFieldHint."
      • Set Value to "Choose the type of the contact from the list. <a href="https://academy.creatio.com/docs/user/platform_basics/user_interface/record_pages_shortcut/record_pages" target="_blank">Read more</a>."
    3. Click Add to add a localizable string.

  5. Set up the tooltip of the Type field of the contact page. To do this, add the configuration object of the page field to the diff array of modifications.

    View the source code of the replacement view model of the contact page below.

    ContactPageV2
    define("ContactPageV2", [], function () {
    return {
        /* The name of the record page object's schema. */
        entitySchemaName: "Contact",
        /* Display the tooltip. */
        diff: /**SCHEMA_DIFF*/[
            /* The metadata to add the tooltip to the button. */
            {
                /* Execute the operation that modifies the existing element. */
                "operation": "merge",
                /* The meta name of the field to change. */
                "name": "Type",
                /* The meta name of the parent container whose field to change. */
                "parentName": "ContactGeneralInfoBlock",
                /* Change the field in the element collection of the parent element. */
                "propertyName": "items",
                /* The properties to pass to the element's constructor. */
                "values": {
                    /* The property of the field that displays the tooltip. */
                    "tip": {
                        /* The tooltip text. */
                        "content": { "bindTo": "Resources.Strings.TypeFieldHint" },
                        /* The display mode of the tooltip.
                        By default, WIDE. Changes the width of the green line displayed in the tooltip. */
                        "displayMode": Terrasoft.controls.TipEnums.displayMode.WIDE
                    }
                }
            }
        ]/**SCHEMA_DIFF*/
    };
});
  6. Click Save on the Designer's toolbar.

Outcome of the example 

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

As a result, Creatio will add the tooltip to the Type field of the contact page.

Resources
Package with example implementation