8.3 KiB

Raw Blame History Unescape Escape

Text Templating

In ABP Framework, text template is a mixture of text blocks and control logic that can generate a string result. An open source package Scriban is used for the control logic and Abp.Localization is used to make content easily localizable. The generated string can be text of any kind, such as a web page, an e-mail content etc.

stored content

<ol>
{{~ for $i in 0..3 ~}}
 <li>{{ L "WelcomeMessage" }}</li>
{{~ endfor ~}}
</ol>

result (for en culture)

1. Welcome to the abp.io!
2. Welcome to the abp.io!
3. Welcome to the abp.io!
4. Welcome to the abp.io!

Installation

It is suggested to use the ABP CLI to install this package.

Using the ABP CLI

Open a command line window in the folder of the project (.csproj file) and type the following command:

abp add-package Volo.Abp.TextTemplating

Manual Installation

If you want to manually install;

Add the Volo.Abp.TextTemplating NuGet package to your project:

Install-Package Volo.Abp.TextTemplating

Add the AbpTextTemplatingModule to the dependency list of your module:

[DependsOn(
    //...other dependencies
    typeof(AbpTextTemplatingModule) //Add the new module dependency
    )]
public class YourModule : AbpModule
{
}

Logic

A Text Template is a combination of two object.

TemplateDefinition
TemplateContent

Template Definition

Template Definition is an object that contains some information about your Text Templates. Template Definition object contains the following properties.

Name (string)
IsLayout (boolean)
Layout (string) contains the name of layout template
LocalizationResource (Type) Inline Localized
IsInlineLocalized(boolean) describes that the template is inline localized or not
DefaultCultureName (string) defines the default culture for the template

Template Content

This is a simple content for your templates. For default, template contents stored as Virtual File.

Example: ForgotPasswordEmail.tpl

<h3>{{L "PasswordReset"}}</h3>

<p>{{L "PasswordResetInfoInEmail"}}</p>

<div>
    <a href="{{model.link}}">{{L "ResetMyPassword"}}</a>
</div>

Localization

You can localize your Text Templates by choosing two different method.

Inline Localization
Multiple Content Localization

Inline Localization

Inline localized Text Templates is using only one content resource, and it is using the Abp.Localization to get content in different languages/cultures.

Example Inline Localized Text Template:

ForgotPasswordEmail.tpl

<h3>{{L "PasswordReset"}}</h3>

<p>{{L "PasswordResetInfoInEmail"}}</p>

<div>
    <a href="{{model.link}}">{{L "ResetMyPassword"}}</a>
</div>

Multiple Content Localization

You can store your Text Templates for any culture in different content resource.

Example Multiple Content Localization

ForgotPasswordEmail / en.tpl

<h3>Reset Your Password</h3>

<p>Hello, this is a password changing email.</p>

<div>
    <a href="{{model.link}}">Click To Reset Your Password</a>
</div>

ForgotPasswordEmail / tr.tpl

<h3>Şifrenizi Değiştirin</h3>

<p>Merhaba, bu bir şifre yenileme e postasıdır.</p>

<div>
    <a href="{{model.link}}">Şifrenizi Yenilemek İçin Tıklayınız</a>
</div>

Layout System

It is typical to use the same layout for some different Text Templates. So, you can define a layout template.

A text template can be layout for different text templates and also a text template may use a layout.

A layout Text Template must have {{content}} area to render the child content. (just like the RenderBody() in the MVC)

Example Email Layout Text Template

<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="utf-8" />
</head>
<body>
    {{content}}
</body>
</html>

Definition a Text Template

First of all, create a class that inherited from TemplateDefinitionProvider abstract class and create Define method that derived from the base class.

Define method requires a context that is ITemplateDefinitionContext. This context is a storage for template definitions and we will add our template definitions to the context.

NOTE! For default, ABP uses Virtual File System for text templates. Do not forget to register your files as an Embedded Resource. Please check the Virtual File System Documentation for more details.

All given examples are for Virtual File Text Template Definitions.

public class MyTemplateDefinitionProvider : TemplateDefinitionProvider
    {
        public override void Define(ITemplateDefinitionContext context)
        {
            // Layout Text Template
            context.Add(
                new TemplateDefinition(
                    name: "MySampleTemplateLayout", // Template Definition Name
                    isLayout: true 
                ).WithVirtualFilePath("/SampleTemplates/SampleTemplateLayout.tpl", true)
            );

            // Inline Localized Text Template
            context.Add(
                new TemplateDefinition(
                    name: "ForgotPasswordEmail",
                    localizationResource: typeof(MyLocalizationResource),
                    layout: TestTemplates.TestTemplateLayout1
                ).WithVirtualFilePath("/SampleTemplates/ForgotPasswordEmail.tpl", true)
            );

            // Multiple File Localized Text Template
            context.Add(
                new TemplateDefinition(
                    name: "ForgotPasswordEmail",
                    defaultCultureName: "en"
                ).WithVirtualFilePath("/SampleTemplates/ForgotPasswordEmail", false)
            );
        }
    }

As you see in the given example, all Text Templates are added with (ITemplateDefinitionContext)context.Add method. This method requires a TemplateDefinition object. Then we call WithVirtualFilePath method with chaining for the describe where is the virtual files.

WithVirtualFilePath is requires one tpl file path for the Inline Localized Text Templates. If your Text Tempalte is Multi Localized you should create a folder and store each different culture files under that. So you can send the folder path as a parameter to WithVirtualFilePath.

Inline Localized File

/ Folder / ForgotPasswordEmail.tpl

Multi Content Localization

/ Folder / ForgotPasswordEmail / en.tpl
/ Folder / ForgotPasswordEmail / tr.tpl

Rendering

When one template is registered, it is easy to render and get the result with ITemplateRenderer service.

ITemplateRenderer service has one method that named RenderAsync and to render your content and it is requires some parametres.

templateName (string) Not Null
model (object) Can Be Null
cultureName (string) Can Be Null
globalContext (dictionary) Can Be Null

templateName is exactly same with Template Definition Name.

model is a dynamic object. This is using to put dynamic data into template. For more information, please look at Scriban Documentation.

cultureName is your rendering destination culture. When it is not exist, it will use the default culture.

If cultureName has a language tag it will try to find exact culture with tag, if it is not exist it will use the language family.

If you try to render content with "es-MX" it will search your template with "es-MX" culture, when it fails to find, it will try to render "es" culture content. If still can't find it will render the default culture content that you defined.

globalContext = TODO

Template Definition Manager

When you want to get your Template Definitions, you can use a singleton service that named Template Definition Manager in runtime.

To use it, inject ITemplateDefinitionManager service.

It has three method that you can get your Template Definitions.

Get
GetOrNull
GetAll

Get and GetOrNull requires a string parameter that name of template definition. Get will throw error when it is not exist but GetOrNull returns null.

GetAll returns you all registered template definitions.

8.3 KiB Raw Blame History Unescape Escape