Session Management

Overview

All WebSubmit application modules are presented as HTML forms.  The user fills out the form and submits it to the server for processing.  Each time the user fills out a given form, this is considered a session in WebSubmit.  It is possible to save these sessions so that they can be loaded at some time in the future.  This reduces the amount of time the user needs to spend filling out the form.  In addition, default sessions exist (both system-wide and user-defined) that are loaded every time a user visits an application.  This not only reduces the time needed to fill out a form, but also provides guidance for users unfamiliar with the application.

Session management capabilities are provided for a subset of the modules distributed with WebSubmit.  In principle, any application module written in Tcl can take advantage of session management.  All that is required is a slight modification of the module code to include the necessary calls to session management routines.  The process of incorporating sessions into WebSubmit applications is detailed below.
 

Implementation

Session Manager
Every application module that allows for session management contains a session manager.  The session manager is created with a single call to the WebSubmit CGI package routine sessionManager.  This routine creates a small group of form elements that can be used to load and save named sessions for the given module.
 

Session Manager:  A call to webSubmit::cgi::sessionManager creates the form elements shown above.  When used in tandem with the other necessary routines, this manager allows users to see what session is currently loaded, to load and delete named library sessions, to load system defaults, and to save the current form elements as the user defaults.

User Session Library
This pull-down menu contains the list of all named sessions for the given module.  It is used in conjunction with the Load Library Session and Delete Selected Session buttons.  If the user has not saved any named sessions, this menu will be empty.

New Session Name
Specifying a name in this text blank and then clicking the corresponding Save button will save the current group of form element values as a named session.  The next time the user loads the form, this named session will appear in the User Session Library.

Load Library Session
Causes the currently selected session from the User Session Library to be loaded.

Load System Defaults
Load the system-wide default session for this module (if it exists).

Delete Selected Session
Deletes the currently selected User Library Session from the user's session library.

Save As Default
Saves the current form element values as the default session for this module.
 

Form Processing with Sessions
Form processing with session management is slightly different than normal form processing.  Basically, session management has to allow for both self-processing of the form and processing by another script.  Self-processing is used whenever some action (e.g., saving a named session) is taken using the session manager; processing by other scripts occurs when the form is submitted for normal execution.  To allow both modes of operation, modules that use session management are all processed by the special script sessionManager.cgi.  This script takes any necessary session actions (saving, loading, deleting sessions) and then performs a CGI redirect depending on how the form was submitted.  If submitted through the session manager, the script redirects back to the submitting module.  If submitted for execution, it saves the current data as a session called lastSession and redirects to the true form processor.
 

Default Sessions
Two types of default sessions exist for any module using session management: system-wide and user-defined.  System-wide defaults are stored in the directory with the module script and are determined by the WebSubmit administrator or module developer.  User-defined values are saved by the user with the session manager.  The question then becomes how to select which default values are to be used.  If both user and system-wide default values exist, user values take precedence.  If only system values exist, these are loaded; if no default values exist, the form is left blank.
 
 

Additional Module Code Required for Session Management

To use session management within a module, the module must both contain some extra code and meet some new restrictions regarding variable naming and processing.  The following code modifications apply to modules written in Tcl.  Extension of modules written in other languages is not currently supported.  The basic outline for session incorporation is as follows:
  1. Variable initialization
  2. Set up form processors
  3. Include session manager in form
  4. Verify that code adheres to restrictions for session management
Variable Initialization
In order for session management to work properly, a list of variables corresponding to form elements must be passed to some intialization routines.  If the form variables are given as var1 ... varn, then the following Tcl code will perform the necessary initialization: This variable initiliazation also performs the function of importing any session variables that may be passed during form self-processing.
 

Set up Form Processors
In order for CGI redirection to function, sessionManager.cgi needs to know the name of the actual form processor to use when the script is submitted by normal means.  To achieve this, export the name of the form processor as a hidden variable using the variable name formProcessor.  The processor used by the form, however, must be given as sessionManger.cgi.
 

Include Session Manager in Form
The session manager should be placed inside the form proper (i.e., within the block <FORM>...</FORM>), and is created with the single call

where $moduleName  is the name of the module that is being processed.  For example, if the module resides in a script called sampleModName.tcl, then $moduleName = sampleModName.
 

Restrictions on Module Code
There are certain restrictions that the module code must meet in order to function properly with the session manager facilities.

  1. Form element values must match form element names.  In this way, importing session information will produce the desired result.  For example, if there is a form element named varName, then its value must be $varName.
  2. Names for variables and buttons cannot coincide with those used within the session manager.  The following names are used by the session manager