Command dispatching and session management

Command dispatching and session management
Prev		Next

Websh provides a command dispatching mechanism to produce, for example, different HTML pages within one "application", which is most likely one file on the file system. The name of the command to be used for a particular page is encoded in the querystring (see web::cmdurl for details on how to produce such querystrings). Command dispatching is initiated with the command web::dispatch. Commands are defined with web::command.

web::command

web::command ?cmdName? cmdBody

Registers cmdBody as cmdName. If cmdName is omitted, "default" is used.

Example 2. Simple command dispatching

proc page {title code} {
    web::put "<html><title>[web::htmlify $title]</title><body>"
    web::put "<h1>[web::htmlify $title]</h1>"
    uplevel 1 $code
    web::put {</body></html>}
}

web::command default {
    page "Home" {
	web::put "<a href=\"[web::cmdurl page1]\">Link to Page 1</a>"
	web::put "<br/>"
	web::put "<a href=\"[web::cmdurl page2]\">Link to Page 2</a>"
    }
}

web::command page1 {
    page "Page 1" {
	web::put "<a href=\"[web::cmdurl default]\">Home</a>"
    }
}

web::command page2 {
    page "Page 2" {
	web::put "<a href=\"[web::cmdurl default]\">Home</a>"
    }
}

web::dispatch

web::getcommand

web::getcommand ?cmdName?

Retrieves the body of the command commandName or of the command "default" if cmdName is omitted.

web::cmdurl

web::cmdurl ?options? cmdName ?key-value-list?

web::cmdurl ?options? cmdName ?k1 v1 ... kN vN?

Options are: -notimestamp, and -urlformat

Generate URLs including querystring. By default, URLs are self-referencing, but the exact output is subject to configuration. The querystring is encrypted, using the encryption method specified by configuration (see web::config). If cmdName is "", no command parameter is produced in the query string.

-notimestamp

do not add a timestamp to the URL.

-urlformat list

specify what items will be used to format just this URL. Default is: {scriptname pathinfo querystring}.

Note: Use web::cmdurlcfg to define the url format for all URLs produced by web::cmdurl in one request.

scheme: include the protocol, only "http" and "https" are currently supported.
host: include the host name, e.g. "websh.com".
port: include the port, e.g. "80"
Trying to set this item without host will throw an error.
scriptname: include scriptname, e.g. "/cgi-bin/orderbooks".
pathinfo: include pathinfo, e.g. "/merchants/shop1".
querystring: include the querystring, e.g. "select=download".

Note

Note that there are two more commands that control the output of web::cmdurl: web::config cmdparam and web::config timeparam.

Example 3. web::cmdurl

% web::cmdurl -notimestamp -urlformat [list scheme host scriptname pathinfo querystring] "test"
http://websh.com/bin/returnmail/member?XDZuRD2rnsfHjFH
%

web::cmdurlcfg

web::cmdurlcfg ?option? ?key? ?value?

Command options are exactly like those of web::param.

web::cmdurlcfg option ?value?

Options are -scheme, -host, -port, -scriptname, -pathinfo, -querystring, -urlformat

If value is omitted, the current value is returned. Otherwise, the value is stored. Configuration for web::cmdurl. This command serves two purposes:

management of static parameters
configuration for web::cmdurl

By "static parameters", we mean those which are set for every page, instead of set on a per-page basis.

Management of static parameters

In addition to the easy way of tracking parameters using web::dispatch -track ..., specific values for parameters can be set using web::cmdurlcfg: In order to explicitly set, retrieve, append or unset static parameters, use the syntax of the web::param command, for example:

web::cmdurlcfg -set key value: add the static parameter key.
web::cmdurlcfg -names: returns a list of all known static parameters.

Important: web::cmdurl compares every key from the static parameters (see web::cmdurlcfg) against the keys from the command line. The static parameter is only used if there is no parameter of the same name given on the command line.

Configuration for web::cmdurl

-scheme ?value?: protocol to be used. Defaults to the scheme used to access the page, which is overridden if the user sets a value.
-host ?value?: server name to be used. Default: taken from request.
-port: port number to be used. Default: taken from request, 80 if not available.
-scriptname: name of CGI executable. Default: taken from request.
-pathinfo: path info (path after scriptname). Default: taken from request.
-urlformat list: changes the urlformat permanently. See web::cmdurl for the description of this option.

In all these cases, "web::cmdurlcfg -option value" sets the value of the given option and returns the value that was used before the change, while "web::cmdurlcfg -option" returns the current value. If no value has been set using web::cmdurlcfg, but is requested for the URL generation, the value from the request will be used. This value, however, can not be retrieved using web::cmdurlcfg.

-reset: will reset the web::cmdurlcfg configuration. Note however, that static parameters will not be reset by this option. To get rid of static parameters configured with the -set option, use -unset with (for a specific parameter) or without (for all parameters) key.

Note that setting a value to an empty string is the same as using -unset.

Also note: web::cmdurl compares every key from the static parameters against the keys from the command line. The static parameter is only used if there is no such parameter on the command line.

Example 4. web::cmdurl and web::cmdurlcfg

% web::cmdurl ""
?XDqPtk34XvyPh41gUBo
% web::cmdurlcfg -scriptname bin/test_script
% web::cmdurl ""
bin/test_script?XDqPtk34XvyPh41gUBo
% web::cmdurlcfg -scriptname ""
% web::cmdurl ""
?XDqPtk34XvyPh41gUBo
% web::cmdurlcfg -urlformat {scheme host port querystring}
scriptname pathinfo querystring
% # for clearer view on what happens: disable querystring encryption
% web::config encryptchain {}
web::encryptd
% web::cmdurlcfg -set foo bar
bar
% web::cmdurlcfg -host tcl.apache.org
% web::cmdurl zoo
http://tcl.apache.org:80?foo=bar&cmd=zoo&t=1141776460
% web::cmdurlcfg -reset
% web::cmdurl zoo
?foo=bar&cmd=zoo&t=1141776496
% web::config cmdurltimestamp 0
1
% web::config cmdparam page
cmd
% web::cmdurl zoo
?foo=bar&page=zoo
%

web::dispatch

web::dispatch ?options?

Options are: -cmd, -querystring, -postdata, -track and -hook.

Parse information and call a command.

-cmd cmdName

switch into command cmdName. If cmdName is an empty string, no command is called. By default, cmdName is taken from the querystring.

-querystring string

parse string as the querystring. If string is an empty string, querystring parsing is turned off. By default, querystring is taken from the request data (CGI environment or apache module request object).

-postdata ""

do not parse any post data.

-postdata ?#?channelName ?content_length? ?content_type?

parse channel channelName (or variable named channelName if # is given) as POST data input with length content_length and type content_type. content_type can be application/x-www-form-urlencoded or

multipart/form-data;
		  boundary=xxx

. In the case of multipat form data, content-type must specify the boundary as well. By default, POST data is taken from the request data.

Default for content_type is application/x-www-form-urlencoded. Default for content_length is to read a channel up to EOF or the full content of the variable.

Use the keyword end for content_length to indicate that Websh should read all content.

Supported content types are:

multipart/form-data; boundary=xxxx
application/x-www-form-urlencoded (default)

-track paramKeyList

Track a parameter: register it as "static" for the generation of URLs with web::cmdurl. Thus, each parameter with the key in paramKeyList will be repeated in every URL generated with web::cmdurl. See the documentation of web::cmdurl for details.

-hook code

Causes web::dispatch to eval code just before the command (from any source) is evaluated. When code is evaluated, the full request information has been parsed. That is, web::param, web::formvar etc. will have up-to-date information when code is evaluated.

Note: If no command is passed to web::dispatch either in the querystring or with the -cmd option, web::dispatch will call the command "default".

Example 5. web::command and web::dispatch

% set tst {puts "On the hook"}
puts "On the hook"
% web::command acmd {puts "this is acmd"}
% web::dispatch -cmd acmd -querystring "" -postdata ""
this is acmd
% web::dispatch -cmd acmd -querystring "" -postdata "" -hook $tst
On the hook
this is acmd
% set data "a=b&c=d"
a=b&c=d
% web::dispatch -cmd "" -querystring "" -postdata #data
% web::formvar a
b
% web::formvar c
d
%

Session management

Websh session management consits of two parts:

session id tracking
session context management

Session context managers are described in detail below (web::filecontext, web::cookiecontext). Session id tracking is managed by web::dispatch -track. The two parts are connected with the -attachto option of the session context manager. The control is as follows:

A user uses the Websh script for the first time.web::dispatch -track will not see any session id, and, consequently, not set the static parameter id.
Within the application, the session is initialized using mgr::init. init will find no static parameter id (which has been specified at creation time of the session manager using the -attachto option). Now, it tries to create a new session id. This will be possible if a session id generator has been specified when the manager was created using the -idgen option. From now, on the session id will be a static parameter, and will therefore be present in every URL generated with web::cmdurl.
The next time the user visits the Websh application using one of these URLs, web::dispatch will detect the session id, and mgr::init will directly load the corresponding session context without generating a new session id.

Example 6. Examples

See http://tcl.apache.org/websh/examples.ws3 for several sample application demonstrating Websh's session management facilities.