Creating helper functions for the Sempare Template Engine

The Sempare Template Engine (available at https://github.com/sempare/sempare-delphi-template-engine and GetIt) is a versatile templating system designed specifically for Delphi developers to streamline the creation and management of dynamic HTML, text, or any other text-based output formats. Whether you are building web applications, reports, or email templates, the Sempare Template Engine offers a powerful yet straightforward solution that integrates with minimal boilerplate into Delphi projects. The template engine has been around since 2019 and has many features for you to explore.

In this tutorial, we will explore how to add helper functions to the template engine.

Builtin functions

The template engine has a number of builtin functions as described on https://github.com/sempare/sempare-delphi-template-engine/blob/main/docs/builtin-functions.md

In this tutorial, we will describe you you can use your own.

Calling functions

Lets start by illustrating how to call a builtin function:

<% fmtdt('yyyy-mm-dd', dtnow()) %>

Calling a custom helper function is no different, except that the builtin functions have been pre-packaged.

Defining functions

Defining functions is done by defining static class methods on a class and binding them to a context.

type
  THelperMethods = class
  public
    class function Add(const AValue, BValue : integer) : integer; static;
  end;

class function THelperMethods.Add(const AValue, BValue : integer) : integer;
begin
  Result := AValue + BValue;
end;

The nice thing about Delphi's RTTI system is that we can map the parameters provided to to the template to the methods using normal types, rather than variadic alternatives and utilising the type system available to us.

Accessing context information

If your function requires access to the template context, it may be presented as the first parameter.

   class function DoSomething(const AContext: ITemplateContext; const AValue : string) : string; static;

Registering your functions

Registering your functions is done through a Template Context and accessing it is a simple as illustrated:

var LContext := Template.Context();
LContext.Functions.AddFunctions(THelperMethods);

var LOutput := Template.Eval(LContext, '<% Add(1,2) %>');

writeln(LOutput);

Limitations

Support for overloaded methods is not robust at present. We do have a patch on the way to improve overloaded support, but it is heavier on the system, so would rather advise having methods with unique names that are not overloaded.

Support for variadic parameters is also going to be improved. e.g. a signature such as:

   class function Sum(const AValues : TArray<integer>) : integer; static;

Lastly, the template engine has no context of default parameters on methods. Unfortunately, you will have to ensure all parameters are passed through correctly.

Conclusion

The Sempare Template Engine offers you many options to extend and offer richness to your templates.

Sponsorship Required

Please help us maintain the project by supporting Sempare via GitHub sponsors (https://github.com/sponsors/sempare) or via our payment link (https://buy.stripe.com/aEU7t61N88pffQIdQQ). Sponsors can obtain access to our integrated IDE wizard for RAD Studio.