5
@page using_and_deploying Using Grantlee in your application
7
Using %Grantlee in Qt applications will often not require much code.
10
Grantlee::Engine *engine = getEngine();
11
Template t = engine->loadByName( "mytemplate.html" );
13
c.insert( "some_input", some_value );
14
browser.setHtml( t->render( c ) );
17
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 %Grantlee, and to configure %Grantlee to find templates and plugins.
19
@section finding_with_cmake Finding Grantlee with CMake
21
%Grantlee uses the <a href="http://www.cmake.org/">CMake</a> cross platform build system, and installs a cmake file called GrantleeConfig.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 %Grantlee libraries.
23
When creating an application using CMake that depends on %Grantlee, first issue the find_package command, and then use the CMake variables to include paths to %Grantlee headers and link to the libraries.
26
project(my_application)
28
cmake_minimum_required(VERSION 2.6)
30
find_package(Qt4 REQUIRED)
31
find_package(Grantlee REQUIRED)
35
${Grantlee_INCLUDE_DIRS}
36
${PROJECT_BINARY_DIR} # Usually this is needed to find moc files.
39
# ... Application sources etc.
41
target_link_libraries(
44
${Grantlee_CORE_LIBRARIES}
48
When %Grantlee is found correctly, it makes the following CMake variables available:
49
- Grantlee_FOUND - Set to true if found, false otherwise.
50
- Grantlee_INCLUDE_DIR - Set to the directory where the %Grantlee headers are located. Applications can then \#include <grantlee/engine.h>
51
- Grantlee_CORE_LIBRARIES - Set to the location of the installed version of the grantlee_core library.
52
- Grantlee_GUI_LIBRARIES - Set to the location of the installed version of the grantlee_gui library.
53
- Grantlee_USE_FILE - Set to the path to the GrantleeUse.cmake file.
54
- Grantlee_VERSION_MAJOR - The major version number of %Grantlee.
55
- Grantlee_VERSION_MINOR - The minor version number of %Grantlee.
56
- Grantlee_VERSION_PATCH - The patch version number of %Grantlee.
58
@section deploying_templates Deploying Templates
60
%Template files can be installed by your application and must later be found by %Grantlee 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 TemplateLoader.
65
Engine *engine = new Engine( this );
67
FileSystemTemplateLoader::Ptr loader = FileSystemTemplateLoader::Ptr( new FileSystemTemplateLoader() );
68
loader->setTemplateDirs( QStringList() << path_to_installed_templates );
70
engine->addTemplateLoader( loader );
75
It is also possible to compile the templates into a <a href="http://qt.nokia.com/doc/4.5/resources.html">Qt Resource</a> file and set the resource URL on the TemplateLoader.
78
# my_app_templates.qrc:
79
<!DOCTYPE RCC><RCC version="1.0">
81
<file>mybasetemplate.html</file>
82
<file>mytemplate.html</file>
83
<file>myothertemplate.html</file>
88
set (_rcc_file "my_app_templates.qrc")
89
qt4_add_resources(_template_rcc_src ${_rcc_file} OPTIONS -root "/templates/" )
91
add_executable(my_app, ${my_app_srcs} ${_template_rcc_src})
94
FileSystemTemplateLoader::Ptr loader = FileSystemTemplateLoader::Ptr( new FileSystemTemplateLoader() );
95
loader->setTemplateDirs( QStringList() << ":/templates/" );
97
engine->addTemplateLoader( loader );
100
The <tt>-root</tt> option passed to rcc in CMake causes the templates to be in the virtual filesystem location "<tt>:/grantlee/mytemplate.html</tt>" etc. This name spacing helps keep independent data in the virtual filesystem separate.
102
@section finding_user_templates Finding user defined templates
104
If users are able to define their own templates in an application that uses %Grantlee for theming for example, the path to the location of such potential templates must also be set through the TemplateLoader. 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 TemplateLoader.
107
FileSystemTemplateLoader::Ptr no_override_loader = FileSystemTemplateLoader::Ptr( new FileSystemTemplateLoader() );
108
no_override_loader->setTemplateDirs( QStringList() << path_to_non_overridable_templates );
110
engine->addTemplateLoader( no_override_loader );
112
FileSystemTemplateLoader::Ptr override_loader = FileSystemTemplateLoader::Ptr( new FileSystemTemplateLoader() );
113
override_loader->setTemplateDirs( QStringList() << path_to_user_templates << path_to_default_templates );
115
engine->addTemplateLoader( override_loader );
118
Additionally, the <a href="http://qt.nokia.com/doc/4.5/resources.html#external-binary-resources">External binary resources</a> 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.
120
@section finding_plugins Finding tags and filters
122
By default, %Grantlee searches in the paths specified by QCoreApplication::libraryPaths() for %Grantlee plugins. Each specified path has <tt>"grantlee/$version/"</tt> appended to it, and the resulting directory is searched for plugins. For example, if the version of %Grantlee is 0.2 and QCoreApplication::libraryPaths() contains <tt>"/usr/lib/plugins/"</tt>, the path <tt>"/usr/lib/plugins/grantlee/0.2"</tt> would be searched for plugins.
124
The paths used to search for plugins can be overriden by using Engine::setPluginPaths. Again, <tt>"grantlee/$version/"</tt> is appended to the path before using it. Paths are searched in order for particular plugins, and the search stops when a plugin matching a particular name is found.
126
@section deploying_custom_plugins Deploying custom tags and filters
128
Custom tags and filters can be defined in C++ code or in QtScript.
130
To create a custom C++ plugin it must be built as part of a library and installed in a location known to the application.
135
include(${Grantlee_USE_FILE}) # This files defines the grantlee_add_plugin macro
137
grantlee_add_plugin(my_custom_plugin
138
custom_plugin_library
150
install(TARGETS my_custom_plugin
151
RUNTIME DESTINATION ${PLUGIN_INSTALL_DIR}
152
LIBRARY DESTINATION ${PLUGIN_INSTALL_DIR}
153
ARCHIVE DESTINATION ${LIB_INSTALL_DIR}
158
In this case, my_custom_plugin is a name used for the plugin in the CMake environment. It is used to install the custom library in the install command.
160
<tt>custom_plugin_library.cpp</tt> is the C++ file where you implement the Grantlee::TagLibaryInterface to return custom tags and filters. The custom tags and filters files are given with the TAGS and FILTERS arguments to the macro. Note that moc is not run on the headers of files given in the FILTERS argument, and is run on the headers of files given in the TAGS argument (custom_tag1.h etc) and on the main library file, in this case custom_plugin_library.h.
162
Note that the PLUGIN_INSTALL_DIR given to the install command should contain the version number of %Grantlee used to create the custom library. For example, <tt>/usr/share/my_app/plugins/grantlee/0.1/</tt>.
164
In C++ code, it is necessary to either instruct the Grantlee::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 %Grantlee plugins.
166
For example, if your custom plugin library contained a custom implementation of the @gr_tag{for} tag:
168
Engine *engine = new Engine( this );
169
engine->setPluginPaths( QStringList() << path_to_custom_plugins << path_to_grantlee_defaults );
172
Note that neither the path to the custom libarary nor the path to the %Grantlee default library should contain the version number when specified in C++ code with the Engine. The version is only specified when installing the plugin in CMake.
174
Custom tags and filters implemented in QtScript can also be deployed on the file system, or, like template files, can also be deployed in Qt Resource files. In that case, the version should be specified in the -root argument in CMake.
178
set (_rcc_file "my_qtscript_library.qrc")
179
qt4_add_resources(_scripted_rcc_src ${_rcc_file} OPTIONS -root "/plugins/grantlee/${Grantlee_VERSION_MAJOR}.${Grantlee_VERSION_MINOR}" )
181
add_executable(my_app, ${my_app_srcs} ${_scripted_rcc_src})
184
engine->setPluginPaths( QStringList() << ":/plugins/" );
187
Note again that when specifying the path in the virtual filesystem, the version is omitted. User defined filter written in QtScript can also be located similiarly to templates from either the filesystem or the Qt Resource virtual filesystem.
189
@section building_grantlee Building Grantlee
191
It is possible to build only parts of %Grantlee if your application is a QCoreApplication that depends only on QtCore
193
@image html grantlee_deps.png "Dependency Graph for Grantlee"
195
@image html plugin_deps.png "Dependency Graph for Grantlee plugins"
197
The appropriate options may be specified in the cmake gui, or on the command line.
200
mkdir build && cd build
201
cmake .. -DBUILD_GUI:BOOL=OFF -DBUILD_TESTS:BOOL=OFF -DBUILD_SCRIPT_PLUGIN:BOOL=OFF
204
Similarly, it is possible to build only grantlee_gui standalone
207
mkdir build && cd build
208
cmake .. -DBUILD_CORE:BOOL=OFF -DBUILD_TESTS:BOOL=OFF -DBUILD_MAIN_PLUGINS:BOOL=OFF -DBUILD_SCRIPT_PLUGIN:BOOL=OFF