Library overview

Contents

1. Widgets
1.1 Layout
1.2 Style
1.3 Widget containers
2. Application URL(s)
3. Startup and session management
4. Signal/slot event handling
5. Optimizing client-side event handling
6. Painting
7. Deployment
7.1 FastCGI
7.2 Built-in httpd
8. Configuration
8.1 Session management (wt_config.xml)
8.2 General application settings (wt_config.xml)
8.3 FastCGI options (wt_config.xml)
8.4 Wt httpd (command-line or configuration file) options
9. Error-handling and logging

1. Widgets

The WWidget class represents a widget, which provides abstraction of a visual entity. The entire user-interface is specified by creating a hierarchical structure of WWidgets, rooted at WApplication::root(). By reacting to events related to these widgets, you can perform business logic, and manipulate the widget hierarchy to update the user interface.

When inserting a widget in the widget hierarchy, ownership is transferred to its parent in the tree. Thus, when deleting a widget, all of its children are deleted as well, significantly reducing the burden of memory management related to widgets. When the WApplication object is deleted, the root of the tree is deleted, and in this way all resources associated with any widget are free'd.

Any descendent class of WWidget is a self-contained (reusable) class that encapsulates both the look and behaviour, enabling the design of the user interface in am orthogonal way.

1.1 Layout

Widgets are layed out (with a few exceptions) following this hierarchical structure. You have two main options for lay-out of children within a container. Either you use directly HTML/CSS, in which case the layout is determined by properties of the container and children: each child manages its layout with respect to its sibling following a (rather complex) set of rules. Alternatively, Wt provides layout managers that may be used for layout.

CSS layout considers two important categories of layout. Text-like layout (inline) flow with sibling inline widgets in lines, wrapping at the right edge of the parent container. In contrast, stacked widgets stack vertically with respect to sibling widgets.

Layout managers are implemented in WLayout and descendant classes. They can be used in conjunction with WContainerWidget or Ext::Container container classes. Note that some layout managers are applicable only to a WContainerWidget and some only to an Ext::Container. Due to limitations in CSS (and browser bugs), vertical layout is not possible without the presence of JavaScript in some browsers.

1.2 Style

For visual markup of widgets, the recommended way is to use CSS style sheets. These allow the visual look to be defined seperately from the the rest of the application. The location of the stylesheet may be configured using WApplication::useStyleSheet().

CSS Style selectors may be used in conjunction with widget style classes that may be set for any widget using WWidget::setStyleClass(). The recommended way for visual response to events is by changing the style class for the widget.

In addition to configuration using style sheets, Wt also supports the direct manipulation of a widget's style, using WWidget::decorationStyle().

1.3 Widget containers

With a few exceptions, all widgets are child of (and contained in) a container widget such as WContainerWidget or WTableCell. A widget is inserted into a WContainerWidget by adding the widget to the container using WContainerWidget::addWidget(), or by passing the parent container as an argument to the constructor.

Widgets may also be added to an Ext::Container, through a choice of layout manager, (see Ext::Container::setLayout()).

2. Application URL(s)

A Wt application, like any other CGI application, is deployed at a specific location (URL) within your web server. Still, an application may manage multiple URLs that correspond to internal paths. These are URLs that are created by appending an internal path to the application URL (this works only if the application was not deployed at a location ending with a '/'). The internal path may be manipulated through WApplication::setInternalPath(). Each time the internal path is changed, this is reflected in the browser URL and an entry is added to the browser history, allowing the user to use the back and forward buttons to navigate through your application.

To effectively change the internal path and obtain consistent behaviour with or without JavaScript, you should use a WAnchor to let the user switch to a new internal path. The easiest way to do this is by using the WAnchor::setRefInternalPath(). This refers the WAnchor to a URL generated by WApplication::bookmarkUrl() for the new internal path (handling the no-JavaScript case), and binds a JavaScrit slot to its WAnchor::clicked() signal, which changes the internal path (handling the AJAX case).

Finally, you can listen for path changes using the WApplication::internalPathChanged() event to react to the user navigating through his history or opening a bookmarked internal page.

To avoid reloading the application (and spawning a new session) each time the internal path is changed, when AJAX is available, the internal path is indicated using a name anchor (#) after the deployment URL. When no JavaScript is available, the session ID is appended to the URL to avoid the session from reloading when the user navigates using a WAnchor to a new internal URLs.

When your applications uses internal URLs, this has consequences for relative URLs to external resources (style sheets, images, JavaScript files, etc...), since these are resolved taking into account the current relative URL. All relative URLs that are known to the application (e.g. those set in WAnchor::setRef(), WImage::setImageRef(), WApplication::useStyleSheet(), etc...) are automatically replace by Wt with an absolute URL that resolves these directly within the deployment location. You should use absolute URLs in CSS or XHTML for them to work within each internal path, since these cannot be fixed by Wt.

3. Startup and session management

In your application, e.g. from within your main(), you should WRun() to start the Wt application server. This method will return only when shutdown is signaled by the environment, and after the application server (and all remaining active sessions) has been properly shutd down. One parameter to the WRun() function is a createApplication function object. Alternatively, if you wish to have more control over the application server, you may also instantiate and configure a WServer instance directly.

For every new session (which corresponds to a new user surfing to your web application), the library calls your createApplication callback function to create a new WApplication object for that session. The request arguments (as part of the WEnvironment object) are passed to this createApplication function, and may be used to customize the application or authenticate the user.

At all times, the WApplication instance is accessible using the static method WApplication::instance(), and is useful to inspect startup arguments and settings (using WApplication::environment()), to set or change the application title (WApplication::setTitle()), to specify a locale (WApplication::setLocale()) for rendering, and many other application-wide settings.

A session exits when the user browses away from the application, when WApplication::quit() is called, or when the application server is shut down. In any case, the application object together with the entire widget tree for that session is first properly deleted. Therefore, you should release resources held by your widgets or application in the destructors of these objects.

The library offers two different mechanisms to map sessions onto processes: dedicated processes (only with FastCGI deployment) and shared processes. The first mechanisms forks a dedicated process for every distinct session. This provides the kernel-level isolation of different sessions, which may be useful for highly security sensitive applications. The second mechanism spawns a number of processes and allocates new sessions randomly to one of these processes (when using the built-in httpd, only one process is used in total). This reduces the danger for DoS attacks, but requires more careful programming as memory corruption affects all sessions in a single process, and sessions are not isolated by any other mechanism but correct programming.

4. Signal/slot event handling

To respond to user-interactivity events, or in general to communicate events from one widget to any other, Wt uses a signal/slot system.

A slot is any method of any descendant of WObject. To connect a signal with a slot, the only requirement is that the method signature of the slot must be compatible with the signal definition. In this way every method may be used as a slot, and it is not necessary to explicitly indicate a particular method to be a slot (as is needed in Qt), by putting them in a special section. Nevertheless, you may still do that if you wish to emphasize that these functions can be used as slots, or, if you have done extra work to optimize the implementation of these methods as client-side JavaScript code (see below).

A signal may be created by adding a Signal<X, ...> object. You may specify up to 6 arguments which may be of arbitrary types that are Copyable, that may be passed through the signal to connected slots.

The library defines several user-event signals on various widgets, and it is easy and convenient to add signals and slots to widget classes to communicate events and trigger callbacks.

Event signals (EventSignal<E>) are signals that may be triggered internally by the library to respond to user interactivity events. The abstract base classes WInteractWidget and WFormWidget define most of these event signals. To react to one of these events, the programmer connects a self-defined or already existing slot to such a signal.

5. Optimizing client-side event handling

By default, Wt performs all event processing server-side. Every connected event signal will cause the web browser to communicate with the web server in order to perform the call-back code, and visual changes will be updated in the web page.

However, Wt offers several options for incorporating client-side event handling. This may in general increase responsiveness of the application since the user gets an instant feed-back, avoiding the typical communication delay is avoided.

The least flexible but most convenient option for client-side event handling is letting Wt learn the visual effect of a slot and cache it in JavaScript code in the browser. In this way, the functionality is still specified in C++, and therefore the application still works equally when JavaScript is not available. The only restriction is that this is only possible for stateless call-back code -- i.e. when the visual update does not depend on state that may change in the course of the application, or event details. See the documentation of WObject::implementStateless for details, or the Treelist example for the use of stateless implementations to create a treelist widget that does all node expansion / collapsing client-side, at least if JavaScript is available.

The stateless slot learning allows applications to be developed entirely in C++, with only one specification of the desired behaviour, and decide at run-time to optimize certain event handling in client-side JavaScript if possible, and fall-back to server-side event handling otherwise.

When the requirements for stateless slot learning cannot be met you will have to resort to writing JavaScript manually. Wt provides a number of mechanisms to integrate JavaScript code with C++:

6. Painting

Wt provides a vector graphics painting system, which depending on the browser support, uses one of three different methods to paint the graphics (inline SVG, inline VML or HTML 5 <canvas> element). Vector graphics has as benefit a lower bandwidth usage, which is indepedent of the image size and inline transport, avoiding an additional round-trip. To use the paint system, you need to specialize WPaintedWidget and use a WPainter to paint the contents of the widget inside its WPaintedWidget::paintEvent().

7. Deployment

The library is designed so that, besides the application binary, no other files are needed to deploy the application. However, some widgets require the resources located in the resources/ folder. In addition, any auxiliary files you use, such as message resource files, graphics, static pages, or anything else, will also need to be deployed.

7.1 FastCGI

When linking your application against libfcgi, the resulting binary is a FastCGI binary. This binary may then be deployed and managed within a web server which supports the FastCGI protocol (these include apache, lighttpd and many other popular web servers).

7.2 Built-in httpd

When linking your application against libhttp, the resulting binary is a stand-alone http(s) webserver. The web server will act as a plain web server in addition to serving the Wt application.

8. Configuration

Wt has one main XML configuration file (which by default is located in /etc/wt/wt_config.xml, and can be overridden with the WT_CONFIG_XML environment variable or the --config startup parameter for wthttpd).

The configuration file may specify several <application-settings>. The settings that apply are determined by the location attribute. Application settings for the '*' location are general settings, which may be overridden on a per-application level by settings with a location attribute that matches the location of the application (on the file system).

8.1 Session management (wt_config.xml)

These are options related to session management, and are specified inside <session-management> subsection.

dedicated-process
Every session is mapped a dedicated process, allowing maximal session isolation, but at an increased session cost.
This is currently only supported using the FastCGI connector.
shared-process
Sessions share a fixed number of processes, yielding a lower session cost.
This is the only option for the Wthttpd connector.

tracking
How session tracking is implemented: automatically (using cookies when available, otherwise using URL rewriting) or strictly using URL rewriting (which allows multiple concurrent sessions from one user).

reload-is-new-session
Should a brower reload spawn a new session (convenient for debugging) or simply refresh (using WApplication::refresh()) the current session ? This setting may have implications for the URL that is displayed, because session information in needed in the URL to handle the reload within the current session.

timeout
The timeout (in seconds) for detecting an idle session. A Wt application uses a keep-alive messages to keep the session alive as long as the user is visiting the page. Increasing this number will result in a longer time between keep-alive message, resulting in a lower server load, but at the same time will detect a dead session with a longer delay, and thus have on average more sessions in memory that are no longer used.

8.2 General application settings (wt_config.xml)

These options are indicated directly within <application-settings>, and specify settings that affect the run-time behaviour of the application.

debug
When debugging is enabled, JavaScript errors are not caught, and thus will provide stack information when using a JavaScript debugger.

log-file
Path to the log file used for application logging (see WApplication::log()). If not specified, logging is directed to stderr, which depending on the connector used ends up in the server error log, into the big void, or, simply to stderr.

max-request-size
The maximum HTTP request size (Kb) that is accepted. An oversized request will result in a WApplication::requestTooLarge() signal.

session-id-length
The length (in number of characters) for the unique session ID.

session-id-prefix
A fixed prefix for the session ID. You can use this to implement aid a load-balancer to figure out the destination for a particular request.

send-xhtml-mime-type
Whether the application presents rendered content as XHTML or HTML. Wt always renders XHTML1 compatible HTML, but by default indicates to the browser that it is in fact HTML. However, to use inline SVG (see WSvgImage), it is necessary to present an XHTML mime type. Setting this option will do so only for browsers that indicate support for XHTML.

behind-reverse-proxy
When enabling this option to indicate that the application is deployed behind a reverse proxy (as would be common if you use the wthttpd connector), the server location is not read from the "Host" header, but from the X-Forwarded-For header, if present.

properties
Application-specific properties which may be accessed using WApplication::readConfigurationProperty(). For example:
      <properties>
        <property name="extBaseURL">/ext/</property>
      </properties>

8.3 FastCGI options (wt_config.xml)

These options only apply to FastCGI-based deployment, and are are specified inside a <connector-fcgi> subsection.

valgrind-path
Set the path to valgrind for debugging using valgrind. This requires that debugging is enabled and debug is passed to the application as last request parameter.

run-directory
The path that is used by the library for managing sessions.

8.4 Wt httpd (command-line or configuration file) options

These options are not specified in the wt_config.xml configuration file, but may be indicated on the command-line, or within a configuration file that is located at /etc/wt/wthttpd.

General options:
  -h [ --help ]                 produce help message
  -t [ --threads ] arg (=10)    number of threads
  --servername arg (=localhost) servername (IP address or DNS name)
  --docroot arg                 document root for static files
  --errroot arg                 root for error pages
  --accesslog arg               access log file (defaults to stdout)
  --no-compression              do not compress dynamic text/html and
                                text/plain responses
  --deploy-path arg (=/)        location for deployment
  --session-id-prefix arg       prefix for session-id's (overrides
                                wt_config.xml setting)
  -p [ --pid-file ] arg         path to pid file (optional)
  -c [ --config ] arg           location of wt_config.xml. If unspecified, 
                                WT_CONFIG_XML is searched in the environment,
                                if it does not exist then the compiled-in
                                default (/etc/wt/wt_config.xml) is tried. If
                                the default does not exist, we revert to
                                default values for all parameters.

HTTP server options:
  --http-address arg    IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)
  --http-port arg (=80) HTTP port (e.g. 80)

HTTPS server options:
  --https-address arg     IPv4 (e.g. 0.0.0.0) or IPv6 Address (e.g. 0::0)
  --https-port arg (=443) HTTPS port (e.g. 443)
  --ssl-certificate arg   SSL server certificate chain file
                          e.g. "/etc/ssl/certs/vsign1.pem"
  --ssl-private-key arg   SSL server private key file
                          e.g. "/etc/ssl/private/company.pem"
  --ssl-tmp-dh arg        File for temporary Diffie-Hellman parameters
                          e.g. "/etc/ssl/dh512.pem"

9. Error-handling and logging

Wt provides logging of events to a log-file (see log-file configuration option). Every log entry has a timestamp, the process id and the session id. Wt uses four different event types, from least to most severe:

notice
Informational notices. These are events that may be interesting for late analysis of other problems, for performance analysis, or estimating server load.

Generated using WApplication::log(), e.g.:

wApp->log("notice") << "Message";

warn
Warnings. These events are generated when you are using the API in a way that may not have been as intended.

Generated using WApplication::log(), e.g.:

wApp->log("warn") << "Message";

error
Non-fatal application errors. These errors indicate for example unexpected input from the web browser or application user, XML parsing problems, but not necessarily a programming error.

Generated using WApplication::log(), e.g.:

wApp->log("error") << "Message";

fatal
Fatal application errors. These errors terminate the current session (but not the application server), and are errors that indicate a programming error. For example, this error is triggered by misuses of the API.

Generated by throwing a std::exception.

You can now proceed to the Treelist example


Generated on Mon Mar 9 08:27:50 2009 for Wt by doxygen 1.5.6