← Back to branch summary

~ubuntu-branches/ubuntu/trusty/grantlee/trusty

« back to all changes in this revision

Viewing changes to templates/lib/context.h

  • Committer: Bazaar Package Importer
  • Author(s): Scott Kitterman
  • Date: 2010-12-07 08:09:15 UTC
  • Revision ID: james.westby@ubuntu.com-20101207080915-ee6wcs8nv625su4b
Tags: 0.1.7-0ubuntu2
* Backport upstream commits 128272d4f65d7f02372cb606c148817c2f15a78d and
  5a71ed118f6fae67a4a26ab867ab7575e5a3e34c to moderate test requirements so
  it will build on armel
* Include missing grantlee_i18ntags.so and grantlee_mutabletags.so in
  libgrantlee-core0

Show diffs side-by-side

added added

removed removed

Lines of Context:
templates/lib/context.h
 
1
/*
 
2
  This file is part of the Grantlee template system.
 
3
 
 
4
  Copyright (c) 2009,2010 Stephen Kelly <steveire@gmail.com>
 
5
 
 
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.1 of the Licence, or (at your option) any later version.
 
10
 
 
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
  Lesser General Public License for more details.
 
15
 
 
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/>.
 
18
 
 
19
*/
 
20
 
 
21
#ifndef GRANTLEE_CONTEXT_H
 
22
#define GRANTLEE_CONTEXT_H
 
23
 
 
24
#include "abstractlocalizer.h"
 
25
#include "grantlee_core_export.h"
 
26
 
 
27
#include <QtCore/QVariantHash>
 
28
 
 
29
namespace Grantlee
 
30
{
 
31
 
 
32
class RenderContext;
 
33
 
 
34
class ContextPrivate;
 
35
 
 
36
/// @headerfile context.h grantlee/context.h
 
37
 
 
38
/**
 
39
  @brief The Context class holds the context to render a template with.
 
40
 
 
41
  For application developers, using the Context class is a matter of inserting keys and
 
42
  values as appropriate for rendering a template using the insert method.
 
43
 
 
44
  @code
 
45
    Template t = engine->newTemplate( "Name is {% name %} and age is {% age %}.", "some_template" );
 
46
 
 
47
    Context c1;
 
48
    c1.insert( "name", "Tom" );
 
49
    c1.insert( "age", 34 );
 
50
 
 
51
    Context c2;
 
52
    c2.insert( "name", "Harry" );
 
53
    c2.insert( "age", 43 );
 
54
 
 
55
    t->render(c1); // Returns "Name is Tom and age is 43."
 
56
    t->render(c2); // Returns "Name is Harry and age is 34."
 
57
  @endcode
 
58
 
 
59
  Note that one Template may be rendered multiple times with different contexts. Note also that any QVariant may be inserted
 
60
  into a Context object. Most commonly, QObjects will be used here.
 
61
  @see @ref custom_objects
 
62
 
 
63
  @section context_stack Context Stack.
 
64
 
 
65
  For template tag developers, some other Context API is relevant.
 
66
 
 
67
  It is possible to push and pop layers of context while a template is being rendered. This is useful if your template
 
68
  tag makes additional variables temporarily available in a part of a template. Template tags should only modify layers of context
 
69
  that they push themselves, and should pop any layers created before finishing its rendering step.
 
70
 
 
71
  See for example the @gr_tag{with} tag. In a template such as
 
72
  @code
 
73
    Some content
 
74
    {% with person.name|toUpper as lowerName %}
 
75
      Name is {% lowerName %}
 
76
    {% endwith %}
 
77
  @endcode
 
78
 
 
79
  In this case, lowerName is available in the context only between the @gr_tag{with} and @gr_tag{endwith} tags. The implementation of
 
80
  the @gr_tag{with} tag render method is:
 
81
 
 
82
  @code
 
83
    void WithNode::render( OutputStream *stream, Context *c )
 
84
    {
 
85
      c->push();
 
86
      // {% with m_filterExpression as m_name %}
 
87
      c->insert( m_name, m_filterExpression.resolve( c ) );
 
88
      m_list.render( stream, c );
 
89
      c->pop(); // The section of context defining m_name is removed.
 
90
    }
 
91
  @endcode
 
92
 
 
93
  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
 
94
  adding items to context and pop it when finished.
 
95
 
 
96
  @code
 
97
    Some content
 
98
    {% with "foo" as var %}
 
99
      Var is {% var %}         // Var is "foo"
 
100
      {% with "bar" as var %}
 
101
        Var is {% var %}       // Var is "bar"
 
102
      {% endwith %}
 
103
      Var is {% var %}         // Var is "foo"
 
104
    {% endwith %}
 
105
  @endcode
 
106
 
 
107
  @author Stephen Kelly <steveire@gmail.com>
 
108
*/
 
109
class GRANTLEE_CORE_EXPORT Context
 
110
{
 
111
public:
 
112
 
 
113
  /**
 
114
    Creates an empty context
 
115
  */
 
116
  Context();
 
117
  /**
 
118
    Sets every key in the hash as a property name with the variant as the value.
 
119
  */
 
120
  explicit Context( const QVariantHash &hash );
 
121
 
 
122
 
 
123
  /**
 
124
    Copy Constructor
 
125
  */
 
126
  Context( const Context &other );
 
127
 
 
128
  /**
 
129
    Assignmant operator
 
130
  */
 
131
  Context& operator =( const Context &other );
 
132
 
 
133
#ifndef Q_QDOC
 
134
  /**
 
135
    @internal
 
136
 
 
137
    Whether to automatically escape all context content. This is not usually used directly. Use the @gr_tag{autoescape} tag instead.
 
138
  */
 
139
  bool autoEscape() const;
 
140
 
 
141
  /**
 
142
    @internal
 
143
 
 
144
    Sets whether to automatically escape all context content. This is not usually used directly. Use the @gr_tag{autoescape} tag instead.
 
145
  */
 
146
  void setAutoEscape( bool autoescape );
 
147
#endif
 
148
  /**
 
149
    Destructor
 
150
  */
 
151
  ~Context();
 
152
 
 
153
  /**
 
154
    Returns the context object identified by the key @p str
 
155
  */
 
156
  QVariant lookup( const QString &str ) const;
 
157
 
 
158
  /**
 
159
    Insert the context object @p variant identified by @p name into the Context.
 
160
  */
 
161
  void insert( const QString &name, const QVariant &variant );
 
162
 
 
163
  /**
 
164
    Pushes a new context.
 
165
    @see @ref context_stack
 
166
  */
 
167
  void push();
 
168
 
 
169
  /**
 
170
    Pops the context.
 
171
    @see @ref context_stack
 
172
  */
 
173
  void pop();
 
174
 
 
175
#ifndef Q_QDOC
 
176
  /**
 
177
    @internal Returns the context hash at depth @p depth.
 
178
  */
 
179
  QVariantHash stackHash( int depth ) const;
 
180
 
 
181
  /**
 
182
    @internal
 
183
    Returns whether template being rendered is being mutated.
 
184
  */
 
185
  bool isMutating() const;
 
186
 
 
187
  /**
 
188
    @internal
 
189
    Sets whether template being rendered is being mutated to @p mutating.
 
190
  */
 
191
  void setMutating( bool mutating );
 
192
 
 
193
  /**
 
194
    @internal
 
195
  */
 
196
  void addExternalMedia( const QString &absolutePart, const QString &relativePart );
 
197
 
 
198
  /**
 
199
    @internal
 
200
  */
 
201
  void clearExternalMedia();
 
202
#endif
 
203
 
 
204
  /**
 
205
    Sets the localizer to be used.
 
206
 
 
207
    The Context takes ownerwhip of the localizer.
 
208
  */
 
209
  void setLocalizer( AbstractLocalizer::Ptr localizer );
 
210
 
 
211
  /**
 
212
    Returns the localizer currently in use.
 
213
  */
 
214
  AbstractLocalizer::Ptr localizer() const;
 
215
 
 
216
  /**
 
217
    Returns the external media encountered in the Template while rendering.
 
218
  */
 
219
  QList<QPair<QString, QString> > externalMedia() const;
 
220
 
 
221
  /**
 
222
    The type of urls to external media that should be put in the template.
 
223
  */
 
224
  enum UrlType
 
225
  {
 
226
    AbsoluteUrls,   ///< Absolute URLs should be put in the template.
 
227
    RelativeUrls    ///< Relative URLs should be put in the template.
 
228
  };
 
229
 
 
230
  /**
 
231
    Sets the type of external media URL to be used in the template to @p type.
 
232
    @see @ref media_finder_tag
 
233
  */
 
234
  void setUrlType( UrlType type );
 
235
 
 
236
  /**
 
237
    The type of URL used in the template.
 
238
  */
 
239
  UrlType urlType() const;
 
240
 
 
241
  /**
 
242
    Sets the relative path to external media to be used in templates to @p relativePath
 
243
    @see @ref media_finder_tag
 
244
  */
 
245
  void setRelativeMediaPath( const QString &relativePath );
 
246
 
 
247
  /**
 
248
    The relative path to external media to be used in templates.
 
249
  */
 
250
  QString relativeMediaPath() const;
 
251
 
 
252
  /**
 
253
   * Returns a modifiable RenderContext for the Node @p scopeNode. This may be used to make
 
254
   * Template rendering threadsafe so that render state does not need to be stored in the
 
255
   * Node implementation itself.
 
256
   */
 
257
  RenderContext* renderContext() const;
 
258
 
 
259
private:
 
260
  Q_DECLARE_PRIVATE( Context )
 
261
  ContextPrivate * const d_ptr;
 
262
};
 
263
 
 
264
}
 
265
 
 
266
#endif
 
267