/usr/include/Wt/WTemplate is in libwt-dev 3.1.10-1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 | // This may look like C code, but it's really -*- C++ -*-
/*
* Copyright (C) 2009 Emweb bvba, Kessel-Lo, Belgium.
*
* See the LICENSE file for terms of use.
*/
#ifndef WTEMPLATE_H_
#define WTEMPLATE_H_
#include <Wt/WInteractWidget>
#include <Wt/WString>
namespace Wt {
/*! \class WTemplate Wt/WTemplate Wt/WTemplate
* \brief A widget that renders an XHTML template.
*
* The XHTML template may contain references to variables which
* replaced by strings are widgets.
*
* Since the template text may be supplied by a WString, you can
* conveniently store the string in a message resource bundle, and
* make it localized by using WString::tr().
*
* Variable references use a <tt>${<i>varName</i>}</tt> syntax to
* reference the variable <tt>"varName"</tt>. To use a literal
* <tt>"${"</tt>, use <tt>"$${"</tt>.
*
* \note The use of XML comments (<tt><!-- ... --></tt>)
* around variables that are bound to widgets will result in bad
* behaviour since the template parser is ignorant about these
* comments and the corresponding widgets will believe that they
* are rendered but aren't actually.
*
* You can bind widgets and values to variables using bindWidget(),
* bindString() or bindInt() or by reimplementing the resolveString()
* and resolveWidget() methods.
*
* Usage example:
* \code
* WString userName = ...;
*
* WTemplate *t = new WTemplate();
* t->setTemplateText("<div> How old are you, ${friend} ? ${age-input} </div>");
*
* t->bindString("friend", userName);
* t->bindWidget("age-input", ageEdit_ = new WLineEdit());
* \endcode
*
* \if cpp
* The template can return a bound widget using resolve(), which already
* tries to cast the widget to the proper type.
* \endif
*
* <h3>CSS</h3>
*
* This widget does not provide styling,
* and can be styled using inline or external CSS as appropriate.
*/
class WT_API WTemplate : public WInteractWidget
{
public:
/*! \brief Creates a template widget.
*/
WTemplate(WContainerWidget *parent = 0);
/*! \brief Creates a template widget with given template.
*
* The \p templateText must be proper XHTML, and this is checked
* unless the XHTML is resolved from a message resource bundle. This
* behavior is similar to a WText when configured with the
* Wt::XHTMLText textformat.
*/
WTemplate(const WString& text, WContainerWidget *parent = 0);
/*! \brief Returns the template.
*
* \sa setTemplateText(const WString&)
*/
const WString& templateText() const { return text_; }
/*! \brief Sets the template text.
*
* The \p text must be proper XHTML, and this is checked unless the
* XHTML is resolved from a message resource bundle or TextFormat is
* Wt::XHTMLUnsafeText. This behavior is similar to a WText when
* configured with the Wt::XHTMLText textformat.
*
* Changing the template text does not clear() bound widgets or
* values.
*
* \sa clear()
*/
void setTemplateText(const WString& text, TextFormat textFormat = XHTMLText);
/*! \brief Binds a widget to a variable name.
*
* The corresponding variable reference within the template will be
* replaced with the widget (rendered as XHTML). Since a single
* widget may be instantiated only once in a template, the variable
* \p varName may occur at most once in the template.
*
* If a widget was already bound to the variable, it is deleted
* first. If previously a string or other value was bound to the
* variable, it is removed.
*
* You may also pass a \c 0 \p widget, which will resolve to an empty
* string.
*
* \sa bindString()
* \sa resolveWidget()
*/
void bindWidget(const std::string& varName, WWidget *widget);
/*! \brief Binds a string value to a variable name.
*
* Each occurrence of the variable within the template will be
* substituted by its value.
*
* Depending on the \p textFormat, the \p value is validated according
* as for a WText.
*
* \sa bindWidget(), bindInt()
* \sa resolveString()
*/
void bindString(const std::string& varName, const WString& value,
TextFormat textFormat = XHTMLText);
/*! \brief Binds an integer value to a variable name.
*
* \sa bindString()
*/
void bindInt(const std::string& varName, int value);
/*! \brief Resolves the string value for a variable name.
*
* This is the main method used to resolve variables in the template
* text, during rendering.
*
* The default implementation considers first whether a string was
* bound using bindString(). If so, that string is returned. If
* not, it will attempt to resolve a widget with that variable name
* using resolveWidget(), and render it as XHTML. If that fails too,
* handleUnresolvedVariable() is called, passing the initial arguments.
*
* You may want to reimplement this method to provide on-demand
* loading of strings for your template.
*
* The result stream expects a UTF-8 encoded string value.
*
* \warning When specializing this class, you need to make sure that
* you append proper XHTML to the \p result, without unsafe active
* contents. The format() methods may be used for this purpose.
*
* \sa renderTemplate()
*/
virtual void resolveString(const std::string& varName,
const std::vector<WString>& args,
std::ostream& result);
/*! \brief Handles a variable that could not be resolved.
*
* This method is called from resolveString() for variables that could
* not be resolved.
*
* The default implementation implementation writes
* "??" + varName + "??" to the result stream.
*
* The result stream expects a UTF-8 encoded string value.
*
* \warning When specializing this class, you need to make sure that
* you append proper XHTML to the \p result, without unsafe active
* contents. The format() methods may be used for this purpose.
*
* \sa resolveString()
*/
virtual void handleUnresolvedVariable(const std::string& varName,
const std::vector<WString>& args,
std::ostream& result);
/*! \brief Resolves a widget for a variable name.
*
* The default implementation returns a widget that was bound using
* bindWidget().
*
* You may want to reimplement this method to create widgets
* on-demand. All widgets that are returned by this method are
* reparented to the WTemplate, so they will be deleted when the
* template is destroyed, but they are not deleted by clear() (unless
* bind was called on them as in the example below).
*
* This method is typically used for delayed binding of widgets.
* Usage example:
* \code
* {
* if (Widget *known = WTemplate::resolveWidget(varName)) {
* return known;
* } else {
* if (varName == "age-input") {
* WWidget *w = new WLineEdit(); // widget only created when used
* bind(varName, w);
* return w;
* }
* }
* }
* \endcode
*/
virtual WWidget *resolveWidget(const std::string& varName);
/*! \brief Returns a widget for a variable name.
*
* This is a convience method, which calls resolveWidget() and casts
* the result to type \p T. You may use this method to fetch widgets
* that have previously been bound using bindWidget().
*/
template <typename T> T resolve(const std::string& varName);
/*! \brief Erases all variable bindings.
*
* Removes all strings and deletes all widgets that were previously
* bound using bindString() and bindWidget().
*/
void clear();
/*! \brief Enables internal path anchors in the XHTML template.
*
* Anchors to internal paths are represented differently depending
* on the session implementation (plain HTML, Ajax or HTML5
* history). By enabling this option, anchors which reference an
* internal path (by referring a URL of the form
* <tt>href="#/..."</tt>), are re-encoded to link to the internal
* path.
*
* The default value is \c false.
*
* \sa WAnchor::setRefInternalPath()
*/
void setInternalPathEncoding(bool enabled);
/*! \brief Returns whether internal paths are enabled.
*
* \sa setInternalPathEncoding()
*/
bool hasInternalPathEncoding() const { return encodeInternalPaths_; }
/*! \brief Refreshes the template.
*
* This rerenders the template.
*/
virtual void refresh();
static const char *DropShadow_x1_x2;
protected:
/*! \brief Renders the template into the given result stream.
*
* The default implementation will parse the template, and resolve variables
* by calling resolveString().
*
* You may want to reimplement this method to manage resources that are
* needed to load content on-demand (e.g. database objects), or support
* a custom template language.
*/
virtual void renderTemplate(std::ostream& result);
virtual void updateDom(DomElement& element, bool all);
virtual DomElementType domElementType() const;
virtual void propagateRenderOk(bool deep);
/*! \brief Utility method to safely format an XHTML string.
*
* The string is formatted according to the indicated \p
* textFormat. It is recommended to use this method when
* specializing resolveString() to avoid security risks.
*/
void format(std::ostream& result, const std::string& s,
TextFormat textFormat = PlainText);
/*! \brief Utility method to safely format an XHTML string.
*
* The string is formatted according to the indicated \p
* textFormat. It is recommended to use this method when
* specializing resolveString() to avoid security risks.
*/
void format(std::ostream& result, const WString& s,
TextFormat textFormat = PlainText);
virtual void enableAjax();
private:
typedef std::map<std::string, WWidget *> WidgetMap;
typedef std::map<std::string, std::string> StringMap;
std::set<WWidget *> *previouslyRendered_;
std::vector<WWidget *> *newlyRendered_;
WidgetMap widgets_;
StringMap strings_;
WString text_;
bool encodeInternalPaths_, changed_;
};
template <typename T> T WTemplate::resolve(const std::string& varName)
{
WWidget *w = resolveWidget(varName);
return dynamic_cast<T>(w);
}
}
#endif // WTEMPLATE_H_
|