KTextTemplate

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

KDE's Doxygen guidelines are available online.