diff --git a/docs/en/Text-Templating.md b/docs/en/Text-Templating.md index c722d2650e..db2f25a807 100644 --- a/docs/en/Text-Templating.md +++ b/docs/en/Text-Templating.md @@ -4,11 +4,11 @@ ABP Framework provides a simple, yet efficient text template system. Text templating is used to dynamically render contents based on a template and a model (a data object): -TEMPLATE + MODEL => RENDERED CONTENT +***TEMPLATE + MODEL ==render==> RENDERED CONTENT*** It is very similar to an ASP.NET Core Razor View (or Page): -RAZOR VIEW (or PAGE) + MODEL => HTML CONTENT +*RAZOR VIEW (or PAGE) + MODEL ==render==> HTML CONTENT* You can use the rendered output for any purpose, like sending emails or preparing some reports. @@ -374,47 +374,72 @@ The rendering result will be: A global object value: TEST VALUE ```` +## Advanced Features +This section covers some internals and more advanced usages of the text templating system. -## Template Content Provider +### Template Content Provider -When you want to get your stored template content you can use `ITemplateContentProvider`. +`ITemplateRenderer` is used to render the template, which is what you want for most of the cases. However, you can use the `ITemplateContentProvider` to get the raw (not rendered) template contents. -`ITemplateContentProvider` has one method that named `GetContentOrNullAsync` with two different overriding, and it returns you a string of template content or null. (**without rendering**) +> `ITemplateContentProvider` is internally used by the `ITemplateRenderer` to get the raw template contents. -- `templateName` (_string_) or `templateDefinition` (_`TemplateDefinition`_) -- `cultureName` (_string_) -- `tryDefaults` (_bool_) -- `useCurrentCultureIfCultureNameIsNull` (_bool_) +Example: -### Usage +````csharp +public class TemplateContentDemo : ITransientDependency +{ + private readonly ITemplateContentProvider _templateContentProvider; -First parametres of `GetContentOrNullAsync` (`templateName` or `templateDefinition`) are required, the other three parametres can be null. + public TemplateContentDemo(ITemplateContentProvider templateContentProvider) + { + _templateContentProvider = templateContentProvider; + } -If you want to get exact culture content, set `tryDefaults` and `useCurrentCultureIfCultureNameIsNull` as a `false`. Because the `GetContentOrNullAsync` tries to return content of template. + public async Task RunAsync() + { + var result = await _templateContentProvider + .GetContentOrNullAsync("Hello"); -> Example Scenario + Console.WriteLine(result); + } +} +```` -> If you have a template content that culture "`es`", when you try to get template content with "`es-MX`" it will try to return first "`es-MX`", if it fails it will return "`es`" content. If you set `tryDefaults` and `useCurrentCultureIfCultureNameIsNull` as `false` it will return `null`. +The result will be the raw template content: -## Template Definition Manager +```` +Hello {{model.name}} :) +```` + +* `GetContentOrNullAsync` returns `null` if no content defined for the requested template. +* It can get a `cultureName` parameter that is used if template has different files for different cultures (see Multiple Contents Localization section above). -When you want to get your `Template Definitions`, you can use a singleton service that named `Template Definition Manager` in runtime. +### Template Content Contributor -To use it, inject `ITemplateDefinitionManager` service. +`ITemplateContentProvider` service uses `ITemplateContentContributor` implementations to find template contents. There is a single pre-implemented content contributor, `VirtualFileTemplateContentContributor`, which gets template contents from the virtual file system as described above. -It has three method that you can get your Template Definitions. +You can implement the `ITemplateContentContributor` to read raw template contents from another source. -- `Get` -- `GetOrNull` -- `GetAll` +Example: + +````csharp +public class MyTemplateContentProvider + : ITemplateContentContributor, ITransientDependency +{ + public async Task GetOrNullAsync(TemplateContentContributorContext context) + { + var templateName = context.TemplateDefinition.Name; -`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`. + //TODO: Try to find content from another source + return null; + } +} -`GetAll` returns you all registered template definitions. +```` -## Template Content Contributor +Return `null` if your source can not find the content, so `ITemplateContentProvider` fallbacks to the next contributor. -You can store your `Template Contents` in any resource. To make it, just create a class that implements `ITemplateContentContributor` interface. +### Template Definition Manager -`ITemplateContentContributor` has a one method that named `GetOrNullAsync`. This method must return content **without rendering** if that is exist in your resource or must return `null`. \ No newline at end of file +`ITemplateDefinitionManager` service can be used to get the template definitions (created by the template definition providers). \ No newline at end of file