KTextTemplate::Context Class

Detailed Description

For application developers, using the Context class is a matter of inserting keys and values as appropriate for rendering a Template using the insert method.

auto t = engine->newTemplate(
    "Name is {% name %} and age is {% age %}.", "some_template" );

Context c1;
c1.insert( "name", "Tom" );
c1.insert( "age", 34 );

Context c2;
c2.insert( "name", "Harry" );
c2.insert( "age", 43 );

t->render(c1); // Returns "Name is Tom and age is 43."
t->render(c2); // Returns "Name is Harry and age is 34."

Note that one Template may be rendered multiple times with different contexts. Note also that any QVariant may be inserted into a Context object. Most commonly, QObjects will be used here.

Context Stack

For template tag developers, some other Context API is relevant.

It is possible to push and pop layers of context while a template is being rendered. This is useful if your template tag makes additional variables temporarily available in a part of a template. %Template tags should only modify layers of context that they push themselves, and should pop any layers created before finishing its rendering step.

See for example the {% with %} tag. In a template such as

Some content
{% with person.name|toUpper as lowerName %}
  Name is {% lowerName %}
{% endwith %}

In this case, lowerName is available in the context only between the {% with %} and {% endwith %} tags. The implementation of the {% with %} tag render method is:

void WithNode::render( OutputStream *stream, Context *c ) const
{
  c->push();
  // {% with m_filterExpression as m_name %}
  c->insert( m_name, m_filterExpression.resolve( c ) );
  m_list.render( stream, c );
  c->pop(); // The section of context defining m_name is removed.
}

Note that a Context may temporarily override a variable in a parent context. This is why it is important to push a new context when adding items to context and pop it when finished.

Some content
{% with "foo" as var %}
  Var is {% var %}         // Var is "foo"
  {% with "bar" as var %}
    Var is {% var %}       // Var is "bar"
  {% endwith %}
  Var is {% var %}         // Var is "foo"
{% endwith %}