1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
/*!
\page ktexttemplate-using-and-deploying
\title Using KTextTemplate in your application
Using KTextTemplate in Qt applications will often not require much code.
\code
auto engine = getEngine();
auto t = engine->loadByName( "mytemplate.html" );
Context c;
c.insert( "some_input", some_value );
browser.setHtml( t->render( c ) );
\endcode
Error handling etc is omitted for clarity. In order for the above to work as expected, it is necessary to configure the build system to find KTextTemplate, and to configure KTextTemplate to find templates and plugins.
\section1 Finding KTextTemplate with CMake
KTextTemplate uses the CMake cross platform build system, and installs a cmake file called \c KF6TextTemplateConfig.cmake. This config file is automatically searched for by CMake and contains the information needed for other CMake based applications to find headers and link against KTextTemplate libraries. See https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html for more.
When creating an application using CMake that depends on KTextTemplate, first issue the \c find_package command, and then use the CMake \c target_link_libraries command link to and use the libraries.
\code
project(my_application)
cmake_minimum_required(VERSION 2.8.11)
set(CMAKE_AUTOMOC ON)
set(CMAKE_INCLUDE_CURRENT_DIR ON)
find_package(KF6TextTemplate REQUIRED)
# ... Application sources etc.
target_link_libraries(my_application
PRIVATE
Qt5::Widgets
KF6::TextTemplate
)
\endcode
\section1 Deploying Templates
Template files can be installed by your application and must later be found by KTextTemplate so they can be used. If the files are installed on the filesystem, the path they were installed to can be specified when creating a AbstractTemplateLoader instance.
\code
Engine* getEngine()
{
auto engine = new Engine( this );
auto loader = QSharedPointer<FileSystemTemplateLoader>::create();
loader->setTemplateDirs( QStringList{ path_to_installed_templates } );
engine->addTemplateLoader( loader );
return engine;
}
\endcode
It is also possible to compile the templates into a \l {https://doc.qt.io/qt-5/resources.html} {Qt Resource} file and set the resource URL on the AbstractTemplateLoader instance.
my_app_templates.qrc:
\code
<!DOCTYPE RCC><RCC version="1.0">
<qresource>
<file>mybasetemplate.html</file>
<file>mytemplate.html</file>
<file>myothertemplate.html</file>
</qresource>
</RCC>
\endcode
CMake code:
\code
set (_rcc_file "my_app_templates.qrc")
qt5_add_resources(_template_rcc_src ${_rcc_file} OPTIONS -root "/templates/" )
add_executable(my_app, ${my_app_srcs} ${_template_rcc_src})
\endcode
Application code:
\code
auto loader = QSharedPointer<FileSystemTemplateLoader>::create();
loader->setTemplateDirs( QStringList{ ":/templates/" } );
engine->addTemplateLoader( loader );
\endcode
The \c -root option passed to \c rcc in CMake causes the templates to be in the virtual filesystem location \c :/templates/mytemplate.html etc. This name spacing helps keep independent data in the virtual filesystem separate.
\section1 Finding user defined templates
If users are able to define their own templates in an application that uses %KTextTemplate for theming for example, the path to the location of such potential templates must also be set through the AbstractTemplateLoader instance. Paths to user defined templates should be defined before default/installed templates so that the user templates are found first. If there is a reason to disallow user overriding of certain templates, they can be specified in a separate AbstractTemplateLoader instance.
\code
auto no_override_loader = QSharedPointer<FileSystemTemplateLoader>::create();
no_override_loader->setTemplateDirs(
QStringList{ path_to_non_overridable_templates }
);
engine->addTemplateLoader( no_override_loader );
auto override_loader = QSharedPointer<FileSystemTemplateLoader>::create();
override_loader->setTemplateDirs(
QStringList{ path_to_user_templates, path_to_default_templates }
);
engine->addTemplateLoader( override_loader );
\endcode
Additionally, the \l {https://doc.qt.io/qt-5/resources.html#external-binary-resources} {External binary resources} feature could be used to allow savvy users to share themes/templates in a package, or to deploy updated templates easily to existing deployed applications.
\section1 Finding tags and filters
KTextTemplate looks for plugins in the paths from the Engine::pluginPaths property. It does so
in the same order they appear there.
The property defaults to the following directories
\list
\li The default plugin directory of your Qt installation (\c {qmake -query QT_INSTALL_PLUGINS}).
\li The directories specified in the environment variable \c QT_PLUGIN_DIR.
\li The default plugin directory of your KTextTemplate installation.
\endlist
Each path has \c kf6/ktexttemplate appended to it, and the resulting
directory is searched for plugins. For example, if
QCoreApplication::libraryPaths() contains \c /usr/lib/plugins/, the directory
\c /usr/lib/plugins/kf6/ktexttemplate would be searched for plugins. The search
stops when a plugin matching a particular name is found.
The paths used to search for plugins can be overriden by using Engine::setPluginPaths. If you
just want to add some additional paths use Engine::addPluginPath. The added path will be
prepended to the list of search paths.
\section1 Deploying custom tags and filters
Custom tags and filters can be defined in C++ code or in Javascript.
To create a custom C++ plugin it must be built as part of a library and installed in a location known to the application.
\code
# CMake code
add_library(my_custom_plugin MODULE
custom_plugin_library.cpp
)
install(TARGETS my_custom_plugin
RUNTIME DESTINATION ${PLUGIN_INSTALL_DIR}
LIBRARY DESTINATION ${PLUGIN_INSTALL_DIR}
ARCHIVE DESTINATION ${LIB_INSTALL_DIR}
COMPONENT Devel
)
\endcode
In this case, \c my_custom_plugin is a name used for the plugin in the CMake environment. It is used to install the custom library in the CMake \c install command.
\c custom_plugin_library.cpp is the C++ file where you implement the KTextTemplate::TagLibraryInterface to return custom tags and filters.
Note that the \c PLUGIN_INSTALL_DIR given to the install command should point to the subdir specific
for the %KTextTemplate plugins. For example, \c /usr/share/my_app/plugins/kf6/ktexttemplate/.
In C++ code, it is necessary to either instruct the KTextTemplate::Engine about the location of the plugins or to configure your QCoreApplication::libraryPaths by another standard method. Note that it is possible to define custom versions of built in tags and filters by putting your own plugin library in the path before the path to the default KTextTemplate plugins.
For example, if your custom plugin library contained a custom implementation of the \c for tag:
\code
auto engine = new Engine( this );
engine->setPluginPaths(
QStringList{ path_to_custom_plugins, path_to_ktexttemplate_defaults }
);
\endcode
Custom tags and filters implemented in Javascript can also be deployed on the file system, or, like template files, can also be deployed in Qt Resource files. In that case, the plugin subdir should be specified in the -root argument in CMake.
\code
# CMake code:
set (_rcc_file "my_qtscript_library.qrc")
qt5_add_resources(_scripted_rcc_src
${_rcc_file}
OPTIONS -root "/plugins/kf6/ktexttemplate"
)
add_executable(my_app, ${my_app_srcs} ${_scripted_rcc_src})
# C++ code:
engine->setPluginPaths( QStringList{ ":/plugins/" } );
\endcode
Note again that when specifying the path in the virtual filesystem, the subdir is omitted. User defined filter written in Javascript can also be located similiarly to templates from either the filesystem or the %Qt Resource virtual filesystem.
\section1 Building KTextTemplate
It is possible to build only parts of KTextTemplate if your application is a QCoreApplication that depends only on QtCore
The appropriate options may be specified in the cmake gui, or on the command line using the \c BUILD_TEXTDOCUMENT or \c BUILD_TEMPLATES CMake options.
\code
mkdir build && cd build
cmake .. -DBUILD_TEXTDOCUMENT=OFF -DBUILD_TESTING=OFF
\endcode
Similarly, it is possible to build only the core of the %KTextTemplate Template library without the plugins. This may be useful for specialized applications, but as the unit tests depend on the plugins, the tests would need to be deactivated in this case too:
\code
mkdir build && cd build
cmake .. -DBUILD_TEXTDOCUMENT=OFF -DBUILD_TESTING=OFF -DBUILD_MAIN_PLUGINS=OFF
\endcode
By default, KTextTemplate depends on the QtQml library in order to implement Javascript support. This support is only enabled if the QtQml library is found.
*/
|
