Adding multi-language email templates to a custom section
Glossary Item Box
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.
ATTENTION
You can install the package for bpm’online products, containing the EmailTemplates package. Make sure all the below described preliminary settings are performed after you install the package.
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