2
This file is part of the Grantlee template system.
4
Copyright (c) 2009,2010 Stephen Kelly <steveire@gmail.com>
6
This library is free software; you can redistribute it and/or
7
modify it under the terms of the GNU Lesser General Public
8
License as published by the Free Software Foundation; either version
9
2 of the Licence, or (at your option) any later version.
11
This library is distributed in the hope that it will be useful,
12
but WITHOUT ANY WARRANTY; without even the implied warranty of
13
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
Library General Public License for more details.
16
You should have received a copy of the GNU Lesser General Public
17
License along with this library. If not, see <http://www.gnu.org/licenses/>.
21
#ifndef GRANTLEE_CONTEXT_H
22
#define GRANTLEE_CONTEXT_H
24
#include <QtCore/QVariantHash>
26
#include "grantlee_core_export.h"
33
/// @headerfile context.h grantlee/context.h
36
@brief The Context class holds the context to render a template with.
38
For application developers, using the Context class is a matter of inserting keys and
39
values as appropriate for rendering a template using the insert method.
42
Template t = engine->newTemplate( "Name is {% name %} and age is {% age %}.", "some_template" );
45
c1.insert( "name", "Tom" );
46
c1.insert( "age", 34 );
49
c2.insert( "name", "Harry" );
50
c2.insert( "age", 43 );
52
t->render(c1); // Returns "Name is Tom and age is 43."
53
t->render(c2); // Returns "Name is Harry and age is 34."
56
Note that one Template may be rendered multiple times with different contexts. Note also that any QVariant may be inserted
57
into a Context object. Most commonly, QObjects will be used here.
58
@see @ref custom_objects
60
@section context_stack Context Stack.
62
For template tag developers, some other Context API is relevant.
64
It is possible to push and pop layers of context while a template is being rendered. This is useful if your template
65
tag makes additional variables temporarily available in a part of a template. Template tags should only modify layers of context
66
that they push themselves, and should pop any layers created before finishing its rendering step.
68
See for example the @gr_tag{with} tag. In a template such as
71
{% with person.name|toUpper as lowerName %}
72
Name is {% lowerName %}
76
In this case, lowerName is available in the context only between the @gr_tag{with} and @gr_tag{endwith} tags. The implementation of
77
the @gr_tag{with} tag render method is:
80
void WithNode::render( OutputStream *stream, Context *c )
83
// {% with m_filterExpression as m_name %}
84
c->insert( m_name, m_filterExpression.resolve( c ) );
85
m_list.render( stream, c );
86
c->pop(); // The section of context defining m_name is removed.
90
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
91
adding items to context and pop it when finished.
95
{% with "foo" as var %}
96
Var is {% var %} // Var is "foo"
97
{% with "bar" as var %}
98
Var is {% var %} // Var is "bar"
100
Var is {% var %} // Var is "foo"
104
@author Stephen Kelly <steveire@gmail.com>
106
class GRANTLEE_CORE_EXPORT Context
111
Creates an empty context
115
Sets every key in the hash as a property name with the variant as the value.
117
explicit Context( const QVariantHash &hash );
123
Context( const Context &other );
128
Context& operator =( const Context &other );
134
Whether to automatically escape all context content. This is not usually used directly. Use the @gr_tag{autoescape} tag instead.
136
bool autoEscape() const;
141
Sets whether to automatically escape all context content. This is not usually used directly. Use the @gr_tag{autoescape} tag instead.
143
void setAutoEscape( bool autoescape );
151
Returns the context object identified by the key @p str
153
QVariant lookup( const QString &str ) const;
156
Insert the context object @p variant identified by @p name into the Context.
158
void insert( const QString &name, const QVariant &variant );
161
Pushes a new context.
162
@see @ref context_stack
168
@see @ref context_stack
174
@internal Returns the context hash at depth @p depth.
176
QVariantHash stackHash( int depth ) const;
180
Returns whether template being rendered is being mutated.
182
bool isMutating() const;
186
Sets whether template being rendered is being mutated to @p mutating.
188
void setMutating( bool mutating );
193
void addExternalMedia( const QString &absolutePart, const QString &relativePart );
198
void clearExternalMedia();
202
Returns the external media encountered in the Template while rendering.
204
QList<QPair<QString, QString> > externalMedia() const;
207
The type of urls to external media that should be put in the template.
211
AbsoluteUrls, ///< Absolute URLs should be put in the template.
212
RelativeUrls ///< Relative URLs should be put in the template.
216
Sets the type of external media URL to be used in the template to @p type.
217
@see @ref media_finder_tag
219
void setUrlType( UrlType type );
222
The type of URL used in the template.
224
UrlType urlType() const;
227
Sets the relative path to external media to be used in templates to @p relativePath
228
@see @ref media_finder_tag
230
void setRelativeMediaPath( const QString &relativePath );
233
The relative path to external media to be used in templates.
235
QString relativeMediaPath() const;
238
Q_DECLARE_PRIVATE( Context )
239
ContextPrivate * const d_ptr;
added
removed
corelib/context.h
