Configuring the Sempare Template Engine for Delphi

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 some of the options to configure a template context.

Safe web development

We know we are in an unsafe world! Attacks are occurring continually. SQL injection, HTML injection just to name the most obvious...

The Sempare Template Engine has features to ensure your web app is safe and responsive. Two features that are important are:

• max run times
• automatic HTML encoding

Max run times

By default, the max runtime is set to 1 minute.

This can be customised:

  var ctx := Template.Context();
  ctx.MaxRunTimeMs = 5;

Automatic HTML encoding

This can be customised:

var LCtx := Template.Context();
LCtx.UseHtmlVariableEncoder();

Let's say we have the following scenario:

type
   TTemplateData = record
      DataField : string;
   end;

var LData : TTemplateData;
LData.DataField := '<script>alert("hello world");</script>';

writeln(Template.Eval('Unsafe: <% DataField %>', LData));
writeln(Template.Eval(LCtx, 'Safe: <% DataField %>', LData));

The output:

Unsafe: <script>alert("hello world");</script>
Safe: &lt;script&gt;alert(&quot;hello world&quot;);&lt;/script&gt;

When you have HTML encoding enabled, you may have scenarios where you want to evaluate raw HTML. You can use the print statement to do this.

<% DataField %>
     vs
<% print(DataField) %>

Changing the script tags

By default, template scripting is done between the <% and %> tags.

This can be changed as follows:

  var LCtx := Template.Context();
  LCtx.StartToken := '{{';
  LCtx.EndToken := '}}';
  writeln(Template.Eval(LCtx, '{{ if true }}hello{{else}}bye{{end}}'));

Embedded error messages

By default, errors in the template evaluation results in a template Exception being raised.

try
  writeln(Template.Eval(LCtx, '<% a := ["a"; "b"] %>'));
except on E: Exception do
  writeln(E.Message);
end;

The above example will raise an exception stating that a comma (,) is expected, rather than the semicolon (;).

We can change the behaviour as follows:

var LCtx := Template.Context();
LCtx.Options := LCtx.Options + [eoEmbedException];
try
  writeln(Template.Eval(LCtx, '<% a := ["a"; "b"] %>'));
except on E: Exception do
  writeln(E.Message);
end;

The above example will produce output:

(Line 1, Column 14) Parsing error. Expecting: ,

Documentation

The documentation for the context is available at https://github.com/sempare/sempare-delphi-template-engine/blob/main/docs/configuration.md

Conclusion

There are many configuration options available for manipulating the behaviour of the template engine.

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.