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 | |
29 | namespace Grantlee |
30 | { |
31 | |
32 | class 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 | */ |
46 | class GRANTLEE_CORE_EXPORT AbstractTemplateLoader |
47 | { |
48 | public: |
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 | */ |
123 | class GRANTLEE_CORE_EXPORT FileSystemTemplateLoader : public AbstractTemplateLoader |
124 | { |
125 | public: |
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 | |
166 | private: |
167 | QString m_themeName; |
168 | QStringList m_templateDirs; |
169 | }; |
170 | |
171 | class 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 | */ |
180 | class GRANTLEE_CORE_EXPORT LocalizedFileSystemTemplateLoader : public FileSystemTemplateLoader |
181 | { |
182 | public: |
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 | |
207 | private: |
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 | */ |
221 | class GRANTLEE_CORE_EXPORT InMemoryTemplateLoader : public AbstractTemplateLoader |
222 | { |
223 | public: |
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 | |
253 | private: |
254 | QHash<QString, QString> m_namedTemplates; |
255 | }; |
256 | |
257 | } |
258 | |
259 | #endif |
260 | |
261 | |