Home - nortal/Utilities.TextTemplating GitHub Wiki

Overview

This assembly provides a text template processing engine capable of merging data from objects (the model) to a text-based prepared template (text, html, xml, ..).

Goals

  1. Trivial for developers to use in code
    1. Any .net object must be usable as model without any modification
  2. Simple also for non-developers to read and write simple templates
  3. Syntax must be configurable, localizable for different languages.
  4. Must support hierarchical model, conditional blocks, loops, subtemplates.

Other considerations

This templating tool must be simple and do only what it's meant for - building text documents from model object. It is NOT meant as universal language.

Usage and performance considerations:

  • This tool must be lightweight, single-dll, and have no runtime dependencies outside core .Net framework.
  • Templates are assumed to be relatively small (usually <<1MB) and can always be fully parsed before generating documents from models.
  • Same template may be used to generate more than 1 document, parse tree reuse must be possible.

Template syntax

Syntax vision & principles

Each template mimics as much as possible the desired output document (text, html, csv, ..) but may additionally contain special placeholders or commands to inject values from model to template. Each command is recognizable by a command mode start and end marker (configurable, by default '' and ''). Example:

This is output text [SomeCommand](/nortal/Utilities.TextTemplating/wiki/SomeCommand) output text continues here.

Commands can be simple paths to a value within model in which case the entire command is simply replaced by given value. Model path may traverse to sub-objects. Example:

Hello, [MyModel.Caller.Name](/nortal/Utilities.TextTemplating/wiki/MyModel.Caller.Name)!!!

Another type of commands are functions which can perform control logic on template elements: if, loops, etc. Functions are recognizable for parenthesis which may contain parameters to given command, either from model or as constants. Also, commands may have a matching end-command declaring a scope of template text for that command. Example:

[if(Mymodel.MyCondition)](/nortal/Utilities.TextTemplating/wiki/if(Mymodel.MyCondition))
     Show this
[endif(Mymodel.MyCondition)](/nortal/Utilities.TextTemplating/wiki/endif(Mymodel.MyCondition))

No arithmetic or other expressions are supported in template, except the fixed set of simple template control commands. Complex expressions can be built in model, and used in template via model path commands.

Command start and end tag, as well as all command names are configurable in runtime.

Syntax in ABNF-like notation

Template = [Text] *(Command [Text])
Command = TagStart LWSP (Function / ModelPath) LWSP TagEnd
Text = 1*CHAR ; exception: cannot contain start or end tags.
ModelPath = 1*(ALPHA / DIGIT / ".")  ;; model path does not contain parenthesis.
Function = FunctionName LWSP "(" LWSP [FunctionParameters LWSP] ")"  ; function is recognizable by parenthesis
FunctionName = 1*ALPHA ;
FunctionParameters = FunctionParameter *( LWSP "," LWSP FunctionParameter)  ; N comma-separated params
FunctionParameter = 1*CHAR

; configurable terminals
TagStart = 1*CHAR ; additional limitations apply to avoid ambiguity
TagEnd = 1*CHAR ; additional limitations apply to avoid ambiguity