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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Wt: Library overview</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.6 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" name="overview">Library overview </a></h1><h2><a class="anchor" name="contents">
Contents</a></h2>
<div style="margin-left: 10px; margin-bottom: 5px;"> <a class="el" href="overview.html#wwidget_sec">1. Widgets</a> <div style="margin-left: 10px; margin-bottom: 7px;"> <a class="el" href="overview.html#layout">1.1 Layout</a> <br>
<a class="el" href="overview.html#style">1.2 Style</a> <br>
<a class="el" href="overview.html#containers">1.3 Widget containers</a> <br>
</div> <a class="el" href="overview.html#urls_sec">2. Application URL(s)</a> <br>
<div style="margin-left: 10px; margin-bottom: 7px;"></div> <a class="el" href="overview.html#application_sec">3. Startup and session management</a> <br>
<div style="margin-left: 10px; margin-bottom: 7px;"></div> <a class="el" href="overview.html#signal_slot">4. Signal/slot event handling</a> <br>
<div style="margin-left: 10px; margin-bottom: 7px;"></div> <a class="el" href="overview.html#eventhandling">5. Optimizing client-side event handling</a> <br>
<div style="margin-left: 10px; margin-bottom: 7px;"></div> <a class="el" href="overview.html#bootstrap">6. Application bootstrap</a> <br>
<div style="margin-left: 10px; margin-bottom: 7px;"> <a class="el" href="overview.html#default_bootstrap">6.1 Default bootstrap</a> <br>
<a class="el" href="overview.html#progressive_bootstrap">6.1 Progressive bootstrap</a> <br>
</div> <a class="el" href="overview.html#sec_painting">7. Painting</a> <br>
<div style="margin-left: 10px; margin-bottom: 7px;"></div> <a class="el" href="overview.html#deployment">8. Deployment</a> <br>
<div style="margin-left: 10px; margin-bottom: 7px;"> <a class="el" href="overview.html#fastcgi">8.1 FastCGI</a> <br>
<a class="el" href="overview.html#wthttpd">8.2 Built-in httpd</a> <br>
</div> <a class="el" href="overview.html#configuration_sec">9. Configuration</a> <div style="margin-left: 10px; margin-bottom: 7px;"> <a class="el" href="overview.html#config_session">9.1 Session management (wt_config.xml)</a> <br>
<a class="el" href="overview.html#config_general">9.2 General application settings (wt_config.xml)</a> <br>
<a class="el" href="overview.html#config_fastcgi">9.3 FastCGI options (wt_config.xml)</a> <br>
<a class="el" href="overview.html#config_wthttpd">9.4 Wt httpd (command-line or configuration file) options</a> <br>
</div> <div style="margin-left: 10px; margin-bottom: 7px;"></div> <a class="el" href="overview.html#error_sec">10. Error-handling and logging</a> </div><h2><a class="anchor" name="wwidget_sec">
1. Widgets</a></h2>
The <a class="el" href="classWt_1_1WWidget.html" title="The abstract base class for a user-interface component.">WWidget</a> class represents a widget, which provides an abstraction of a visual entity. The entire user-interface is specified by creating a hierarchical structure of WWidgets, rooted at <a class="el" href="classWt_1_1WApplication.html#17e118a04d962459484a12989a80bc05" title="Returns the root container.">WApplication::root()</a>. By reacting to events related to these widgets, you can perform business logic, and manipulate the widget hierarchy to update the user interface.<p>
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 <a class="el" href="classWt_1_1WApplication.html" title="Represents an application instance for a single session.">WApplication</a> object is deleted, the root of the tree is deleted, and in this way all resources associated with any widget are free'd.<p>
Any descendent class of <a class="el" href="classWt_1_1WWidget.html" title="The abstract base class for a user-interface component.">WWidget</a> is a self-contained (reusable) class that encapsulates both the look and behaviour, enabling the design of the user interface in an orthogonal way.<h3><a class="anchor" name="layout">
1.1 Layout</a></h3>
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 a CSS based layout, in which case the CSS style properties of the container and children together determine the result: 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.<p>
CSS layout considers two important categories of layout. Text-like widgets (<a class="el" href="classWt_1_1WWidget.html#c78e3af143883334c82031790c87416e">inline</a>) flow with sibling inline widgets in lines, wrapping at the right edge of the parent container. In contrast, widgets displayed as a <a class="el" href="classWt_1_1WWidget.html#c78e3af143883334c82031790c87416e">block </a> stack vertically with respect to sibling widgets. Block widgets allow more control over their position and size than inline widgets, and may also float to the left or right border of the parent container.<p>
Layout managers are implemented by classes that derive from <a class="el" href="classWt_1_1WLayout.html" title="An abstract base class for layout managers.">WLayout</a>. They can be used in conjunction with <a class="el" href="classWt_1_1WContainerWidget.html" title="A widget that holds and manages child widgets.">WContainerWidget</a> or <a class="el" href="classWt_1_1Ext_1_1Container.html" title="A container class which manages its contents using layout managers.">Ext::Container</a> container classes. Note that some layout managers are applicable only to a <a class="el" href="classWt_1_1WContainerWidget.html" title="A widget that holds and manages child widgets.">WContainerWidget</a> and some only to an <a class="el" href="classWt_1_1Ext_1_1Container.html" title="A container class which manages its contents using layout managers.">Ext::Container</a>. Due to limitations in CSS (and pedantic browser implementations), vertical layout is not possible without JavaScript.<h3><a class="anchor" name="style">
1.2 Style</a></h3>
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. External stylesheets may be loaded using <a class="el" href="classWt_1_1WApplication.html#f377d541443b4bcea5fcc40be7c70173" title="Adds an external style sheet.">WApplication::useStyleSheet()</a>, and the internal stylesheet may be manipulated using <a class="el" href="classWt_1_1WApplication.html#6a9a20d65ce9e7c2f62b27387c94e10d" title="Returns a reference to the inline style sheet.">WApplication::styleSheet()</a>.<p>
In the stylesheets, you describe rules that are prefixed by CSS selectors. By setting matching style classes for your widgets using <a class="el" href="classWt_1_1WWidget.html#4be23ecf48d5968efb5d926e38e01708" title="Sets (one or more) CSS style classes.">WWidget::setStyleClass()</a>, these rules will be applied to your widgets. The recommended way for visual response to events is by changing the style class for the widget.<p>
In addition to style sheets, Wt also supports the direct manipulation of a widget's style, using <a class="el" href="classWt_1_1WWidget.html#c1833c7c01599b3733712ab0bf3c3a0a" title="Returns the decoration style of this widget.">WWidget::decorationStyle()</a>.<h3><a class="anchor" name="containers">
1.3 Widget containers</a></h3>
With a few exceptions, all widgets are child of (and contained in) a container widget such as <a class="el" href="classWt_1_1WContainerWidget.html" title="A widget that holds and manages child widgets.">WContainerWidget</a> or <a class="el" href="classWt_1_1WTableCell.html" title="A container widget that represents a cell in a table.">WTableCell</a>. A widget may be inserted into a <a class="el" href="classWt_1_1WContainerWidget.html" title="A widget that holds and manages child widgets.">WContainerWidget</a> by adding the widget to the container using <a class="el" href="classWt_1_1WContainerWidget.html#2cfe66d9b62940f889e99538a9f478d2" title="Adds a child widget to this container.">WContainerWidget::addWidget()</a>, or by passing the parent container as an argument to its constructor. You may also add a widget to a container using a layout manager.<h2><a class="anchor" name="urls_sec">
2. Application URL(s)</a></h2>
A Wt application, like any other CGI application, is deployed at a single location (URL) within your web server. In this mode, a Wt application is a single page web application: the URL does not change. 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 <a class="el" href="classWt_1_1WApplication.html#2c1a10aadc0d7ed877b5715b42ca4911" title="Change the internal path.">WApplication::setInternalPath()</a>. When the internal path changes, 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.<p>
To avoid rerendering the entire widget tree for each internal path change, when AJAX is available, the internal path is indicated using a name anchor (#) after the deployment URL. For a plain HTML session, the session ID is appended to the URL to avoid the session from reloading when the user navigates using a <a class="el" href="classWt_1_1WAnchor.html" title="A widget that represents an HTML anchor (to link to other documents).">WAnchor</a> to a new internal URL.<p>
To effectively change the internal path and obtain consistent behaviour with or without JavaScript, you should use a <a class="el" href="classWt_1_1WAnchor.html" title="A widget that represents an HTML anchor (to link to other documents).">WAnchor</a> to let the user navigate to a new internal path. The easiest way to do this is by using the <a class="el" href="classWt_1_1WAnchor.html#e3ea26646f135bf133871564f5d6798d" title="Sets the destination URL as an internal path.">WAnchor::setRefInternalPath()</a>. This refers the <a class="el" href="classWt_1_1WAnchor.html" title="A widget that represents an HTML anchor (to link to other documents).">WAnchor</a> to a URL generated by <a class="el" href="classWt_1_1WApplication.html#37b4cf44f393688785ed3b34f53fead1" title="Returns a bookmarkable URL for the current internal path.">WApplication::bookmarkUrl()</a> for the new internal path (handling the plain HTML case), and binds a JavaScript slot to its <a class="el" href="classWt_1_1WInteractWidget.html#e11e050cce0d4a8f742afa3ef92bfe8c" title="Event signal emitted when a mouse key was clicked on this widget.">WAnchor::clicked()</a> signal, which changes the internal path (handling the AJAX case).<p>
Finally, you can listen for path changes using the <a class="el" href="classWt_1_1WApplication.html#3e68c4b6bb387f27a614e7962e11967b" title="Signal which indicates that the user changes the internal path.">WApplication::internalPathChanged()</a> event to react to the user navigating through his history.<p>
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 <a class="el" href="classWt_1_1WAnchor.html#cf0206a2ac91ea67d68ba10e3a951ba3" title="Sets the destination URL.">WAnchor::setRef()</a>, <a class="el" href="classWt_1_1WImage.html#cea9ce518f4eec6b19fd4bacc44a52e8" title="Sets the image URL.">WImage::setImageRef()</a>, <a class="el" href="classWt_1_1WApplication.html#f377d541443b4bcea5fcc40be7c70173" title="Adds an external style sheet.">WApplication::useStyleSheet()</a>, etc...) are automatically replaced by Wt with an absolute URL that resolves these directly within the deployment location. You should use absolute URLs in your own CSS or XHTML snippets when you wish these snippets to work regardless of the internal path in a plain session, since these cannot be fixed by Wt.<h2><a class="anchor" name="application_sec">
3. Startup and session management</a></h2>
In your application, e.g. from within your main(), you should <a class="el" href="classWt_1_1WServer.html#bca6890dab44d87bd3af64705ac072d3" title="Runs the Wt application server.">WRun()</a> 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 <a class="el" href="classWt_1_1WServer.html#bca6890dab44d87bd3af64705ac072d3" title="Runs the Wt application server.">WRun()</a> function is a <em>createApplication</em> function object. Alternatively, if you wish to have more control over the application server, you may also instantiate and configure a <a class="el" href="classWt_1_1WServer.html" title="A class encapsulating an application server.">WServer</a> instance directly.<p>
For every new session (which corresponds to a new user accessing your web application), the library calls your createApplication callback function to create a new <a class="el" href="classWt_1_1WApplication.html" title="Represents an application instance for a single session.">WApplication</a> object for that session. The request arguments (as part of the <a class="el" href="classWt_1_1WEnvironment.html" title="A class that captures information on the application environment.">WEnvironment</a> object) are passed to this createApplication function, and may be used to customize the application or authenticate the user. See also <a class="el" href="overview.html#bootstrap">6. Application bootstrap</a> for details on the application bootstrap method.<p>
At all times, the <a class="el" href="classWt_1_1WApplication.html" title="Represents an application instance for a single session.">WApplication</a> instance is accessible using the static method <a class="el" href="classWt_1_1WApplication.html#38d922da0a0d83395519f3eaab85d0f6" title="Returns the current application instance.">WApplication::instance()</a>, and is useful to inspect startup arguments and settings (using <a class="el" href="classWt_1_1WApplication.html#19f3b913f4bc2f69761d9a3738bf142b" title="Returns the environment information.">WApplication::environment()</a>), to set or change the application title (<a class="el" href="classWt_1_1WApplication.html#71a3f7da5abb9a76df94fab69ba61670" title="Sets the window title.">WApplication::setTitle()</a>), to specify a locale (<a class="el" href="classWt_1_1WApplication.html#5c9cc1350019d69f154a2b44cdaf2596" title="Changes the locale.">WApplication::setLocale()</a>) for rendering, and many other application-wide settings. In a multi-threaded environment, access to this instance is implemented using thread local storage.<p>
A session exits when the user browses away from the application, when <a class="el" href="classWt_1_1WApplication.html#5231d54ed34982f4366058eb6440c8f7" title="Quits the application.">WApplication::quit()</a> 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.<p>
The library offers two different mechanisms to map sessions onto processes: <b>dedicated processes</b> (only with FastCGI deployment) and <b>shared processes</b>. 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.<h2><a class="anchor" name="signal_slot">
4. Signal/slot event handling</a></h2>
To respond to user-interactivity events, or in general to communicate events from one widget to any other, Wt uses a signal/slot system.<p>
A slot is any method of any descendant of <a class="el" href="classWt_1_1WObject.html" title="A base class for objects that participate in the signal/slot system.">WObject</a>. 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).<p>
A signal may be created by adding a <a class="el" href="classWt_1_1Signal.html">Signal<X, ...></a> 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.<p>
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.<p>
Event signals (<a class="el" href="classWt_1_1EventSignal.html">EventSignal<E></a>) are signals that may be triggered internally by the library to respond to user interactivity events. The abstract base classes <a class="el" href="classWt_1_1WInteractWidget.html" title="An abstract widget that can receive user-interface interaction.">WInteractWidget</a> and <a class="el" href="classWt_1_1WFormWidget.html" title="An abstract widget that corresponds to an HTML form element.">WFormWidget</a> 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.<h2><a class="anchor" name="eventhandling">
5. Optimizing client-side event handling</a></h2>
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 invoke the call-back code, and visual changes will be updated in the web page.<p>
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.<p>
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 <a class="el" href="classWt_1_1WObject.html#c00d775170f47e715894b24de6b869da" title="Declares a slot to be stateless and learn client-side behaviour on first invocation...">WObject::implementStateless</a> for details, or the <a class="el" href="example.html">Treelist example</a> 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.<p>
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.<p>
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++:<p>
<ul>
<li>
Using <a class="el" href="classWt_1_1JSlot.html" title="A slot that is only implemented in client side JavaScript code.">JSlot</a>, you can specify the JavaScript for a slot, when connected to an <a class="el" href="classWt_1_1EventSignal.html" title="A signal that conveys user-interface events.">EventSignal</a>. </li>
<li>
Using <a class="el" href="classWt_1_1JSignal.html" title="A signal to relay JavaScript to C++ calls.">JSignal</a>, you can emit a C++ signal from JavaScript code, using a JavaScript function <code>Wt.emit()</code>. </li>
<li>
Using <a class="el" href="classWt_1_1WApplication.html#2a92457b9212cef4057cb54e56183967" title="Executes some JavaScript code.">WApplication::doJavaScript()</a>, you can call JavaScript code directly as part of event handling. </li>
</ul>
<h2><a class="anchor" name="bootstrap">
6. Application bootstrap</a></h2>
A Wt application may support both plain HTML and Ajax-enabled user agents. When a first request is made for a new session, there is no way of knowing whether the agent supports Ajax (and has it enabled). The bootstrap procedure therefore has two strategies of making the choice between a plain HTML and Ajax-enabled application mode.<h3><a class="anchor" name="default_bootstrap">
6.1 Default bootstrap</a></h3>
In the default bootstrap mode, for the normal case, a small bootstrap HTML file is served, which detects presence of AJAX (and various other environment properties such as presence of an internal path as an anchor, cookie support, and IE VML DPI setting). If no JavaScript support is available, it automatically redirects the user to a plain HTML version of the application.<p>
In this mode, the application is not started until the library has determined AJAX support, which is made available in <a class="el" href="classWt_1_1WEnvironment.html#f39702064f91a549514f28de713b7cd2" title="Returns whether the browser has enabled support for AJAX.">WEnvironment::ajax()</a> which is passed to the application constructor.<p>
In some special cases, this bootstrap is skipped and a plain HTML version is served. This is for user agents that are identified as spider bots, or user agents which are configured to not support AJAX (well), see the <a class="el" href="overview.html#config_general">user-agents configuration setting</a>.<p>
There are some draw-backs to this bootstrap method: <ul>
<li>
the redirection without JavaScript support may not be supported by all user agents, leaving these with a link and a redirect message (see the <a class="el" href="overview.html#config_general">redirect-message configuration setting</a>) </li>
<li>
there is an additional round-trip before any contents is rendered </li>
<li>
for an AJAX user interface, all contents will be loaded through JavaScript. This has a draw-back that IE may delay applying external stylesheets after the contents has been rendered, which might cause some confusion, and some 3rd party JavaScript libraries do not support being loaded on-demand (with as most notable example, Google ads). </li>
</ul>
<h3><a class="anchor" name="progressive_bootstrap">
6.1 Progressive bootstrap</a></h3>
Since Wt 2.99.4, a new bootstrap method has been added (initially proposed by Anthony roger Buck). While the default bootstrap already honors the principle of graceful degradation, this bootstrap implements this using the principle of <a href="http://en.wikipedia.org/wiki/Progressive_enhancement">progressive enhancement</a> (and quite literally so).<p>
This bootstrap method may be enabled with the <a class="el" href="overview.html#config_general">progressive-bootstrap configuration setting</a>.<p>
This bootstrap method will initially assume that the user agent is a plain HTML user-agent and immediately create the application (with <a class="el" href="classWt_1_1WEnvironment.html#f39702064f91a549514f28de713b7cd2" title="Returns whether the browser has enabled support for AJAX.">WEnvironment::ajax()</a> always returning <code>false</code>). The initial response will contain the initial page suitable for a plain HTML user-agent.<p>
JavaScript embedded in this page will sense for AJAX support and trigger a second request which progresses the application to an AJAX application (without repainting the user interface). To that extent, it will change <a class="el" href="classWt_1_1WEnvironment.html#f39702064f91a549514f28de713b7cd2" title="Returns whether the browser has enabled support for AJAX.">WEnvironment::ajax()</a> to return <code>true</code>, and invoke <a class="el" href="classWt_1_1WApplication.html#78016406c4746c56b2c2ffce7c5e181f" title="Progresses to an Ajax-enabled user interface.">WApplication::enableAjax()</a> which in turn propagates <a class="el" href="classWt_1_1WWidget.html#919a4eaf68ff52f06f6a726d55dfb768" title="Progresses to an Ajax-enabled widget.">WWidget::enableAjax()</a> through the widget hierarchy. This upgrade happens in the back-ground, unnoticed to the user.<p>
This mitigates disadvantages associated with the default bootstrap, but has the draw-backs of being a recent development in Wt, and it requires slightly more server-side processing.<h2><a class="anchor" name="sec_painting">
7. Painting</a></h2>
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 quality, and can be embedded within the HTML, avoiding an additional round-trip. To use the paint system, you need to specialize <a class="el" href="classWt_1_1WPaintedWidget.html" title="A widget that is painted using vector graphics.">WPaintedWidget</a> and use a <a class="el" href="classWt_1_1WPainter.html" title="Helper class for painting on a WPaintDevice.">WPainter</a> to paint the contents of the widget inside its <a class="el" href="classWt_1_1WPaintedWidget.html#d8ce22eff41754c8616f45851f57fb1a" title="Paints the widget.">WPaintedWidget::paintEvent()</a>.<h2><a class="anchor" name="deployment">
8. Deployment</a></h2>
The library is designed so that, besides the application binary, only files from the <code>resources/</code> folder are needed to deploy the application. The resources folder contains icons, style sheets associated with themes, and other resources specific for special widgets. In addition, any auxiliary files you use, such as message resource files, graphics, static pages, or anything else, will also need to be deployed.<p>
The URL at which the <code>resources/</code> folder is deployed is based on the <em>resourcesURL</em> configuration property (see see <a class="el" href="overview.html#config_general">configuration properties</a>), which defaults to "/resources".<h3><a class="anchor" name="fastcgi">
8.1 FastCGI</a></h3>
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).<h3><a class="anchor" name="wthttpd">
8.2 Built-in httpd</a></h3>
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.<h2><a class="anchor" name="configuration_sec">
9. Configuration</a></h2>
Wt has one main XML configuration file (which by default is located in <code>/etc/wt/wt_config.xml</code>, and can be overridden with the WT_CONFIG_XML environment variable or the <code>--config</code> startup parameter for wthttpd).<p>
The configuration file may specify several <b><application-settings></b>. The settings that apply are determined by the <em>location</em> 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).<h3><a class="anchor" name="config_session">
9.1 Session management (wt_config.xml)</a></h3>
These are options related to session management, and are specified inside <b><session-management></b> subsection.<p>
<dl>
<dt><b>dedicated-process</b> </dt>
<dd>Every session is mapped a dedicated process, allowing maximal session isolation, but at an increased session cost. <br>
This is currently only supported using the FastCGI connector.<p>
</dd>
<dt><b>shared-process</b> </dt>
<dd>Sessions share a fixed number of processes, yielding a lower session cost. <br>
This is the only option for the Wthttpd connector.<p>
</dd>
<dt><b>tracking</b> </dt>
<dd>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). <p>
</dd>
<dt><b>reload-is-new-session</b> </dt>
<dd>Should a brower reload spawn a new session (convenient for debugging) or simply refresh (using <a class="el" href="classWt_1_1WApplication.html#02b9d8aa1b6c2d0dc9edc1b9c63f86dc" title="Refreshes the application.">WApplication::refresh()</a>) 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.<p>
</dd>
<dt><b>timeout</b> </dt>
<dd>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. </dd>
</dl>
<h3><a class="anchor" name="config_general">
9.2 General application settings (wt_config.xml)</a></h3>
These options are indicated directly within <b><application-settings></b>, and specify settings that affect the run-time behaviour of the application.<p>
<dl>
<dt><b>debug</b> </dt>
<dd>When debugging is enabled, JavaScript errors are not caught, and thus will provide stack information when using a JavaScript debugger.<p>
</dd>
<dt><b>log-file</b> </dt>
<dd>Path to the log file used for application logging (see <a class="el" href="classWt_1_1WApplication.html#75067771ba8fcc56e174f2e741ce278f" title="Adds an entry to the application log.">WApplication::log()</a>). 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. <p>
</dd>
<dt><b>max-request-size</b> </dt>
<dd>The maximum HTTP request size (Kb) that is accepted. An oversized request will result in a <a class="el" href="classWt_1_1WApplication.html#ef3a8fa2a7825ed7439707d8a90b08aa" title="Signal which indicates that too a large request was received.">WApplication::requestTooLarge()</a> signal. <p>
</dd>
<dt><b>session-id-length</b> </dt>
<dd>The length (in number of characters) for the unique session ID.<p>
</dd>
<dt><b>session-id-prefix</b> </dt>
<dd>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.<p>
</dd>
<dt><b>send-xhtml-mime-type</b> </dt>
<dd>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 <a class="el" href="classWt_1_1WSvgImage.html" title="A paint device for rendering using Scalable Vector Graphics (SVG).">WSvgImage</a>), it is necessary to present an XHTML mime type. Setting this option will do so only for browsers that indicate support for XHTML. <p>
</dd>
<dt><b>redirect-message</b> </dt>
<dd>When the default bootstrap method is used, this message is used in the link which redirects to the user to a plain HTML version, in case his user agent does not support the automatic redirect.<p>
</dd>
<dt><b>behind-reverse-proxy</b> </dt>
<dd>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 <code>X-Forwarded-For</code> header, if present.<p>
</dd>
<dt><b>user-agents</b> </dt>
<dd>Wt considers three types of sessions: <ul>
<li>
AJAX sessions: use AJAX and JavaScript </li>
<li>
plain HTML sessions: use plain old server POSTs </li>
<li>
bots: have clean internal paths, no persistent sessions, and no html <form> elements. </li>
</ul>
<p>
<p>
By default, Wt does a browser detection to distinguish between the first two: if a browser supports JavaScript (and has it enabled), and has an AJAX DOM API, then AJAX sessions are chosen, otherwise plain HTML sessions.<p>
<p>
Here, you may indicate which user agents should or should not receive an AJAX session regardless of what they report as capabilities, and which user agents should be treated as search bots. <p>
</dd>
<dt><b>progressive-bootstrap</b> </dt>
<dd>This boolean configuration option configures which bootstrap method is used, see <a class="el" href="overview.html#bootstrap">6. Application bootstrap</a>. <p>
</dd>
<dt><b>properties</b> </dt>
<dd>Application-specific properties which may be accessed using <a class="el" href="classWt_1_1WApplication.html#c0f5599ed35eb159fa6912aa0ff3c75c" title="Reads a configuration property.">WApplication::readConfigurationProperty()</a>. For example: <div class="fragment"><pre class="fragment"> <properties>
<<span class="keyword">property</span> name=<span class="stringliteral">"extBaseURL"</span>>/ext/</<span class="keyword">property</span>>
<<span class="keyword">property</span> name=<span class="stringliteral">"resourcesURL"</span>>/resources</<span class="keyword">property</span>>
</properties>
</pre></div> </dd>
</dl>
<h3><a class="anchor" name="config_fastcgi">
9.3 FastCGI options (wt_config.xml)</a></h3>
These options only apply to FastCGI-based deployment, and are are specified inside a <b><connector-fcgi></b> subsection.<p>
<dl>
<dt><b>valgrind-path</b> </dt>
<dd>Set the path to valgrind for debugging using valgrind. This requires that debugging is enabled and <code>debug</code> is passed to the application as last request parameter.<p>
</dd>
<dt><b>run-directory</b> </dt>
<dd>The path that is used by the library for managing sessions. </dd>
</dl>
<h3><a class="anchor" name="config_wthttpd">
9.4 Wt httpd (command-line or configuration file) options</a></h3>
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.<p>
The configuration file syntax is line based: <ul>
<li>
<p>
A line in the form: <p>
<code>name = value</code> <p>
gives a value to an option. <p>
</li>
<li>
<p>
The <code>#</code> character introduces a comment that spans until the end of the line. </li>
</ul>
<p>
<div class="fragment"><pre class="fragment">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-<span class="keywordtype">id</span>-prefix arg prefix for session-<span class="keywordtype">id</span>'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"
</pre></div><h2><a class="anchor" name="error_sec">
10. Error-handling and logging</a></h2>
Wt provides logging of events to a log-file (see the <a class="el" href="overview.html#config_general">log-file configuration setting</a>). Every log entry has a timestamp, the process id and the session id. Wt uses four different event types, from least to most severe:<p>
<dl>
<dt><b>notice</b> </dt>
<dd>Informational notices. These are events that may be interesting for late analysis of other problems, for performance analysis, or estimating server load.<p>
<p>
Generated using <a class="el" href="classWt_1_1WApplication.html#75067771ba8fcc56e174f2e741ce278f" title="Adds an entry to the application log.">WApplication::log()</a>, e.g.: <div class="fragment"><pre class="fragment">wApp->log(<span class="stringliteral">"notice"</span>) << <span class="stringliteral">"Message"</span>;
</pre></div> <p>
</dd>
<dt><b>warn</b> </dt>
<dd>Warnings. These events are generated when you are using the API in a way that may not have been as intended.<p>
<p>
Generated using <a class="el" href="classWt_1_1WApplication.html#75067771ba8fcc56e174f2e741ce278f" title="Adds an entry to the application log.">WApplication::log()</a>, e.g.: <div class="fragment"><pre class="fragment">wApp->log(<span class="stringliteral">"warn"</span>) << <span class="stringliteral">"Message"</span>;
</pre></div> <p>
</dd>
<dt><b>error</b> </dt>
<dd>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.<p>
<p>
Generated using <a class="el" href="classWt_1_1WApplication.html#75067771ba8fcc56e174f2e741ce278f" title="Adds an entry to the application log.">WApplication::log()</a>, e.g.: <div class="fragment"><pre class="fragment">wApp->log(<span class="stringliteral">"error"</span>) << <span class="stringliteral">"Message"</span>;
</pre></div> <p>
</dd>
<dt><b>fatal</b> </dt>
<dd>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.<p>
<p>
Generated by throwing a std::exception. </dd>
</dl>
<p>
You can now proceed to <a class="el" href="InstallationUnix.html">Installation: Unix-like platforms</a> or <a class="el" href="InstallationWindows.html">Installation: Windows</a> </div>
<hr size="1"><address style="align: right;"><small>
Generated on Fri Mar 26 17:12:06 2010 for <a href="http://www.webtoolkit.eu/wt/">Wt</a> by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6</small></address>
</body>
</html>
|
