Command dispatching and session management
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 ?cmdName? cmdBody
Registers cmdBody as
cmdName. If cmdName is
omitted, "default" is used.
web::getcommand ?cmdName?
Retrieves the body of the command commandName
or of the command "default" if
cmdName is omitted.
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 2. web::cmdurl
% web::cmdurl -notimestamp -urlformat [list scheme host scriptname pathinfo querystring] "test"
http://websh.com/bin/returnmail/member?XDZuRD2rnsfHjFH
%
web::cmdurlcfg ?options? ?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 order to 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
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
- -protocol ?value?
protocol to be used. Defaults to the scheme used to
access the page, which is overridden if the user gives
sets a value.
- -servername ?value?
server name to be used. Default: taken from request.
- -port
port number to be used. Default: 80.
- -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 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.
Note that setting a value to an empty string amounts to
unset.
Note also: 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 such parameter on the command line.
Example 3. web::cmdurl
% web::cmdurl ""
?XDqPtk34XvyPh41gUBo
% web::cmdurlcfg -scriptname bin/test_script
% web::cmdurl ""
bin/test_script?XDqPtk34XvyPh41gUBo
% web::cmdurlcfg -scriptname ""
% web::cmdurl ""
?XDqPtk34XvyPh41gUBo
%
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 string
?content_type?
parse string as POST data input with
type content_type.
content_type can be application/x-www-form-urlencoded
or multipart/form-data;
boundary=xxx. In the second case,
content-type must specify the
boundary as well. By default, POST data is taken from
the request data.
If
string is an empty string, postdata
parsing is turned off.
Default for
content_type is
"application/x-www-form-urlencoded".
-
-postdata channelName
content_length
content_type
As above, but reads the POST data from channel
channelName.
Use the keyword end for
content_length to indicate that
Websh should read all content.
Examples for
content_type include:
- -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 that, 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 4. 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
%
Websh session management consits of two parts:
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.