6.1 KiB
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
AbpTextTemplatingModuleto 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.
TemplateDefinitionTemplateContent
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 templateLocalizationResource(Type) Inline LocalizedIsInlineLocalized(boolean) describes that the template is inline localized or notDefaultCultureName(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 LocalizationMultiple 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.
For default, ABP uses
Virtual Filesfor text templates. All given examples are forVirtual 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.