feat: reference partials and functions in Didot.Core (only ST, Scriban and Hdb) (#173)

Author: Seddryck

docs/_data/navigation_docs.yml

@@ -27,6 +27,8 @@
   - configuration
   - feature-formatter
   - feature-mappings
+  - feature-partial
+  - feature-function
 
 - title: Parsers
   docs:

docs/_docs/feature-function.md

@@ -0,0 +1,70 @@
+---
+title: Defining a function
+tags: [template, features]
+---
+## Overview
+
+A template function is a function defined inside a template that can render content dynamically. When passed as an argument to another function (like map, each, or custom helpers), it acts as a kind of callback, formatting or transforming values within the template itself.
+
+You define a template block or lambda that takes arguments and renders something with them. Then you pass that function to another function (e.g., a mapping function or loop).
+
+## Registering a Function
+
+To register a function, use the `AddFunction` method of an `ITemplateEngine`. The method requires:
+
+- A name for the function – the identifier for the function.
+- A function returning a string representing the function template.
+
+```csharp
+var factory = new FileBasedTemplateEngineFactory();
+var engine = factory.GetByTag(tag);
+engine.AddFunction("Hello", () => "function definition");
+```
+
+## Using Functions in Templates
+
+Once registered, functions can be applied directly in templates by referencing the function name and passing values to the parameters. All examples below will have the same output:
+
+```text
+Greetings: Mr. Einstein Albert!
+```
+
+### Scriban
+
+The main template is defined as,
+
+```liquid
+{% raw %}Greetings: {{ Hello(model.Name.First, model.Name.Last) }}!{% endraw %}
+```
+
+and the function itself is defined as,
+
+```text
+{%- raw -%}
+{{ func Hello(firstName, lastName) -}}
+  Mr. {{ lastName }} {{ firstName -}}
+{{ end }}
+{% endraw %}
+```
+
+### StringTemplate
+
+The main template is defined as,
+
+```text
+{% raw %}Greetings: <Hello(model.Name.First, model.Name.Last)>!{% endraw %}
+```
+
+and the function itself is defined as,
+
+```text
+{% raw %}Hello(firstName, lastName)::= Mr. <lastName> <firstName>{% endraw %}
+```
+
+### Liquid, Fluid, Handlebars, Morestachio and SmartFormat
+
+This feature is not supported.
+
+### Conclusions
+
+Template functions that accept another template function give you a clean, composable way to define how data should be rendered, and reuse that rendering logic flexibly.

docs/_docs/feature-mappings.md

@@ -22,7 +22,7 @@ Once registered, mappings can be applied directly in templates by referencing th
 ```csharp
 var factory = new FileBasedTemplateEngineFactory();
 var engine = factory.GetByTag(tag);
-engine.AddMappings("greetings", new Dictionary<object, string>() { {"french", "Bonjour"}, {"english", "Hi"}, {"spanish", "Ola"} })
+engine.AddMappings("greetings", new Dictionary<object, string>() { {"french", "Bonjour"}, {"english", "Hi"}, {"spanish", "Ola"} });
 ```
 
 Assume the model contains a property *Language*, and a dictionary named *greetings* has been registered to provide translations. The following examples demonstrate how to apply mappings across different template engines:

docs/_docs/feature-partial.md

@@ -0,0 +1,58 @@
+---
+title: Defining a partial
+tags: [template, features]
+---
+## Overview
+
+A partial is a reusable snippet of template code that can be included or embedded within one or more templates. It allows you to extract repeated layout or formatting logic into a separate, named unit, improving both readability and maintainability.
+
+When a template includes a partial, the templating engine:
+
+1. Looks up the partial by its name
+2. Loads or renders its content
+3. Injects the rendered result into the main template at the point of inclusion
+
+## Registering a Partial
+
+To register a partial, use the `AddPartial` method of an `ITemplateEngine`. The method requires:
+
+- A name for the partial – the identifier for the partial.
+- A function returning a string representing the partial template.
+
+## Using Partials in Templates
+
+Once registered, mappings can be applied directly in templates by referencing the dictionary name.
+
+```csharp
+var factory = new FileBasedTemplateEngineFactory();
+var engine = factory.GetByTag(tag);
+engine.AddPartial("greetings", () => "Welcome");
+```
+
+In this case, at each occurrence of the partial *greetings*, it will output the text *Welcome*.
+
+```text
+Welcome, Albert Einstein!
+```
+
+### Scriban
+
+```liquid
+{% raw %}{{include 'greetings'}}, {{model.Name.First}} {{model.Name.Last}}!{% endraw %}
+```
+
+### Handlebars
+
+```handlebars
+{% raw %}{{> Greetings }}, {{model.Name.First}} {{model.Name.Last}}!{% endraw %}
+```
+
+### StringTemplate
+
+```text
+{% raw %}<Greetings()>, <model.Name.First> <model.Name.Last>!{% endraw %}
+```
+
+### Liquid, Fluid, Morestachio and SmartFormat
+
+This feature is not supported.

src/Didot.Core/ITemplateEngine.cs

@@ -9,6 +9,8 @@ public interface ITemplateEngine
 {
     void AddMappings(string mapKey, IDictionary<string, object> mappings);
     void AddFormatter(string name, Func<object?, string> function);
+    void AddFunction(string name, Func<string> template);
+    void AddPartial(string name, Func<string> template);
     string Render(string template, object model);
     string Render(Stream template, object model);
 }

src/Didot.Core/TemplateEngines/BaseTemplateWrapper.cs

@@ -18,6 +18,8 @@ public BaseTemplateEngine(TemplateConfiguration configuration)
 
     protected Dictionary<string, IDictionary<string, object>> Mappings { get; } = [];
     protected Dictionary<string, Func<object?, string>> Formatters { get; } = [];
+    protected Dictionary<string, Func<string>> Functions { get; } = [];
+    protected Dictionary<string, Func<string>> Partials { get; } = [];
 
     public virtual void AddMappings(string mapKey, IDictionary<string, object> mappings)
     {
@@ -31,6 +33,18 @@ public virtual void AddFormatter(string name, Func<object?, string> function)
             Formatters[name] = function;
     }
 
+    public virtual void AddFunction(string name, Func<string> template)
+    {
+        if (!Functions.TryAdd(name, template))
+            Functions[name] = template;
+    }
+
+    public virtual void AddPartial(string name, Func<string> template)
+    {
+        if (!Partials.TryAdd(name, template))
+            Partials[name] = template;
+    }
+
     public abstract string Render(string template, object model);
     public abstract string Render(Stream stream, object model);
 }

src/Didot.Core/TemplateEngines/DotLiquidWrapper.cs

@@ -19,6 +19,10 @@ public DotLiquidWrapper(TemplateConfiguration configuration)
 
     public override void AddFormatter(string name, Func<object?, string> function)
         => throw new NotImplementedException();
+    public override void AddFunction(string name, Func<string> template)
+        => throw new NotImplementedException();
+    public override void AddPartial(string name, Func<string> template)
+        => throw new NotImplementedException();
 
     public override string Render(string source, object model)
     {

src/Didot.Core/TemplateEngines/FluidWrapper.cs

@@ -6,6 +6,8 @@
 using System.Threading.Tasks;
 using Fluid;
 using Fluid.Values;
+using Microsoft.Extensions.FileProviders;
+using Microsoft.Extensions.Primitives;
 using SmartFormat.Core.Extensions;
 
 namespace Didot.Core.TemplateEngines;
@@ -21,6 +23,12 @@ public FluidWrapper(TemplateConfiguration configuration)
         : base(configuration)
     { }
 
+    public override void AddFunction(string name, Func<string> template)
+        => throw new NotImplementedException();
+
+    public override void AddPartial(string name, Func<string> template)
+        => throw new NotImplementedException();
+
     public override string Render(string source, object model)
     {
         var template = Parser.Parse(source);

src/Didot.Core/TemplateEngines/HandlebarsWrapper.cs

@@ -17,6 +17,8 @@ public HandlebarsWrapper()
     public HandlebarsWrapper(TemplateConfiguration configuration)
         : base(configuration)
     { }
+    public override void AddFunction(string name, Func<string> template)
+        => throw new NotImplementedException();
 
     public override string Render(string template, object model)
     {
@@ -32,6 +34,9 @@ public override string Render(Stream stream, object model)
         using var reader = new StreamReader(stream);
         var templateInstance = handlebarsContext.Compile(reader);
 
+        foreach (var include in Partials)
+            handlebarsContext.RegisterTemplate(include.Key, include.Value.Invoke());
+
         using var writer = new StringWriter(); // StringWriter as TextWriter for output
         templateInstance(writer, model);
         return writer.ToString();

src/Didot.Core/TemplateEngines/MorestachioWrapper.cs

@@ -17,6 +17,11 @@ public MorestachioWrapper()
     public MorestachioWrapper(TemplateConfiguration configuration)
         : base(configuration)
     { }
+    public override void AddFunction(string name, Func<string> template)
+        => throw new NotImplementedException();
+
+    public override void AddPartial(string name, Func<string> template)
+        => throw new NotImplementedException();
 
     public override string Render(string template, object model)
     {