File: using_and_deploying.dox

package info (click to toggle)
grantlee5 5.1.0-2.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 4,152 kB
  • sloc: cpp: 24,299; python: 413; sh: 108; ruby: 24; makefile: 20
file content (218 lines) | stat: -rw-r--r-- 9,870 bytes parent folder | download | duplicates (2)
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
213
214
215
216
217
218

namespace Grantlee
{
/**
  @page using_and_deploying Using Grantlee in your application

  Using %Grantlee in Qt applications will often not require much code.

  @code
    Grantlee::Engine *engine = getEngine();
    Template 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 %Grantlee, and to configure %Grantlee to find templates and plugins.

  @section finding_with_cmake Finding Grantlee with CMake

  %Grantlee uses the <a href="http://www.cmake.org/">CMake</a> cross platform build system, and installs a cmake file called Grantlee5Config.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.

  When creating an application using CMake that depends on %Grantlee, first issue the find_package command, and then use the CMake <tt>target_link_libraries</tt> 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(Grantlee5 REQUIRED)

    # ... Application sources etc.

    target_link_libraries(
      my_application
      Qt5::Widgets
      Grantlee5::Templates
    )
  @endcode

  @section deploying_templates Deploying Templates

  %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.

  @code
    Engine* getEngine()
    {
      Engine *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 <a href="http://qt.nokia.com/doc/4.5/resources.html">Qt Resource</a> file and set the resource URL on the TemplateLoader.

  @code
    # my_app_templates.qrc:
    <!DOCTYPE RCC><RCC version="1.0">
    <qresource>
        <file>mybasetemplate.html</file>
        <file>mytemplate.html</file>
        <file>myothertemplate.html</file>
    </qresource>
    </RCC>

    # CMake 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})

    # Application code:
    auto loader = QSharedPointer<FileSystemTemplateLoader>::create();
    loader->setTemplateDirs( QStringList() << ":/templates/" );

    engine->addTemplateLoader( loader );
  @endcode

  The <tt>-root</tt> option passed to rcc in CMake causes the templates to be in the virtual filesystem location &quot;<tt>:/grantlee/mytemplate.html</tt>&quot; etc. This name spacing helps keep independent data in the virtual filesystem separate.

  @section finding_user_templates Finding user defined templates

  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.

  @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 <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.

  @section finding_plugins Finding tags and filters

  Grantlee looks for plugins in the paths from the Engines pluginPath property. It does so
  in the same order they appear there.

  The property defaults to the following directories
    - The default plugin directory of your qt installation (qmake -query QT_INSTALL_PLUGINS).
    - The directories specified in the environment variable QT_PLUGIN_DIR.
    - The default plugin directory of your grantlee installation.

  Each path has <tt>&quot;grantlee/$version/&quot;</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>&quot;/usr/lib/plugins/&quot;</tt>, the directory
  <tt>&quot;/usr/lib/plugins/grantlee/0.2&quot;</tt> 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.

  @section deploying_custom_plugins Deploying custom tags and filters

  Custom tags and filters can be defined in C++ code or in QtScript.

  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

    include(${Grantlee_USE_FILE}) # This files defines the grantlee_add_plugin macro

    grantlee_add_plugin(my_custom_plugin
      custom_plugin_library

      TAGS
        custom_tag1
        custom_tag2
        custom_tag3
      FILTERS
        custom_filter1
        custom_filter2
        custom_filter3
    )

    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, 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.

  <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.

  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>.

  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.

  For example, if your custom plugin library contained a custom implementation of the @gr_tag{for} tag:
  @code
    Engine *engine = new Engine( this );
    engine->setPluginPaths( QStringList() << path_to_custom_plugins << path_to_grantlee_defaults );
  @endcode

  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.

  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.

  @code
    # CMake code:
    set (_rcc_file "my_qtscript_library.qrc")
    qt5_add_resources(_scripted_rcc_src ${_rcc_file} OPTIONS -root "/plugins/grantlee/${Grantlee5_VERSION_MAJOR}.${Grantlee5_VERSION_MINOR}" )

    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 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.

  @section building_grantlee Building Grantlee

  It is possible to build only parts of %Grantlee if your application is a QCoreApplication that depends only on QtCore

  <center>
  <b>
  @dotfile "moduledeps.dot" "Dependency Graph for Grantlee"
  </b>

  <b>
  @dotfile "plugindeps.dot" "Dependency Graph for Grantlee plugins"
  </b>
  </center>

  The appropriate options may be specified in the cmake gui, or on the command line.

  @code
    mkdir build && cd build
    cmake .. -DBUILD_GUI:BOOL=OFF -DBUILD_TESTS:BOOL=OFF -DBUILD_SCRIPT_PLUGIN:BOOL=OFF
  @endcode

  Similarly, it is possible to build only grantlee_gui standalone

  @code
    mkdir build && cd build
    cmake .. -DBUILD_CORE:BOOL=OFF -DBUILD_TESTS:BOOL=OFF -DBUILD_MAIN_PLUGINS:BOOL=OFF -DBUILD_SCRIPT_PLUGIN:BOOL=OFF
  @endcode

*/
}