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_TEMPLATE_H |
22 | #define GRANTLEE_TEMPLATE_H |
23 | |
24 | #include "exception.h" |
25 | #include "grantlee_core_export.h" |
26 | #include "node.h" |
27 | |
28 | #include <QtCore/QSharedPointer> |
29 | #include <QtCore/QStringList> |
30 | |
31 | namespace Grantlee |
32 | { |
33 | class Context; |
34 | class Engine; |
35 | class TemplateImpl; |
36 | class OutputStream; |
37 | |
38 | #ifdef Q_QDOC |
39 | #define TemplateImpl Template |
40 | #else |
41 | typedef QSharedPointer<TemplateImpl> Template; |
42 | #endif |
43 | |
44 | class TemplatePrivate; |
45 | |
46 | /// @headerfile template.h grantlee/template.h |
47 | |
48 | /** |
49 | @brief The Template class is a tree of nodes which may be rendered. |
50 | |
51 | All Templates are created through the Grantlee::Engine class. |
52 | A template is created by parsing some text markup passed into the Engine, or by |
53 | reading it from a file. |
54 | |
55 | Note that Template is actually a typedef for a QSharedPointer<TemplateImpl>, so all of its members should be accessed with operator->(). |
56 | |
57 | The result of parsing is a Template object which can be rendered multiple times with multiple different Contexts. |
58 | |
59 | @code |
60 | Engine *engine = getEngine(); |
61 | Template t = engine->newTemplate( "{{ name }} is aged {{ age }}", "simple template" ); |
62 | if ( t->error() ) |
63 | { |
64 | // Tokenizing or parsing error, or couldn't find custom tags or filters. |
65 | qDebug() << t->errorString(); |
66 | return; |
67 | } |
68 | QTextStream textStream( stdout ); |
69 | OutputStream stream( textStream ); |
70 | |
71 | for ( ... ) |
72 | { |
73 | Context c; |
74 | // ... c.insert |
75 | t->render( stream, c ); |
76 | |
77 | if (t->error()) |
78 | { |
79 | // Rendering error. |
80 | qDebug() << t->errorString(); |
81 | } |
82 | } |
83 | @endcode |
84 | |
85 | If there is an error in parsing or rendering, the error and errorString methods can be used to check the source of the error. |
86 | |
87 | @author Stephen Kelly <steveire@gmail.com> |
88 | */ |
89 | class GRANTLEE_CORE_EXPORT TemplateImpl : public QObject |
90 | { |
91 | Q_OBJECT |
92 | public: |
93 | ~TemplateImpl(); |
94 | |
95 | /** |
96 | Renders the template to a string given the Context @p c. |
97 | */ |
98 | virtual QString render( Context *c ); |
99 | |
100 | /** |
101 | Renders the Template to the OutputStream @p stream given the Context c. |
102 | */ |
103 | // ### BIC make this const and non-virtual. |
104 | virtual OutputStream* render( OutputStream *stream, Context *c ); |
105 | |
106 | #ifndef Q_QDOC |
107 | /** |
108 | @internal |
109 | */ |
110 | NodeList nodeList() const; |
111 | |
112 | /** |
113 | @internal |
114 | */ |
115 | void setNodeList( const NodeList &list ); |
116 | #endif |
117 | |
118 | /** |
119 | Returns an error code for the error encountered. |
120 | */ |
121 | Error error(); |
122 | |
123 | /** |
124 | Returns more information to developers in the form of a string. |
125 | */ |
126 | QString errorString(); |
127 | |
128 | /** |
129 | Returns the Engine that created this Template. |
130 | */ |
131 | Engine const * engine() const; |
132 | |
133 | #ifndef Q_QDOC |
134 | protected: |
135 | TemplateImpl( Engine const *engine, QObject *parent = 0 ); |
136 | TemplateImpl( Engine const *engine, bool smartTrim, QObject *parent = 0 ); |
137 | |
138 | void setContent( const QString &templateString ); |
139 | #endif |
140 | |
141 | private: |
142 | //Don't allow setting the parent on a Template, which is memory managed as a QSharedPointer. |
143 | using QObject::setParent; |
144 | |
145 | private: |
146 | Q_DECLARE_PRIVATE( Template ) |
147 | TemplatePrivate * const d_ptr; |
148 | #ifndef Q_QDOC |
149 | friend class Engine; |
150 | friend class Parser; |
151 | #endif |
152 | }; |
153 | |
154 | } |
155 | |
156 | Q_DECLARE_METATYPE( Grantlee::Template ) |
157 | |
158 | #endif |
159 | |
160 | |