Nuria::TemplateEngine Class Reference

Templating engine for rendering Twig code. More...

#include <templateengine.hpp>

Inheritance diagram for Nuria::TemplateEngine:

Public Member Functions
	TemplateEngine (QObject *parent=0)
	~TemplateEngine () override
void	addFunction (const QString &name, const Callback &function, bool isConstant=false)
int	currentCacheSize () const
void	flushCache ()
bool	hasFunction (const QString &name)
bool	isProgramOutdated (const TemplateProgram &program)
bool	isTemplateInCache (const QString &templateName) const
TemplateError	lastError () const
TemplateLoader *	loader () const
QLocale	locale () const
int	maxCacheSize () const
void	mergeValues (const QVariantMap &map)
TemplateProgram	program (const QString &templateName)
QString	render (const QString &templateName)
void	setLoader (TemplateLoader *loader)
void	setLocale (const QLocale &locale)
void	setMaxCacheSize (int size)
void	setValue (const QString &name, const QVariant &value)
void	setValues (const QVariantMap &map)
QVariant	value (const QString &name) const
QVariantMap	values () const

Detailed Description

Templating engine for rendering Twig code.

This is a templating engine capable of rendering Twig code. Twig is a template language popular in PHP and is developed by SensioLabs at http://twig.sensiolabs.org/

It features a rich amount of possibilities to efficiently write templates especially for HTML pages, though in its core it's target agnostic, meaning you could also e.g. write templates for INI files.

For a beginners tutorial, please go to http://twig.sensiolabs.org/doc/templates.html

Note

The implementation is based on Twig version 1.16.0

Features

Supported features:

• Twig command blocks, expansions and comments
• Flow control and loops (if, for)
• All operators
• All tags, commands, filters and functions if not noted otherwise
• Accessing fields and methods in maps, lists, QObjects and structures registered to the Nuria meta system

Unsupported features are:

• The use command
• verbatim and sandbox blocks.
• The convert_encoding() filter. Everything is UTF-8.
• macros
• attribute() - Please use the square-braces syntax instead.
• The date_modify filter.
• The format filter.
• The raw filter.
• The constant() test function.
• The sameas/same as test function is obsolete, as == is the same.
• Binary operations
• The flush command, as it wouldn't do anything at all.
• The source() function.
• The slice() shorthand notation "[x:y]"

Implementation differences:

• Input is always considered to be UTF-8
• Template names in include and extends commands must be constant
• Include and extends only support the basic form of {% include/extends "foo" %}
• The date filter expects a QDateTime or string in the Qt::TextDate format in the C locale.
• The date filter does not support the timezone argument.
• The format string for the date filter is optional. It defaults to the locale long format.
• The json_encode filter does not support additional arguments.
• The url_encode filter does not support the 'rawurlencode' bool argument.
• The reverse filter doesn't support maps.
• "!", "&&" and "||" are aliases for "not", "and" and "or" respectively.
• The == operator is equivalent to PHPs ===.
• The matches test uses QRegularExpression syntax.
• The 'loop.parent' variable inside for-loops only contains a 'loop' variable.

Performance

The internal AST is not transformed to C++ nor JIT'ed. The only real but powerful optimization done is constant folding. Thus, Twig code like

{% if 1 > 2 %}
Foo
{% else %}
Bar
{% endif %}

Is optimized to simply "Bar". If a template were to only consist out of such constant constructs, it is folded into a single QString. Thus, to use TemplateEngine as constant folding calculator, you could do:

nDebug() << TemplateEngine ().render ("{{ 1 + 2 }}");

Caching of programs

Another optimization worth noting is that programs are cached. You can control this behaviour using setMaxCacheSize().

Variable inheritance and strictness

This engine will always, even if only internally, generate instances of TemplateProgram. To provide a balanced mix between ease of use and performance, this class can pass on variables to all generated programs.

In simpler words, all variables you set to a TemplateEngine will be automatically set in all generated programs. Changing variables of the engine will not affect already generated programs.

You can use this to e.g. set company or product specific variables which are used in all templates and set template-specific variables in the TemplateProgram.

Please note that this implementation of a Twig engine is pretty strict when it comes to variables and functions. All functions referenced by a template must be present when the template is loaded. Variables must be present upon rendering.

If a function or a variable is missing, by default, a error will be issued and the operation is cancelled.

Variable access

The engine supports all C++ POD types and QVariantList and QVariantMap, including all types being accessible through QSequentialIterable and QAssociativeIterable.

QObjects are supported too, but only access to properties is provided. Objects registered to the Nuria meta system support access to fields and methods, though the first method is always chosen when the method is overloaded.

Custom functions

It's possible to register custom functions using the addFunction() method. It's also possible for the TemplateEngine version to define a function as constant, meaning that for the same arguments they produce the same result. This will enable the internal compiler to optimize functions, which are constant, meaning they'll be invoked at compile-time.

This can also be used to register custom filters. A filter will simply be passed the result of the previous statement as first argument. All additional arguments are then passed after that.

Example: "foo|bar(1,2)" is equivalent to "bar(foo,1,2)".

Locale

Locale-dependent functions will use the application-wide default locale by default. You can also set this using setLocale() on the template engine or program.

Warning

setLocale() has no effect on cached programs. To force this, call flushCache() afterwards.

Constructor & Destructor Documentation

Nuria::TemplateEngine::TemplateEngine ( QObject *  parent = 0 )

explicit

Constructor.

Nuria::TemplateEngine::~TemplateEngine ( )

override

Destructor.

Member Function Documentation

void Nuria::TemplateEngine::addFunction	(	const QString &	name,
		const Callback &	function,
		bool	isConstant = false
	)

Adds function, making it known as name. Functions that are constant, meaning that for the same arguments they always output the same result, should set isConstant to true to make it subject for constant folding during the compilation step.

Note

Built-in functions can not be overridden.

int Nuria::TemplateEngine::currentCacheSize

(

)

const

Returns the amount of currently cached programs.

void Nuria::TemplateEngine::flushCache

(

)

Clears the program cache.

bool Nuria::TemplateEngine::hasFunction

(

const QString &

name

)

Returns true, if there's a user-defined function called name.

bool Nuria::TemplateEngine::isProgramOutdated

(

const TemplateProgram &

program

)

Checks if program is outdated, meaning, if the templates it consists of were modified after program was compiled.

bool Nuria::TemplateEngine::isTemplateInCache

(

const QString &

templateName

)

const

Returns true if templateName is already cached.

TemplateError Nuria::TemplateEngine::lastError

(

)

const

Returns the last occured error.

Note

render() clears this.

TemplateLoader* Nuria::TemplateEngine::loader

(

)

const

Returns the used template loader.

QLocale Nuria::TemplateEngine::locale

(

)

const

Returns the default locale for programs. If not set, this is equivalent to the default application-wide QLocale.

int Nuria::TemplateEngine::maxCacheSize

(

)

const

Returns the maximum count of programs to be cached.

void Nuria::TemplateEngine::mergeValues

(

const QVariantMap &

map

)

Merges map with the internal value map.

All values of map will be inserted into the internal map, overriding the internal one if a key already exists.

TemplateProgram Nuria::TemplateEngine::program

(

const QString &

templateName

)

Loads and compiles a Twig template called templateName and returns a TemplateProgram, which can be cached by the user if wanted. The program will be prepopulated with the variables set to the engine.

Note

A TemplateProgram is not dependent on a TemplateEngine.

Caching does not interfer with the variable being passed on to the program!

QString Nuria::TemplateEngine::render

(

const QString &

templateName

)

Loads the template templateName and renders it into a string. If templateName is unknown, an empty string is returned.

Same as:

myTemplateEngine->program ("foo").render ();

void Nuria::TemplateEngine::setLoader

(

TemplateLoader *

loader

)

Replaces the currently used template loader. Ownership of loader is transferred to the environment.

void Nuria::TemplateEngine::setLocale

(

const QLocale &

locale

)

Sets the locale for programs.

void Nuria::TemplateEngine::setMaxCacheSize

(

int

size

)

Resizes the internal cache to size. If size is 0, the cache is effectively disabled.

void Nuria::TemplateEngine::setValue	(	const QString &	name,
		const QVariant &	value
	)

Inserts value as name into the value map of the engine.

void Nuria::TemplateEngine::setValues

(

const QVariantMap &

map

)

Sets the values to map, replacing the internal one.

QVariant Nuria::TemplateEngine::value

(

const QString &

name

)

const

Returns the value of name.

QVariantMap Nuria::TemplateEngine::values

(

)

const

Returns the map of values to render templates.

---

The documentation for this class was generated from the following file:

• templateengine.hpp