2
This file is part of the Grantlee template system.
4
Copyright (c) 2009,2010 Stephen Kelly <steveire@gmail.com>
6
This library is free software; you can redistribute it and/or
7
modify it under the terms of the GNU Lesser General Public
8
License as published by the Free Software Foundation; either version
9
2 of the Licence, or (at your option) any later version.
11
This library is distributed in the hope that it will be useful,
12
but WITHOUT ANY WARRANTY; without even the implied warranty of
13
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
Library General Public License for more details.
16
You should have received a copy of the GNU Lesser General Public
17
License along with this library. If not, see <http://www.gnu.org/licenses/>.
21
#ifndef GRANTLEE_ENGINE_H
22
#define GRANTLEE_ENGINE_H
25
#include "templateloader.h"
29
class TagLibraryInterface;
33
/// @headerfile engine.h grantlee/engine.h
36
@brief Grantlee::Engine is the main entry point for creating %Grantlee Templates.
38
The Grantlee::Engine is responsible for configuring and creating Template objects.
39
In typical use, one or more TemplateLoader objects will be added to the Engine to load template objects, and
40
plugin directories will be set to enable finding template tags and filters.
43
Engine *engine = new Engine();
45
FileSystemTemplateLoader::Ptr loader = FileSystemTemplateLoader::Ptr( new FileSystemTemplateLoader() );
46
loader->setTemplateDirs( QStringList() << "/usr/share/myapp/templates" );
47
engine->addTemplateLoader( loader );
49
engine->setPluginPaths( QStringList() << GRANTLEE_PLUGIN_PATH );
51
Template template1 = engine->newTemplate( "Template content", "template name" );
53
Template template2 = engine->loadByName( "templatefile.html" );
56
Once it is configured, the engine can be used to create new templates by name by loading the templates with the loadByName method,
57
or by defining the content in the newTemplate method.
59
By default the builtin tags and filters distributed with %Grantlee are available in all templates without using the @gr_tag{load}
60
tag in the template. These pre-loaded libraries may be configured if appropriate to the application. For example, an application
61
which defines its own tags and filters may want them to be always available, or it may be desirable to restrict the features
62
available to template authors by removing built in libraries.
64
Different Engine objects can be used to create templates with differing configurations.
66
@author Stephen Kelly <steveire@gmail.com>
68
class GRANTLEE_CORE_EXPORT Engine : public QObject
75
Engine( QObject *parent = 0 );
83
Returns the TemplateLoaders currently configured on the Engine.
85
QList<AbstractTemplateLoader::Ptr> templateLoaders();
88
Adds @p loader to the TemplateLoaders currently configured on the Engine.
90
void addTemplateLoader( AbstractTemplateLoader::Ptr loader );
93
Sets the plugin dirs currently configured on the Engine to @p dirs.
95
@see @ref finding_plugins
97
void setPluginPaths( const QStringList &dirs );
100
Returns a URI for a media item with the name @p name.
102
Typically this will be used for images. For example the media URI for the image
103
<tt>"header_logo.png"</tt> may be <tt>"/home/user/common/header_logo.png"</tt> or <tt>"/home/user/some_theme/header_logo.png"</tt>
104
depending on the templateLoaders configured.
106
This method will not usually be called by application code.
107
To load media in a template, use the @gr_tag{media_finder} template tag.
109
QPair<QString, QString> mediaUri( const QString &fileName ) const;
112
Load the Template identified by @p name.
114
The Templates and plugins loaded will be determined by the Engine configuration.
116
Template loadByName( const QString &name ) const;
119
Create a new Template with the content @p content identified by @p name.
121
The secondary Templates and plugins loaded will be determined by the Engine configuration.
123
Template newTemplate( const QString &content, const QString &name ) const;
126
Returns the libraries available by default to new Templates.
128
QStringList defaultLibraries() const;
131
Adds the library named @p libName to the libraries available by default to new Templates.
133
void addDefaultLibrary( const QString &libName );
136
Removes the library named @p libName from the libraries available by default to new Templates.
138
void removeDefaultLibrary( const QString &libName );
144
Loads and returns the libraries specified in defaultLibraries or @p state.
146
void loadDefaultLibraries();
151
Loads and returns the library specified by @p name in the current Engine configuration or @p state.
153
Templates wishing to load a library should use the @gr_tag{load} tag.
155
TagLibraryInterface* loadLibrary( const QString &name );
159
Q_DECLARE_PRIVATE( Engine )
160
EnginePrivate * const d_ptr;