KTextTemplate

engine.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_ENGINE_H
11#define KTEXTTEMPLATE_ENGINE_H
12
13#include "template.h"
14#include "templateloader.h"
15
16namespace KTextTemplate
17{
18class TagLibraryInterface;
19
20class EnginePrivate;
21
22/// @headerfile engine.h <KTextTemplate/Engine>
23
24/**
25 @brief **%KTextTemplate::Engine** is the main entry point for creating %KTextTemplate
26 Templates.
27
28 The **%KTextTemplate::Engine** is responsible for configuring and creating Template
29 objects. In typical use, one or more AbstractTemplateLoader objects will be
30 added to the Engine to load template objects, and plugin directories will be
31 set to enable finding template tags and filters.
32
33 @code
34 auto engine = new Engine();
35
36 auto loader = QSharedPointer<FileSystemTemplateLoader>::create();
37 loader->setTemplateDirs( {"/usr/share/myapp/templates"} );
38 engine->addTemplateLoader( loader );
39
40 engine->addPluginPath( "/usr/lib/myapp" );
41
42 auto template1 = engine->newTemplate( "Template content", "template name" );
43
44 auto template2 = engine->loadByName( "templatefile.html" );
45 @endcode
46
47 Once it is configured, the **%Engine** can be used to create new templates by
48 name by loading the templates with the @ref loadByName method, or by defining
49 the content in the @ref newTemplate method.
50
51 By default the builtin tags and filters distributed with %KTextTemplate are
52 available in all templates without using the @gr_tag{load} tag in the
53 template. These pre-loaded libraries may be configured if appropriate to the
54 application. For example, an application which defines its own tags and
55 filters may want them to be always available, or it may be desirable to
56 restrict the features available to template authors by removing built in
57 libraries.
58
59 Different **%Engine** objects can be used to create templates with differing
60 configurations.
61
62 @section smart_trim Insignificant whitespace
63
64 The output of rendering a template depends on the content of the template. In
65 some cases when generating content in which whitespace is significant, this
66 can have undesired effects. For example, given a template to generate C++ code
67 like:
68
69 @verbatim
70 class MyClass {
71 {# This loop creates the #}
72 {# methods in the class #}
73 {% for method in methods %}
74 {% if method.hasDox %}
75 {{ method.dox }}
76 {% endif %}
77 {{ method.signature }}
78 {% endfor %}
79 };
80 @endverbatim
81
82 The output would have a lot of whitespace which is not necessarily wanted.
83
84 @code
85 class MyClass {
86
87
88
89
90 void foo() const;
91
92 };
93 @endcode
94
95 It is possible to strip insignificant whitespace by enabling the smartTrim
96 feature with @ref setSmartTrimEnabled. When enabled the output will not
97 contain a newline for any line in the template which has only one token of
98 template syntax, such as a comment, tag or variable.
99
100 @code
101 class MyClass {
102
103 void foo() const;
104 };
105 @endcode
106
107 @author Stephen Kelly <steveire@gmail.com>
108*/
109class KTEXTTEMPLATE_EXPORT Engine : public QObject
110{
111 Q_OBJECT
112public:
113 /**
114 Constructor
115 */
116 Engine(QObject *parent = {});
117
118 /**
119 Destructor.
120 */
121 ~Engine() override;
122
123 /**
124 Returns the TemplateLoaders currently configured on the **%Engine**.
125 */
127
128 /**
129 Adds @p loader to the TemplateLoaders currently configured on
130 the **%Engine**.
131 */
132 void addTemplateLoader(QSharedPointer<AbstractTemplateLoader> loader);
133
134 /**
135 Sets the plugin dirs currently configured on the **%Engine** to @p dirs.
136
137 @warning This overwrites the default paths. You normally want
138 @ref addPluginPath.
139
140 @see @ref finding_plugins
141 */
142 void setPluginPaths(const QStringList &dirs);
143
144 /**
145 Prepend @p dir to the list of plugin dirs.
146 */
147 void addPluginPath(const QString &dir);
148
149 /**
150 Removes all instances of @p dir from the list of plugin dirs.
151 */
152 void removePluginPath(const QString &dir);
153
154 /**
155 Returns the currently configured plugin dirs
156 */
157 QStringList pluginPaths() const;
158
159 /**
160 Returns a URI for a media item with the name @p name.
161
162 Typically this will be used for images. For example the media URI for the
163 image <tt>"header_logo.png"</tt> may be
164 <tt>"/home/user/common/header_logo.png"</tt> or
165 <tt>"/home/user/some_theme/header_logo.png"</tt>
166 depending on the @ref templateLoaders configured.
167
168 This method will not usually be called by application code. To load media
169 in a template, use the @gr_tag{media_finder} template tag.
170 */
171 std::pair<QString, QString> mediaUri(const QString &fileName) const;
172
173 /**
174 Load the Template identified by @p name.
175
176 The Templates and plugins loaded will be determined by
177 the **%Engine** configuration.
178 */
179 Template loadByName(const QString &name) const;
180
181 /**
182 Create a new Template with the content @p content identified by @p name.
183
184 The secondary Templates and plugins loaded will be determined by
185 the **%Engine** configuration.
186 */
187 Template newTemplate(const QString &content, const QString &name) const;
188
189 /**
190 Returns the libraries available by default to new Templates.
191 */
192 QStringList defaultLibraries() const;
193
194 /**
195 Adds the library named @p libName to the libraries available by default to
196 new Templates.
197 */
198 void addDefaultLibrary(const QString &libName);
199
200 /**
201 Removes the library named @p libName from the libraries available by
202 default to new Templates.
203 */
204 void removeDefaultLibrary(const QString &libName);
205
206 /**
207 Returns whether the smart trim feature is enabled for newly loaded
208 templates.
209
210 @see smart_trim
211
212 This is false by default.
213 */
214 bool smartTrimEnabled() const;
215
216 /**
217 Sets whether the smart trim feature is enabled for newly loaded templates.
218
219 @see smart_trim
220 */
221 void setSmartTrimEnabled(bool enabled);
222
223#ifndef K_DOXYGEN
224 /**
225 @internal
226
227 Loads and returns the libraries specified in defaultLibraries or @p state.
228 */
229 void loadDefaultLibraries();
230
231 /**
232 @internal
233
234 Loads and returns the library specified by @p name in the
235 current **%Engine** configuration or @p state.
236
237 Templates wishing to load a library should use the @gr_tag{load} tag.
238 */
239 TagLibraryInterface *loadLibrary(const QString &name);
240#endif
241
242private:
243 Q_DECLARE_PRIVATE(Engine)
244 EnginePrivate *const d_ptr;
245};
246}
247
248#endif
KTextTemplate::Engine is the main entry point for creating KTextTemplate Templates.
Definition engine.h:110
The TagLibraryInterface returns available tags and filters from libraries.
The Template class is a tree of nodes which may be rendered.
Definition template.h:85
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 Jul 19 2024 11:59:16 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.