docs/en/modules/text-template-management.md
//[doc-seo]
{
"Description": "Manage and edit text templates effortlessly with the ABP Framework's Text Template Management Module, enhancing your application's communication features."
}
You must have an ABP Team or a higher license to use this module.
This module stores and lets users edit content for ABP's text templating system. Read the text templating documentation to understand how applications define and render templates.
Applications use text templates for many purposes. For example, the Account Module defines templates for emails such as password reset messages. This module provides a UI for editing those templates.
See the module description page for an overview of the module features.
The TextManagement.Enable feature is enabled by default. The module's permissions, application services and menu items require this feature.
The Text Template Management module is pre-installed in the startup templates, so you do not need to install it manually.
To add the Text Template Management module to an existing solution, use the ABP CLI add-module command:
abp add-module Volo.TextTemplateManagement
This module follows the module development best practices guide and consists of several NuGet and NPM packages. See the guide if you want to understand the packages and relations between them.
Visit the Text Template Management module package list to see the packages related to this module.
Text Template Management module adds the following items to the "Main" menu, under the "Administration" menu item:
TextTemplateManagementMainMenuNames class has the constants for the menu item names.
The Text Templates page lists the templates defined in the application.
Click Actions > Edit Contents to edit a template. The module provides two editors:
This kind of templates uses the L function to perform inline localization. In this way, it is easier to manage the template for different cultures.
This kind of templates provides different content for each culture. In this way, you can define a completely different content for a specific culture.
Saved content is an override for the current tenant context. The host and each tenant have separate overrides; a tenant doesn't inherit an override saved in the host context. If no database override exists, the text templating system continues with the configured content contributors, such as the template's virtual-file content.
For a static template, the framework content provider first tries the requested regional culture and then its parent culture. An inline-localized template then falls back to its culture-independent content, while a culture-specific template falls back to its configured default culture.
Dynamic definitions use a different lookup order. When IsDynamicTemplateStoreEnabled is enabled and a definition exists only in the database, DatabaseTemplateContentContributor tries the requested culture, the definition's default culture (or en when it has no default), and then culture-independent content. This lookup can return content before the framework tries the requested culture's parent. Restore to default deletes the current tenant context's override for the selected template and culture, after which the applicable fallback path is used again.
The MVC UI uses textTemplateManagement.textDefinition for both entity action extensions and data table column extensions.
The Blazorise UI exposes entity actions and table columns through the TextTemplateManagement page component type. See the Blazor entity action and data table column extension documents.
TextTemplateManagementOptionsTextTemplateManagementOptions can be used to configure the module. The following example shows the default values:
Configure<TextTemplateManagementOptions>(options =>
{
options.MinimumCacheDuration = TimeSpan.FromHours(1);
options.SaveStaticTemplatesToDatabase = true;
options.IsDynamicTemplateStoreEnabled = false;
});
| Property | Description |
|---|---|
MinimumCacheDuration | Sets the sliding expiration of cached template contents. The default is one hour. |
SaveStaticTemplatesToDatabase | Starts synchronizing static template definitions and their virtual-file contents to the database during application initialization. The default is true. |
IsDynamicTemplateStoreEnabled | Enables the database-backed dynamic template-definition store. The default is false. Static definitions take precedence when static and dynamic definitions share the same name. |
Both SaveStaticTemplatesToDatabase and IsDynamicTemplateStoreEnabled are disabled automatically in a data-migration environment. Disabling static synchronization doesn't disable saved content overrides.
DatabaseTemplateContentContributor caches template contents to increase performance. Cache entries use the MinimumCacheDuration sliding expiration.
You can access the cache by injecting IDistributedCache<string, TemplateContentCacheKey>. TemplateContentCacheKey contains the template definition name and culture; ABP's distributed cache key normalization also isolates entries by the current tenant context. The application service removes the related cache entry when it persists a new override or deletes one through Restore to default, so an application restart isn't required.
For more information, please check the Caching guide.
TemplateContentCacheKey is a special cache key for template contents.
It has TemplateDefinitionName and Culture properties.
This module doesn't define an IDataSeedContributor. The optional startup synchronization controlled by SaveStaticTemplatesToDatabase is separate from the data seed system.
This module follows the Entity Best Practices & Conventions guide.
TextTemplateContent (aggregate root): Represents a tenant-aware template content override.TextTemplateDefinitionRecord (aggregate root): Stores synchronized template definition metadata.TextTemplateDefinitionContentRecord (entity): Stores a synchronized definition's file content.This module follows the Repository Best Practices & Conventions guide.
The following custom repositories are defined for this module:
ITextTemplateContentRepositoryITextTemplateDefinitionRecordRepositoryITextTemplateDefinitionContentRecordRepositoryDatabaseTemplateContentContributor is an ITemplateContentContributor used by ITemplateContentProvider to read tenant-aware content overrides and, when the dynamic definition store is enabled, synchronized definition content from the database and cache.
This module doesn't define any setting.
TemplateDefinitionAppService (implements ITemplateDefinitionAppService): Implements the use cases of the text template management UI.TemplateContentAppService (implements ITemplateContentAppService): Implements the use cases of the text template management UI.All tables/collections use the Abp prefix by default. Set static properties on the TextTemplateManagementDbProperties class if you need to change the table prefix or set a schema name (if supported by your database provider).
This module uses TextTemplateManagement as the connection string name. If you don't define a connection string with this name, it falls back to the Default connection string.
See the connection strings documentation for details.
All permissions require the TextManagement.Enable feature.
The module defines the following permissions:
| Permission | Purpose |
|---|---|
TextTemplateManagement.TextTemplates | View and filter template definitions and read their contents. |
TextTemplateManagement.TextTemplates.EditContents | Edit and restore template content. |
TextTemplateManagement.TextTemplates.EditNonSandboxedContents | Additionally authorize editing templates rendered by a non-sandboxed engine, such as Razor. |
Whether a template is sandboxed is determined by ITemplateRenderingEngine.IsSandboxed on the engine that renders it. An unknown, unregistered or unresolved default engine is treated as non-sandboxed. Editing a non-sandboxed template requires both EditContents and EditNonSandboxedContents.
When the standard Permission Management data seeder runs, it grants all role-applicable permissions to the admin role. This includes EditNonSandboxedContents. If the administrators in your application shouldn't be allowed to edit executable template content, customize the seeding policy and remove any existing grant.
The Text Template Management UI surfaces this distinction:
EditNonSandboxedContents for a non-sandboxed template.Treat
EditNonSandboxedContentsas equivalent to granting shell access to the application server. Only assign it to fully trusted developers or operators.
To configure the application to use the text template management module, import provideTextTemplateManagementConfig from @volo/abp.ng.text-template-management/config and add it to the root providers array.
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideTextTemplateManagementConfig } from '@volo/abp.ng.text-template-management/config';
export const appConfig: ApplicationConfig = {
providers: [
// ...
provideTextTemplateManagementConfig(),
],
};
The text template management module should be imported and lazy-loaded in your routing array. It exports a createRoutes function from @volo/abp.ng.text-template-management. Available options are listed below.
// app.routes.ts
import { Routes } from '@angular/router';
const APP_ROUTES: Routes = [
// ...
{
path: 'text-template-management',
loadChildren: () =>
import('@volo/abp.ng.text-template-management').then(c => c.createRoutes()),
},
];
<h4 id="h-text-template-management-module-options">Options</h4>Startup templates already include both settings, so no additional configuration is needed.
You can modify the look and behavior of the module pages by passing the following options to the createRoutes function:
The Text Template Management module's services and models are generated by the ABP CLI generate-proxy command. To generate the module's proxies, run the following command in the Angular project directory:
abp generate-proxy --module textTemplateManagement
eTextTemplateManagementComponents enum provides all replaceable component keys. It is available for import from @volo/abp.ng.text-template-management.
The available keys are:
eTextTemplateManagementComponents.TextTemplateseTextTemplateManagementComponents.TemplateContentseTextTemplateManagementComponents.InlineTemplateContentPlease check Component Replacement document for details.
The Text Template Management module remote endpoint URL can be configured in the environment files.
export const environment = {
// other configurations
apis: {
default: {
url: 'default url here',
},
TextTemplateManagement: {
url: 'Text Template Management remote url here',
},
// other api configurations
},
};
The Text Template Management module's remote URL configuration is optional. If you don't set a URL, default.url is used as a fallback.
This module doesn't define any additional distributed event. See the standard distributed events.