Chapter 3 DynaScript Predefined Objects

session object

Object

The session object is a special object that the Web site uses to store information about a session for a given Web client.

Syntax

To use a session property:

session.propertyName

Description

The session object provides a way of maintaining information while a user of your site navigates through a set of pages.

Web connections and sessions

Web connections are typically sessionless--from your Web client, you can jump from one Web site to another (and back) at any time. The Web site never knows exactly when you have ended your "session" with it.

It is desirable, though, to maintain some concept of a session between the Web client and the Web site. If you, as the Web site, set up a welcome page that asks the user to log in with a name and password, each of the pages that you then make available to them must "know" somehow that the user has already logged in. If, however, they have not logged in (or have not logged in recently), the site needs a way of detecting this to force them to log in again.

Duration of a session

The Dynamo session object provides a way of storing session information so that it persists for the duration of this particular client-to-site connection. Because there is no explicit end to a session, though, the duration of the connection must be decided arbitrarily. Session objects are created once they are accessed.

By default, Dynamo considers a session to last five minutes from the time of the user's last action at a given Web site (you can change this default duration globally or for specific session objects). For the duration of a session, the site maintains information about the user's connection--a login name, their last action, or whatever other information the site requests from the client.

The site stores session information in a session object--one object for each client. A session object is accessible to all Web pages in the site, so they can check its status as they require. After the specified duration elapses (or times out), the session object associated with the client goes away. Web pages accessing the object are still able to query the session object to determine that the session has ended (no longer exists). Null would be returned in this case.

Using the session object

The session object has only one predefined property (timeOut ). You define the additional properties that you want to keep track of during a client's session.

The session information itself typically comes from client input such as an HTML form. A login page, for example, might prompt a user for a name and password.

To check whether or not there is session information available, use:

if ( exists(session) ){
...

The client sends the requested information as a URL with arguments. For example:

http://www.acme.com/check_login.htm?username=hsimpson&password=doh

The receiving document (in this case, check_login.htm ) can then read the incoming values, look them up in a password list or database table, and set a property in the session object accordingly. For example, if the user's login is correct, the following statement sets a user-defined property called loginCorrect :

session.loginCorrect = true;

Until the session times out, other pages can then check the session.loginCorrect property each time they load. For example:

<!--SCRIPT
  if ( !exists(session) || !session.loginCorrect ) {
    document.WriteLn( "Permission denied." );
  } else {
  // show authorized content here
  }
-->

For a working example of the session object used in a login page, see the sample application in the /Site/app folder of the Dynamo demo database.

Using cookies for sessions

Internally, Dynamo implements the session object using cookies, which are small chunks of information passed between a particular Web client and Web site. A cookie provides a way for the site to remember information about that client's session. For more information on cookies and how they store persistent information for a Web connection, see the Netscape Web sitehttp://www.netscape.com .

timeOut property

Syntax

session.timeOut

Description

The duration of the session (in minutes). This property exists only if the timeOut value has been changed from the default of five minutes. To check if this property exists, use:

if ( exists (session.timeOut)) {
. . .

For more information on Dynamo's default cookie timeout see "Changing Dynamo configuration settings" in PowerDynamo User's Guide.

Each session instance can set its own timeOut value.

Example

This script sets a time out of 10 minutes for the session object after a user's login has been validated:

<!--SCRIPT 
  if ( exists (session)
  && session.loginCorrect ){
     session.timeOut = 10;
  }
-->