Library overview

Contents

1. WWidget
1.1 Layout
1.2 Style
1.3 Widget containers
2. Startup
3. Signal/slot mechanism
4. Server-side and Client-side event handling.
5. Painting
6. Deployment
6.1 FastCGI
6.2 Built-in httpd
7. Configuration
7.1 Session management (wt_config.xml)
7.2 General application settings (wt_config.xml)
7.3 FastCGI options (wt_config.xml)
7.4 Wt httpd (command-line or configuration file) options

1. WWidget

A key class in Wt is Wt::WWidget. A WWidget provides abstraction of a visual entity. The entire user-interface is specified by creating a hierarchical structure of WWidgets, starting at the Wt::WApplication::root(), and letting these widgets respond to events.

When a widget is inserted in the tree, ownership is transferred to the tree. Whenever a widget is deleted, all its children are deleted as well. When the WApplication object is deleted, the root of the tree is deleted, and in this way all resources associated with any widget are freed.

Any descendent class of WWidget is a self-contained (reusable) class that encapsulates both the look and behaviour.

1.1 Layout

Widgets are layed out (with a few exceptions) following this hierarchical structure. The capabilities of HTML/CSS do not allow for a general layout system like common in many GUI widget frameworks, without using JavaScript tricks. As an alternative, Wt exposes the layout mechanisms built-in HTML/CSS: every WWidget has some control over its own layout in reference to its immediate parent or siblings.

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.

Nevertheless, Wt has layout classes (see WLayout and descendants). These cannot be used with plain widgets, but they have suitable implementations for Ext widgets, who rely on JavaScript presence anyway. You can thus use these classes to layout within Ext::Container widgets.

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 Wt::WApplication::useStyleSheet().

CSS Style selectors may be used in conjunction with widget style classes that may be set for any widget using Wt::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 inline specification of style, using Wt::WWidget::decorationStyle().

1.3 Widget containers

With a few exceptions, all widgets are child of (and contained in) a container widget such as Wt::WContainerWidget or Wt::WTableCell. A widget is inserted into a WContainerWidget by adding the widget to the container using Wt::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. Startup

From the main() function of your application, you must call the Wt::WRun() to start listening for requests. One parameter to this function is a createApplication function object. For every new session (which corresponds to a new user surfing to your web application), the library calls your createApplication function which must create a new Wt::WApplication object. The request arguments (as part of the WEnvironment object) are passed to this createApplication function, and could thus be used to customize the application or authenticate the user.

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

An application is exited when the user browses away from the application, when WApplication::quit() is called, or when the application server is shut down. In either case, the entire widget tree is properly deleted. Therefore, you should release resources held by your widgets or application in the destructors of these objects.

As of version 2.0.0, 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.

3. Signal/slot mechanism

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 Wt::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 for an object by instantiating a Wt::Signal<> class.

The library defines several userevent 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 (Wt::EventSignal) are signals that may be triggered internally by the library to respond to user interactivity events. Together, the abstract classes Wt::WInteractWidget and Wt::WFormWidget, which are baseclasses of many widgets, provide most of these event signals. Thus, to react to one of these events, the programmer connects a self-defined or already existing slot to the signal.

4. Server-side and 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 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 Wt::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++:

5. Painting

Wt provides a painting system, which you can use to paint vector graphics. In order to use the paint system, you need to reimplement a WPaintedWidget, and use a WPainter to paint the contents of the widget. Depending on the browser support, Wt will use one of three different methods to paint the graphics (SVG, VML or HTML 5 <canvas> element). You can add other painting devices by providing a suitable implementation to WPaintDevice.

6. Deployment

The library is designed so that, besides the application binary, no other files are needed to deploy the application. Obviously, any auxiliary files you use, such as message resource files, graphics, static pages, or anything else, will also need to be deployed.

6.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).

6.2 Built-in httpd

When linking your application against libhttp, the resulting binary is a stand-alone http(s) webserver.

7. Configuration

Wt has one main XML configuration file (which by default is located in /etc/wt/wt_config.xml).

7.1 Session management (wt_config.xml)

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 is allows multiple concurrent sessions from one user)
reload-is-new-session
Should a brower reload spawn a new session (convenient for debuggin) or simply refresh (using Wt::WApplication::refresh()) 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.

7.2 General application settings (wt_config.xml)

max-request-size
The maximum HTTP request size (Kb) that is accepted. An oversized request will result in a Wt::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 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>

7.3 FastCGI options (wt_config.xml)

enable-debug
When debugging is enabled, appending a debug to the initial query will enable debug information.
valgrind-path
Set the path to valgrind for debugging using valgrind.
run-directory
The path that is used by the library for managing sessions.

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

General options:
  -h [ --help ]              produce help message
  -t [ --threads ] arg (=10) number of threads
  --docroot arg              document root for static files
  --errroot arg              root for error pages
  --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 (may be empty)

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"

You can now proceed to the Treelist example


Generated on Mon Apr 14 15:15:00 2008 for Wt by doxygen 1.5.3