1/*
2 This file is part of the Grantlee template system.
3
4 Copyright (c) 2009,2010 Stephen Kelly <steveire@gmail.com>
5
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.1 of the Licence, or (at your option) any later version.
10
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 Lesser General Public License for more details.
15
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/>.
18
19*/
20
21#ifndef GRANTLEE_TEMPLATELOADER_H
22#define GRANTLEE_TEMPLATELOADER_H
23
24#include "template.h"
25#include "grantlee_core_export.h"
26
27#include <QtCore/QSharedPointer>
28
29namespace Grantlee
30{
31
32class AbstractLocalizer;
33
34/// @headerfile templateloader.h grantlee/templateloader.h
35
36/**
37 @brief An retrieval interface to a storage location for Template objects.
38
39 This interface can be implemented to define new ways of retrieving the content of Templates.
40
41 The interface of this class should not be called directly from applications. TemplateLoaders will typically
42 be created, configured and added to the Grantlee::Engine which will call the appropriate API.
43
44 @author Stephen Kelly <steveire@gmail.com>
45*/
46class GRANTLEE_CORE_EXPORT AbstractTemplateLoader
47{
48public:
49 /**
50 A QSharedPointer to an AbstractTemplateLoader
51 */
52 typedef QSharedPointer<AbstractTemplateLoader> Ptr;
53
54 /**
55 Destructor
56 */
57 virtual ~AbstractTemplateLoader();
58
59 /**
60 Load a Template called @p name. Return an invalid Template if no content by that name exists.
61 */
62 virtual Template loadByName( const QString &name, Engine const *engine ) const = 0;
63
64 /**
65 Return a complete URI for media identified by fileName.
66 */
67 virtual QPair<QString, QString> getMediaUri( const QString &fileName ) const = 0;
68
69 /**
70 Return true if a Template identified by @p name exists and can be loaded.
71 */
72 virtual bool canLoadTemplate( const QString &name ) const = 0;
73
74};
75
76/// @headerfile templateloader.h grantlee/templateloader.h
77
78/**
79 @brief The FileSystemTemplateLoader loads Templates from the file system.
80
81 This template loader works by traversing a list of directories to find templates. Directories
82 are checked in order, and the first match hit is parsed and returned.
83
84 @code
85 loader->setTemplateDirs(QStringList() << "/home/user/app/templates" << "/usr/local/share/app/templates" );
86 engine->setTemplateLoader( loader );
87
88 // This will try /home/user/app/templates/mytemplate.html
89 // followed by /usr/local/share/app/templates/mytemplate.html
90 engine->loadByName( "mytemplate.html" );
91 @endcode
92
93 Additionally, a themeName may be set on the template loader, which will be appended to search paths before the template name.
94
95 @code
96 loader->setTemplateDirs(QStringList() << "/home/user/app/templates" << "/usr/local/share/app/templates" );
97 loader->setTheme( "simple_theme" );
98 engine->setTemplateLoader( loader );
99
100 // This will try /home/user/app/templates/simple_theme/mytemplate.html
101 // followed by /usr/local/share/app/templates/simple_theme/mytemplate.html
102 engine->loadByName( "mytemplate.html" );
103 @endcode
104
105 Media URIs may be retrieved for media relative to the directories searched queried for templates.
106
107 @code
108 loader->setTemplateDirs(QStringList() << "/home/user/app/templates" << "/usr/local/share/app/templates" );
109 loader->setTheme( "simple_theme" );
110 engine->setTemplateLoader( loader );
111
112 // This will try /home/user/app/templates/simple_theme/logo.png
113 // followed by /usr/local/share/app/templates/simple_theme/logo.png
114 // and return the first one that exists.
115 engine->mediaUri( "logo.png" );
116 @endcode
117
118 The template files loaded by a %FileSystemTemplateLoader must be UTF-8 encoded.
119
120 @see @ref deploying_templates
121
122*/
123class GRANTLEE_CORE_EXPORT FileSystemTemplateLoader : public AbstractTemplateLoader
124{
125public:
126#ifndef Q_QDOC
127 typedef QSharedPointer<FileSystemTemplateLoader> Ptr;
128#endif
129
130 /**
131 Constructor
132 */
133 FileSystemTemplateLoader();
134
135 /**
136 Destructor
137 */
138 virtual ~FileSystemTemplateLoader();
139
140 /* reimp */ Template loadByName( const QString &name, Engine const *engine ) const;
141
142 /* reimp */ bool canLoadTemplate( const QString &name ) const;
143
144 /* reimp */ QPair<QString, QString> getMediaUri( const QString& fileName ) const;
145
146 /**
147 Sets the theme of this loader to @p themeName
148 */
149 void setTheme( const QString &themeName );
150
151 /**
152 The themeName of this TemplateLoader
153 */
154 QString themeName() const;
155
156 /**
157 Sets the directories to look for template files to @p dirs.
158 */
159 void setTemplateDirs( const QStringList &dirs );
160
161 /**
162 The directories this TemplateLoader looks in for template files.
163 */
164 QStringList templateDirs() const;
165
166private:
167 QString m_themeName;
168 QStringList m_templateDirs;
169};
170
171class LocalizedFileSystemTemplateLoaderPrivate;
172
173// ### BIC: Make l10n part of the AbstractTemplateLoader, making this class unneeded.
174/**
175 @brief The LocalizedFileSystemTemplateLoader loads templates and l10n catalogs from the filesystem.
176
177 This template loader not only loads templates from the file system, but also loads translation
178 catalogs for themes.
179*/
180class GRANTLEE_CORE_EXPORT LocalizedFileSystemTemplateLoader : public FileSystemTemplateLoader
181{
182public:
183#ifndef Q_QDOC
184 typedef QSharedPointer<LocalizedFileSystemTemplateLoader> Ptr;
185#endif
186
187 /**
188 Constructor
189 */
190 LocalizedFileSystemTemplateLoader( const AbstractLocalizer::Ptr localizer );
191
192 /**
193 Destructor
194 */
195 virtual ~LocalizedFileSystemTemplateLoader();
196
197 /**
198 Sets the theme of this loader to @p themeName and loads the theme catalogs
199 */
200 void setTheme( const QString &themeName );
201
202 /**
203 Sets the directories to look for template files to @p dirs and loads catalogs from them.
204 */
205 void setTemplateDirs( const QStringList &dirs );
206
207private:
208 Q_DECLARE_PRIVATE( LocalizedFileSystemTemplateLoader )
209 LocalizedFileSystemTemplateLoaderPrivate * const d_ptr;
210};
211
212/// @headerfile templateloader.h grantlee/templateloader.h
213
214/**
215 @brief The InMemoryTemplateLoader loads Templates set dynamically in memory
216
217 This class is mostly used for testing purposes, but can also be used for simple uses of %Grantlee.
218
219 Templates can be made available using the setTemplate method, and will then be retrieved by the Grantlee::Engine as appropriate.
220*/
221class GRANTLEE_CORE_EXPORT InMemoryTemplateLoader : public AbstractTemplateLoader
222{
223public:
224#ifndef Q_QDOC
225 typedef QSharedPointer<InMemoryTemplateLoader> Ptr;
226#endif
227
228 InMemoryTemplateLoader();
229 virtual ~InMemoryTemplateLoader();
230
231 /* reimp */ Template loadByName( const QString &name, Engine const *engine ) const;
232
233 /* reimp */ bool canLoadTemplate( const QString &name ) const;
234
235 /* reimp */ QPair<QString, QString> getMediaUri( const QString& fileName ) const;
236
237 /**
238 Add a template content to this Loader.
239
240 Example:
241
242 @code
243 InMemoryTemplateLoader::Ptr loader = InMemoryTemplateLoader( new InMemoryTemplateLoader() );
244 loader->setTemplate( "name_template", "My name is {{ name }}" );
245 loader->setTemplate( "age_template", "My age is {{ age }}" );
246 engine->addTemplateLoader( loader );
247
248 // Both templates may now be retrieved by calling Engine::loadByName.
249 @endcode
250 */
251 void setTemplate( const QString &name, const QString &content );
252
253private:
254 QHash<QString, QString> m_namedTemplates;
255};
256
257}
258
259#endif
260
261