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
31namespace Grantlee
32{
33class Context;
34class Engine;
35class TemplateImpl;
36class OutputStream;
37
38#ifdef Q_QDOC
39#define TemplateImpl Template
40#else
41typedef QSharedPointer<TemplateImpl> Template;
42#endif
43
44class 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*/
89class GRANTLEE_CORE_EXPORT TemplateImpl : public QObject
90{
91 Q_OBJECT
92public:
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
134protected:
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
141private:
142 //Don't allow setting the parent on a Template, which is memory managed as a QSharedPointer.
143 using QObject::setParent;
144
145private:
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
156Q_DECLARE_METATYPE( Grantlee::Template )
157
158#endif
159
160