Nuria::TemplateEngine Class Reference

#include <templateengine.hpp>

Public Member Functions
	TemplateEngine (const QString &templData=QString())
	TemplateEngine (QIODevice *readDevice)
QString	templateData () const
void	bind (const QString &name, const QVariant &data)
void	bind (const QString &name, QObject *object)
void	unbind (const QString &name)
void	clearBindings ()
void	setTemplateData (const QString &templData)
QString	generate ()

Static Public Member Functions
static QString	generate (const QString &templateData, const QVariantMap &variables)

Detailed Description

This class provides a simple to use templating engine for text data.

Variables

Data is read as byte stream. To access bound variables use: <=Variablename>

A bound variable may be of any type that can be converted to a QString. Also supported are lists and maps which are registered to the Nuria::Variant system. Variable names may consist of the following characters: a-z, 0-9, "_", "-" and ".". Names are always matched case-sensitive!

Working with lists

Lists support direct access of elements (Just like maps do). To directly access an item at a known index write the index after a point: <=List.123>

Note

Valid indexes are: 0 <= Index < Length of list

To access the first or last item in a list, use "first" or "last" respectively: <=List.first> ... <=List.last>

To access an item at a random index, use "random": <=List.random>

Note

To insert the length of a list use the Length modifier.

Modifiers

A modifier is a special command which evaluates a block only if its statement is true. A modifier always begins with "%" instead of "=" to be easily distinguishable. Most modifiers can have an "<%else>" block which are evaluated when the statement turned out to be false. A block is always ended with "<%%>". The modifiers which can have an else block can also be negated using the negation operator "!" written before the modifier itself.
Example:

Available languages:
<%!Empty:Langs>
<%Each:Langs>"<=Value>" <%%>
<%else>
None!
<%%>

The example above first checks if "Langs" (which is a list) is not empty. If it's not, it will iterate over all elements writing the value of each one in quotation marks. If the list is empty, it will simply output "None!".

The 'Each' modifier

As mentioned above, you can also bind lists and maps. This way you can easily have repetitive elements in your output. To do so use a 'each' block: <Each:Variable>...<%%>

Note

Blocks can be nested.

Blocks always end with "<%%>". Inside an each block use Key and Value to access the key of a map or the value of a map or list respectively.

Each does not support an else block nor does it support the negation operator!

QVariantMap and QObject

You can also directly access values of a bound QVariantMap and a property of a bound QObject* by delimting the the variable name and the property name with a dot (".") <=ObjectOrMap.Property> It is also possible to call methods in a bound QObject* by appending "()" at the end of the property name. Note that you can only invoke public slots and that the slot can't take any argument. <=Object.slot()>

Note

The object must live in the same thread as the caller as the slot is invoked using a Qt::DirectConnection!

You can apply all modifiers to all variable types. This also applies to objects, maps and lists.

For example, you have a bound QObject "object" with a slot named "users()" which when called returns a list of strings. You can output all elements as you'd expect using Each: <Each:object.users()><=Value><%%>

The 'Has' modifier

If you need to check if there is a bound variable with a specific name you can use the Has modifier: Foo: <Has:Foo><=Foo><%%> Inside a 'Has' block, you can use a 'else' marker to output data if the 'Has' condition fails: Foo: <Has:Foo><=Foo><else>Not set<%%>

The 'Empty' modifier

Some times you don't care if a variable really exists or not. All you want to know if a variable is empty (as in: Is defined (or not) and contains data). For this use-case use Empty: Your name <Empty:Name>is empty<else>is set<%%>

Inline templates

If you need to evaluate a variable like a template, use "$": <$Translation.Welcome> The variable is executed in the current scope and thus has access to all bound variables.

Note

The variable must be a string. If you need to execute a list or map combine it with Each.

You're free to call inline templates redundant. For security reasons, TemplateEngine allows a recursion depth of up to 50 calls. This should be enough for any normal use-case and defend against attacks.

Additional modifiers for maps and lists

Note

This section refers to Each blocks. Often you need to know additional data when working with lists. For example you need to know the current index. Or the total number of items. To handle such situations this engine provides two special variables: CurrentIndex and TotalLength. These variables represent the current item index in a list or map and the total item count respectively. These variables are also available in sub-scopes. Both refer to the next Each block. So, if you nest multiple Each blocks, you only have access to the value from the highest block. You can't access the value of parent blocks.

Beside these two special variables, various special modifiers are provided:

• A FirstItem block is only executed when this is the first item.
• A LastItem block is only executed when this is the last item.
• A EvenItem block is only executed when the current index is even.
• A OddItem block is only executed when the current index is odd.

<%Each:List>
<=CurrentIndex>: <=Value>
(<%FirstItem>First<%%> <%LastItem>Last<%%> <%OddItem>Odd<%%> <%EvenItem>Even<%%>)<br />
<%%>

The 'Length' modifier

The Length modifier lets you access the length of strings and the item count of lists and maps. This modifier is special as it only expands to an integer, and thus doesn't open a new block and can't be negated. It is used with the assignment operator "=": <=Length:StringOrMap>

Constructor & Destructor Documentation

Nuria::TemplateEngine::TemplateEngine

(

const QString &

templData = QString()

)

Constructs a template engine instance with templateData set to templData.

Nuria::TemplateEngine::TemplateEngine

(

QIODevice *

readDevice

)

Constructs a template engine instance. The templateData is read from readDevice. Data is interpreted as UTF-8. The readDevice must be open and readable. All data will be read out of it. The device won't be closed afterwards and ownership will remain at the caller.

Note

readDevice can be closed after the instance has been created.

Member Function Documentation

void Nuria::TemplateEngine::bind	(	const QString &	name,
		const QVariant &	data
	)

Binds variable name to data.

void Nuria::TemplateEngine::bind	(	const QString &	name,
		QObject *	object
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Convenience overload for binding QObjects.

void Nuria::TemplateEngine::clearBindings

(

)

Clears the list of bound variables.

QString Nuria::TemplateEngine::generate

(

)

Generates the result of the template.

static QString Nuria::TemplateEngine::generate ( const QString &  templateData, const QVariantMap &  variables  )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Nuria::TemplateEngine::setTemplateData

(

const QString &

templData

)

Sets the template data.

Note

This won't clean bound variables.

QString Nuria::TemplateEngine::templateData

(

)

const

Returns the current template data. Is empty by default.

void Nuria::TemplateEngine::unbind

(

const QString &

name

)

Removes the variable name.

---

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

• templateengine.hpp