template_engine #

A flexible Dart library to parse templates and render output such as:

• Html
• Programming code
• Markdown
• Xml, Json, Yaml
• Etc...

Features #

• Template expressions that can contain (combinations of):
  • Data types
  • Constants
  • Variables
  • Operators
  • Functions
• Functions to import:
  • Pure files (to be imported as is)
  • Template files (to be parsed and rendered)
  • XML files (to be used as a data source)
  • JSON files (to be used as a data source)
  • YAML files (to be used as a data source)
• All of the above can be customized or you could add your own.

Getting started #

See: Installing

Examples #

import 'package:shouldly/shouldly.dart';
import 'package:template_engine/template_engine.dart';

Future<void> main() async {
  var engine = TemplateEngine();
  var parseResult = await engine.parseText('Hello {{name}}.');
  var renderResult = await engine.render(parseResult, {'name': 'world'});
  renderResult.text.should.be('Hello world.');
}

Note the documentation of the template_engine package was generated by itself. See: tool/generate_documentation.dart

For more see: Examples

Tags #

Tags are specific texts in templates that are replaced by the TemplateEngine with other information.

A tag:

• Starts with some bracket and/or character combination, e.g.: {{
• Followed by some contents
• Ends with some closing bracket and/or character combination, e.g.: }}

A tag example: {{customer.name}}

By default the TemplateEngine tags start with {{ and end with }} brackets, just like the popular template engines Mustache and Handlebars.

You can also define alternative tag brackets in the TemplateEngine constructor parameters. See TemplateEngine.tagStart and TemplateEngine.tagEnd.

It is recommended to use a start and end combination that is not used elsewhere in your templates, e.g.: Do not use < > as tag start and end if your template contains HTML or XML.

The TemplateEngine comes with default tags. You can replace or add your own tags by manipulating the the TemplateEngine.tags field.

Expression Tag #

Data types in tag expressions #

A data type defines what the possible values an expression, such as a variable, operator or a function call, might take.

The TemplateEngine supports several default DataTypes.

Custom DataTypes #

You can adopt existing DataTypes or add your own custom DataTypes by manipulating the TemplateEngine.dataTypes field. See Example.

Available DataTypes #

String Data Type #

Number Data Type #

Boolean Data Type #

Constants in tag expressions #

A Constant is a value that does not change value over time.

The TemplateEngine comes with several mathematical constants.

Custom Constants #

You can create and add your own Constants by manipulating the TemplateEngine.constants field. See Example.

Available Constants #

e Constant #

ln10 Constant #

ln2 Constant #

log10e Constant #

log2e Constant #

pi Constant #

Variables in tag expressions #

A Variable is a named container for some type of information (like number, boolean, String etc...)

• Variables are stored as key, value pairs in a dart Map<String, Object> where:
  • String=Variable name
  • Object=Variable value
• Variables can be used in a tag expression
• Initial variable values are passed to the TemplateEngine.render method
• Variables can be modified during rendering

The variable name:

• must be unique and does not match a other [Tag] syntax
• must start with a letter, optionally followed by letters and or digits
• is case sensitive (convention: use camelCase)

Variables can be nested. Concatenate variable names separated with dot's to get the variable value of a nested variable.

E.g.:
Variable map: {'person': {'name': 'John Doe', 'age',30}}
Variable Name person.name: refers to the variable value of 'John Doe'

Examples:

• Variable Example
• Nested Variable Example

Functions in tag expressions #

A function is a piece of dart code that performs a specific task. So a function can basically do anything that dart code can do.

A function can be used anywhere in an tag expression. Wherever that particular task should be performed.

An example of a function call: cos(pi) Should result in: -1

Function & Parameter & argument names:

• are case sensitive
• must start with a lower case letter, optionally followed by (lower or upper case) letters and or digits.
• conventions: use lowerCamelCase
• must be unique and does not match a other [Tag] syntax

Parameters vs Arguments

• Parameters are the names used in the function definition.
• Arguments are the actual values passed when calling the function.

Parameters:

• A function can have zero or more parameters
• Parameters are defined as either mandatory or optional
• Optional parameters can have a default value

Arguments:

• Multiple arguments are separated with a comma, e.g. single argument: cos(pi) multiple arguments: volume(10,20,30)
• There are different types of arguments
  • Positional Arguments: These are passed in the order the function defines them. e.g.: volume(10, 20, 30)
  • Named Arguments: You can specify which parameter you're assigning a value to, regardless of order. e.g.: volume(l=30, h=10, w=20)
• Arguments can set a parameter only once
• You can mix positional arguments and named arguments, but positional arguments must come first
• Named arguments remove ambiguity: If you want to skip an optional argument or specify one out of order, you must name it explicitly

Argument values:

• must match the expected parameter type. e.g. area(length='hello', width='world') will result in a failure
• may be a tag expression such as a variable, constant, operation, function, or combination. e.g. cos(2*pi)

Custom Functions #

You can use prepackaged [template_engine] functions or add your own custom functions by manipulating the TemplateEngine.functionGroups field. See Example.

Available Functions #

Math Functions #

exp Function #

log Function #

sin Function #

asin Function #

cos Function #

acos Function #

tan Function #

atan Function #

sqrt Function #

round Function #

String Functions #

length Function #

Documentation Functions #

tagDocumentation Function #

dataTypeDocumentation Function #

constantDocumentation Function #

functionDocumentation Function #

operatorDocumentation Function #

exampleDocumentation Function #

Path Functions #

templateSource Function #

Import Functions #

importTemplate Function #

importPure Function #

importJson Function #

importXml Function #

importYaml Function #

Operator #

An operator behaves generally like functions, but differs syntactically or semantically.

Common simple examples include arithmetic (e.g. addition with +) and logical operations (e.g. &).

An operator can be used anywhere in an tag expression wherever that particular Operator should be performed.

The TemplateEngine supports several standard operators.

Custom Operators #

You can adopt existing operators or add your own custom operators by manipulating the TemplateEngine.operatorGroups field. See custom_operator_test.dart.

Available Operators #

Parentheses #

Parentheses Operator ()

Prefixes #

Positive Operator +

Negative Operator -

Not Operator !

Multiplication #

Caret Operator ^

Multiply Operator *

Divide Operator /

Modulo Operator %

And Operator &

Additions #

Add Operator +

Subtract Operator -

Or Operator |

Comparisons #

Equals Operator ==

Not Equals Operator !=

Greater Than Or Equal Operator >=

Greater Than Operator >

Less Than Or Equal Operator <=

Less Than Operator <

Assignment #

Assignment Operator =