libwt-dev 3.1.10-1ubuntu2 / usr / include / Wt / WTemplate

// 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>&lt;!-- ... --&gt;</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_