Copyright (c) 2019-2021 Sempare Limited

Contact: [email protected]

License: GPL v3.0 or Sempare Limited Commercial License

Open Source: https://github.com/sempare/sempare-delphi-template-engine

1. Introduction
2. Quickstart
3. Features
4. Objectives
5. Requirements
6. Installation: GetIt
7. Installation: Delphinus
8. Feedback
9. Statements
10. Expressions
11. Builtin functions
12. Builtin variables
13. Custom functions
14. Configuration
15. Components
16. Tricks
17. Template Patterns
18. Internals
19. Restrictions/Limitations/Known Bugs
20. Todo
21. License

Template engines are used often in in the technology where text needs to be customised by substituting variables with values from a data source. Examples where this may take place:

• web sites using template engines (or languages)
• code generation
• mail merge
• notification messages

The Sempare Template Engine is a small templating engine for Delphi (Object Pascal) that allows for templates to be created easily and efficiently by providing a simple and easy to use interface.

Example usage:

program Example;
uses
    Sempare.Template;
type
    TInformation = record
        name: string;
        favourite_sport : string;
    end;
begin
    var tpl := Template.parse('My name is <% name %>. My favourite sport is <% favourite_sport %>.');
    var information : TInformation;
    information.name := 'conrad';
    information.favourite_sport := 'ultimate';
    writeln(Template.eval(tpl, information));	
end.

In the example above, you can see that the '<%' start and '%>' end the scripting statement respectively. Within a scripting statement, you can reference variables, assign variables, use conditions, for and while loops, and include other templates.

NOTE In examples in this documentation I may use the latest Delphi syntax, e.g. inline variable declarations. This is not backward compatible as they were introduced in Delphi 10.2 and are used to shorten the code/examples being illustrated in the documentation. The codebase will attempt to be as backward compatible as possible.

Try the demo if you want to dive in quick and play with the template engine.

Quick tutorials on You Tube. The playlist has a few videos that are very short (most less than a minute - blink and they are done). You can drag the slider in the videos if you miss something or refer to the rest of the documentation.

• statements
  • if, elif, else statements
  • for and while statements
  • include statement
  • with statement
  • function/method calls
• expressions
  • simple expression evaluation (logical, numerical and string)
  • variable definition
  • functions and methods calls
  • dereference records, classes, arrays, JSON objects, TDataSet descendants and dynamic arrays
  • ternary operator
• safety
  • max run-time protection
• customisation
  • custom script token replacement
  • add custom functions
  • strip recurring spaces and new lines
• lazy template resolution
• parse time evaluation of expressions/statements
• allow use of custom encoding (UTF-8 with BOM, UTF-8 without BOM, ASCII, etc)
• extensibile RTTI interface to easily dereference classes and interfaces (current customisations for ITemplateVariables, TDictionary, TJsonObject)

The Sempare Template Engine is not intended to be a fully featured general purpose programming language such as PHP where the script itself could be a self contained programming language (but it does have most of the features).

Sempare Template Engine aims to provide just enough functionality to allow you to easily work with the 'view' aspects of a template. Any enhanced functionality required from the scripting environment should be provided by the custom functions written in Pascal.

This should work with most modern versions of Delphi.

Tests currently run using the DUnitX TestFramework.

An attempt has been made not to use the latest features to ease backward compatability. Although the development was done on Delphi 10.3.3, build and tests have been run on the following versions:

• Delphi XE 4
• Delphi XE 8
• Delphi 10.0 Seatle
• Delphi 10.1 Berlin
• Delphi 10.2 Tokyo
• Delphi 10.3.3 Rio
• Delphi 10.4 Sydney
• Delphi 10.4.1 Sydney

There should be no platform specific restrictions.

Have a look at Sempare.Template.Compiler.inc. The following defines can be defined if appropriate:

• SEMPARE_TEMPLATE_FIREDAC - to support tests for TDataSet
• SEMPARE_TEMPLATE_NO_INDY - if Indy is not present. This is used to access an html encoder if TNetEncoding is not available.

The Sempare Template Engine for Delphi can be installed via the Embarcadero GetIt manager

This will add the src folder to the search path so you can start working immediately.

The Sempare Template Engine for Delphi can be installed via the Delphinus package manager.

This will add the src folder to the search path so you can start working immediately.

Start by adding the src folder to the Delphi search path. Otherwise, there are some projects you can use:

Open Sempare.Template.Engine.Group.groupproj which will include:

• Sempare.Template.Pkg.dproj

  The core template project. (runtime)

• Sempare.Template.Tester.dproj

  100+ unit tests

• demo\VelocityDemo\Sempare.Template.Demo.dproj

  The velocity real-time demo.

I have not been able to test on XE5-XE7 as I don't have access to those compilers. If anyone in the community can help check the output of the tests, that will be extremely helpful.

You can raise issues on GitHub and they will be addressed based on priority.

Most features have some basic tests in place. If a bug is been discovered, please include a basic test/scenario replicating the issue if possible as this will ease the investigation process.

Please see the contibution terms and conditions

The Sempare Template Engien is dual-licensed. You may choose to use it under the restrictions of the GPL v3.0 at no cost to you, or you may purchase for user under the Sempare Limited Commercial License

The dual-licensing scheme allows you to test the library with no restrictions, but subject to the terms of the GPL. A nominal fee is requested to support the maintenance of the library if the product is to be used in commercial products. This support fee binds you to the commercial license, removing any of the GPL restrictions, and allowing you to use the library in your products as you will.

A commercial licence grants you the right to use Sempare Template in your own applications, royalty free, and without any requirement to disclose your source code nor any modifications to Sempare Templte to any other party. A commercial licence lasts into perpetuity, and entitles you to all future updates - free of charge.

A commercial licence is provided per developer developing applications that use the Sempare Template Engine. The initial cost is $70 per developer and includes first year of support. For support thereafter, at your discretion, a support fee of $30 per developer per year would be appreciated (the cost of a few cups of coffee). Please contact us for site license pricing.

Please send an e-mail to [email protected] to request an invoice which will contain the bank details.

Support and enhancement requests submitted by users that pay for support will be prioritised. New developments may incur additional costs depending on time required for implementation.