Adding multi-language email templates to a custom section

Introduction

You can set up custom logic for selecting languages of multi-language email templates. You can select email templates in the needed language using the action dashboard of a section record. The selection is based on special rules that can be specified for the section. If special rules are not defined, the selection is based on the contact, bound to the edited record (the [Contact] column). If a section object does not have a column for connecting with a contact, the DefaultMessageLanguage system setting value is used.

To add custom logic for selecting multi-language templates (localization):

1. Create a class or classes inherited from BaseLanguageRule and define the language selection rules (one class defines one rule).

2. Create a class inherited from BaseLanguageIterator. Define the LanguageRules property in the class constructor as a class instance array created on the previous step. The sequence corresponds to the rule priority.

3. Create a class inherited from AppEventListenerBase that will bind the class defining the language selection rules to the section.

4. Add the necessary multi-language templates to the [Email templates] lookup.

Case description

Add logic of selecting an email template language to a custom section based on the UsrContact column of the primary section object. Use English and Spanish languages.

Source code

You can download the package with case implementation using the following link.

Preliminary settings

For correct case implementation:

1. Make sure that the [Customer languages] lookup contains English and Spanish languages (Fig.1).

Fig. 1. [Customer languages] lookup

2. Use the section wizard to check that there is the UsrContact column bound to the [Contact] lookup on the edit page of the custom section record (Fig.2).

Fig. 2. The UsrContact column

Case implementation algorithm

1. Adding a language selection rule

Create a [Source code] schema in the custom package (see “Creating the [Source code] schema”).

For the created schema specify (Fig. 3):

• [Name] – "UsrContactInUsrTestLanguageRule"
• [Title] – "User defined email template rule”

Fig. 3. The [Source code] schema properties

Add the following source code to the schema:

namespace Terrasoft.Configuration
{
    using System;
    using Terrasoft.Core;
    using Terrasoft.Core.Entities;
    public class ContactInUsrTestLanguageRule : BaseLanguageRule
    {
        public ContactInUsrTestLanguageRule (UserConnection userConnection) : base(userConnection) 
        {
        }
        // Defines the user preferred language identifier. 
        // recId — current record identifier.
        public override Guid GetLanguageId(Guid recId)
        {
            // Creating the EntitySchemaQuery instance for the custom section primary object.
            var esq = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "UsrMLangEmailTpl");
            // Defining the contact language column name.
            var languageColumnName = esq.AddColumn("UsrContact.Language.Id").Name;
            // Obtaining current record instance.
            Entity usrRecEntity = esq.GetEntity(UserConnection, recId);
            // Obtaining the value of user preferred language identifier. 
            Guid languageId = usrRecEntity.GetTypedColumnValue<Guid>(languageColumnName);
            return languageId;
        }
    }
}

Publish the schema.

2. Defining the order sequence of language selection rules

Create a [Source code] schema in the custom package (see “Creating the [Source code] schema”).

For the created schema specify (Fig. 3):

• [Name] – "UsrTestLanguageIterator”
• [Title] – "User defined language iterator”

Add the following source code to the schema:

namespace Terrasoft.Configuration
{
    using Terrasoft.Core;
    public class UsrTestLanguageIterator: BaseLanguageIterator
    {
        public UsrTestLanguageIterator(UserConnection userConnection): base(userConnection)
        {
            // Language selection rule array.
            LanguageRules = new ILanguageRule[] {
                // Custom rule.
                new ContactInUsrTestLanguageRule (UserConnection),
                // Default rule.
                new DefaultLanguageRule(UserConnection),
            };
        }
    }
}

DefaultLanguageRule. is the second array element The rules uses the DefaultLanguage system setting for obtaining the language and is used by default if the language was not detected by higher priority rules.

Publish the schema.

3. Binding language selection iterator to the section

Create a [Source code] schema in the custom package (see “Creating the [Source code] schema”).

For the created schema specify (Fig. 3):

• [Name] – "UsrTestMLangBinder”
• [Title] – "UsrTestMLangBinder"

Add the following source code to the schema:

namespace Terrasoft.Configuration
{
    using Terrasoft.Core.Factories;
    using Terrasoft.Web.Common;
    public class UsrTestMLangBinder: AppEventListenerBase
    {
        public override void OnAppStart(AppEventContext context)
        {
            // Calling the basic logics.
            base.OnAppStart(context);
            // Binding iterator to a custom section.
            // UsrMLangEmailTpl — name of the section primary object.
            ClassFactory.Bind<ILanguageIterator, UsrTestLanguageIterator>("UsrMLangEmailTpl");
        }
    }
}

Publish the schema.

4. Adding the necessary multi-language templates

Add a new record (Fig.4) to the [Email Templates] lookup and define the email templates in the necessary languages (Fig.5).

Fig. 4. A new record in the [Email templates] lookup

Fig. 5. Adding templates in the necessary languages

As a result of case implementation, in the action dashboard panel (Fig. 6. 1) of the custom section record edit page (Fig.6) the email templates (Fig. 6. 2) will be selected automatically in the language (Fig. 6. 3) specified as the contact’s preferred language (Fig.7).

Fig. 6. Case result

Fig. 7. Contact preferred language