Session Mode Introduction by Keith Oustalet

In the previous section on creating FORMs, we demonstrated a mechanism for passing variables from one page to another, and we showed how heitml gains access to the values stored in those variables by adding "ff." to the variable name.

Although this is a practical, simple and easy-to-learn method, and certainly much less time-consuming than the effort that would otherwise be involved in learning a Scripting Language, there is, unfortunately, one area where it still suffers from the same drawback as any CGI Scripting Language; namely, that once a set of variables have been processed, subsequent pages have no memory of their existence, unless you make the effort of preserving them by writing them to a database. Although it is indeed possible to do this, as we have so recently demonstrated in our Guestbook example, the solution adds a problem of its own. Not all variables are worthy of long-term storage. Therefore, unless you also develop a set of maintenance programs or procedures to purge your databases, your hard disk would soon fill up with data values that have accumulated from every person who ever visited your Web Site.

The question then is whether or not a means could be found to maintain variables in a persistent state as they pass among various Web Pages, without also introducing the burdensome maintenance chores of periodically purging unwanted data from your databases.

heitml Session Mode solves this problem because it is designed to work transparently. Every variable of the type se.name is automatically preserved, ready for processing whenever it is needed. Session Mode's biggest strength lies in the fact that it stores all your program variables in large, self-organizing data structures. No longer do you have to maintain a list of important variables to pass from page to page. No longer do you have to worry about the chance of finding yourself deep into the design of a multi-page application, only to realize that you've forgotten to preserve a much-needed value from an earlier page. With Session Mode, you can create variables at will, on any page where they are needed, and simply forget about them until they are needed again.

Here are just a few of the things Session Mode makes possible:

• For wizards: to keep user input over several pages.
• For database search applications: storing the complete result of queries in Session Variables and allowing the User to scroll through them in a pre-defined sub-window of the Browser display.
• For shopping applications: You can fill a Shopping Cart full of items and, when the User indicates a desire to go to the "Check-out Counter", all price and quantity information is ready to be summarized and submitted for approval. The User can change his mind at the last minute and delete unwanted items, or go back to retrieve items he may have forgotten.

A Quick Example

Session mode keeps all the variables named se.name, where name specifies a particular variable on any page of your Session Mode Application. Session variables can use any data type you like, including tuples and arrays.

To use session mode you need to include the ses.hei Library. Furthermore, all Source Code from a Session Mode Web Page must be contained within the boundaries of the <session> environment Tag. Also, any links to other pages must be of a special type. Instead of the normal HTML Anchor Tag <a> you simply substitute the <sa ...> Tag, which tells Session Mode to log and/or update any values it encountered on that page, and make them available to subsequent pages.

Here's what a very simple Session Mode page might look like:

Filename: sessimp.hei
<include name="ses.hei"/> <session mode="create"> <let se.i=default(se.i,0)+1> The number is <? se.i>. <sa href="sessimp.hei">Increment</sa> </session>

A page defined as above would show a counter, and whenever the User clicked on the "Increment" link, it would add one to the counter.

How does it work?

You don't really need to know how Session Mode works internally, but it can sometimes be helpful (during debugging for instance) to be familiar with the underlying mechanism.

When a User enters a Session Mode page, a Session Card Number is assigned (currently made up by the date, time, and IP-number). After processing, any Session Variables appearing on the page are written to a file containing the same name as the card number.

When the User requests a subsequent page, the Session Variables are automatically read in again. (Naturally, this assumes that the page being linked to was defined using the special <sa ...> Anchor Tag; that it includes the ses.hei library; employs the se.name variable naming convention; and wraps them within the boundaries of the <session> ... </session> environment Tags.

The Session Card Number is passed as an identifier from the first page to the second one by adding it to the URL. This is why you need to use the special <sa ...> Tag instead of the normal HTML Anchor Tag, because it automatically adds the Card Number to the requested URL.

Starting pages and Inner pages

When using Session Mode, many of your pages will require certain Session Variables to have been set already. Such pages are called "inner" pages, because they must always be called from another Session Mode page. In contrast to this, pages that start a Session are called "starting" pages. By carefully setting your links, you can ensure that inner pages are always called properly (except when a User types the URL of such a page directly into his Browser, of course).

heitml allows you to specify starting and inner pages using the Mode Parameter of the <session> Tag. When a User tries to directly access an inner page, an error message is produced, referring him to the proper starting page. You should also specify an Application Name in the Session Tag. This would prevent the rare possibility of a User confusing Session Files by typing URLs in his Browser and directly jumping among pages belonging to non-related Session Mode Applications. Declaring an Application Name as a parameter of the <session> Tag automatically causes heitml to check that both a Session File and page belong to the same Application.

Session Mode: Tutorial Demo

Now that we've covered some of the background concepts regarding Session Mode, we'll take a look at a few practical code samples that cover the major points required to set up a Session Mode Application on your own.

First, let's look at an abbreviated sample of the code contained within the seslogin.hei file. This file is part of the heitml Download Package and should be located in the installdir/htdocs/heitml2.1/tutor directory on your local hard disk (assuming that you specified "installdir" as the installation directory when you ran the heitml setup program).

Filename: seslogin.hei (abridged)
<HTML> <HEAD> <include name="NewLayout.hei"/> <title>Session Mode Example</title> </HEAD> <BODY> Enter your email address or "@" to login: <p> <FORM ACTION="sesstart.hei"> <INPUT name="email" size=40> <INPUT type="submit" name="submit"> <if !isempty(ff.s.inframe)> <INPUT name="s.inframe" type="hidden" value="t"> </if> </FORM> <p> <sa "homepage.hei> Back to the Home Page</sa> </BODY> </HTML>

You should notice a few old friends here by now: We've included the layout file we developed in the Modular Pages section and called the <BODY> Tag which we have redefined in the layout file.

Other than that, however, there is very little heitml-specific code to talk about. We've purposely kept this example simple, which is why we've used standard HTML Tags wherever possible. You should note, though, that we could just as easily have used some of the Tags we developed in the Creating FORMs section as a replacement for the HTML <input> Tag.

Notice also the conditional if Tag we've included to see whether or not the ff.s.inframe variable has been declared. You may remember that this was part of our discussion of the Outline Library in the section devoted to Modular Pages. The purpose of the line you see here is to determine whether the page is currently operating in FRAMEs Mode and, if so, to pass that variable along to the next page as part of the URL line.

Lastly, we used the <sa> Tag as a replacement for the HTML Anchor Tag, and created a link that allows the User to change his mind and go back to the Home Page (or page of your choice) should he decide that he doesn't want to logon and begin running your Session Mode Application after all.

This next example is where things really get started and, appropriately enough, we've called it sesstart.hei (which is also included as part of the heitml Download Package).

Filename: sesstart.hei (abridged)

<HTML> <HEAD> <include name="NewLayout.hei"/> <include name="ses.hei"/> <title>Session Mode Example</title> </HEAD> <BODY> // First verify the User Login. <if !isnull(ff.email) && !contains(ff.email,"@") // Accept Login if email contains "@" > <h1>Login failed<h1> The email address has to contain a @. <p><a href="seslogin.hei">back</a><p> <else> <session mode="create"> <if contains(default(ff.email,""),"@") ; // If we come from seslogin.hei, remember // the email address in a persistent way se.email=ff.email; se.textsize="+1"; se.textcolor="black"; /if> <h1>Login failed<h1> <FONT color=<? se.textcolor> size=<? se.textsize> > Welcome to session mode. You can now move to another <sa href="sesnext.hei"> page </sa>, or <sa href="sesparam.hei">change some parameters</sa> <p> <sa "tutor2.hei">Back</sa> to the examples page. </FONT> </session> </if> </BODY> </HTML>

In addition to our layout file, we must now also include the Session Library file ses.hei.

We must first check if we come from seslogin.hei to know that this must be the first time the User has come to this page. In that case we perform a simple check to see if an email address or an ampersand character "@" was entered.

If our test determines that the email field was left blank or does not contain the ampersand character, however, the code following the if statement is executed. In this case the User is presented with a message explaining what went wrong.

Otherwise, we start the session and initialize the textsize and textcolor variables to some arbitrary beginning value. This section of code in the above example is where the Session Mode finally begins. From this point onwards, everything on the page is contained within the beginning and ending <session> Tags.

Notice how we then use the HTML <FONT> Tag to set the color and size of the text that will appear on the page. Now you see why we initialized these variables as part of the conditional if statement above, since heitml would have otherwise detected an undeclared variable, thus causing the page to crash.

The rest of the page merely presents a series of clickable hot-links to the User, leading to any one of several other pages within the Session, depending on the User's preference.

Clicking on the "page" link simply brings the User to the sesnext.hei page, which shows whatever email address he entered, thus proving that the value of that variable had been preserved.

The sesparam.hei page allows the User to change the color and size of the text. This page contains a standard HTML FORM, except that Session Mode would detect and preserve the values of the se.name variables automatically and pass them onto the next page:

Filename: sesparam.hei

<HTML> <HEAD> <include name="ses.hei"/> <include name="NewLayout.hei"/> <TITLE>Session Mode Parameter Form</TITLE> </HEAD> <BODY> <h1>Session Mode Parameter Form</h1> <session start="seslogin.hei"> <let se.textcolor=default(ff.textcolor,se.textcolor,"black"); se.textsize=default(ff.textsize,se.textsize,"+0")> <font color=<? se.textcolor "P"> size=<? se.textsize "P">> <form action="sesparam.hei"> Text color : <input name="textcolor" size=10 value=<? se.textcolor "P">> <br> Text size : <input name="textsize" size=10 value=<? se.textsize "P">> <br> <sessionhidden/> <input type="submit"> </form> <p> You can now move to the <sa href="sesstart.hei"> starting page </sa> or to another <sa href="sesnext.hei"> page </sa>. </font> </session> </BODY> </HTML>

Notice that our program begins by calling the <session> Tag. As explained earlier, this is required for any page belonging to a Session Mode Application. The difference here is that, instead of using the "create" parameter, as we did in the seslogin.hei file, the sesparam.hei file only needs to identify the name of the Application to which is belongs (i.e. the name of the file where the Session began). Like in the Creating FORMs section, we pass and lookup the values of the form fields in the ff object in order to preserve them in se. In the remainder of the example, the HTML form and its fields are generated using the values stored in the session.

Session Mode: Tutorial Demo using Components

The example above is written in a very low-level style. By using heitml/RADpage Components like the sesform, fieldtext and formbutton Component, we not only achieve the benefits of using a structured/modular set of tools to create FORMs, but our workload is further reduced because we take advantage of Session Mode's variable-saving features. Here is a version of sesparam.hei using components:

Filename: sesparacom.hei

<HTML> <HEAD> <include name="ses.hei"/> <include name="sesform.hei"/> <include name="formfields.hei"/> <include name="copanel.hei"/> <include name="NewLayout.hei"/> <heitmldefs><![CDATA[ <defenv dfont fcolor fsize panel=gl._curpanel; inherit SimpleInlineComponent; ><\FONT color=<? panelfield()[fcolor] "Q"> size=<? panelfield()[fsize] "Q"> ><defbody><\/FONT>< /defenv> ]]></heitmldefs> <TITLE>Session Mode Parameter Form</TITLE> </HEAD> <BODY> <h1>Session Mode Parameter Form</h1> <session start="seslogin.hei"> <sesform oid="paraform"> <dfont fcolor="textcolor" fsize="textsize"> Text color : <fieldtext name="textcolor" size="10" value="black" /> <br/> Text size : <fieldtext name="textsize" size="10" value="+0" /> <br/> <formbutton name="submit" type="submit"></formbutton> </dfont> </sesform> <p> You can now move to the <sa href="sesstart.hei"> starting page </sa> or to another <sa href="sesnext.hei"> page </sa>.</p> </session> </BODY> </HTML>

There are many Field Components available, one for every type of Data Field you would ever use, including Check Boxes, Radio Buttons, and Select Boxes. You should read the documentation in the heitml Component Guide to become intimately familiar with them, as it is likely you will find them to be exceptional tools for FORMs building.

Summary

We began this section with a review of some of the concepts discussed in previous pages, and talked about some of the problems not yet addressed by the topics encountered along the way. We turned then to an introductory discussion of Session Mode, and focused on how Session Mode could solve these problems, at the same time saving Web Designers time and effort.

We showed a quick code sample of what a Web Page using Session Mode would look like, and then we discussed some of the underlying mechanisms employed by the Ses Library.

We then presented a tutorial walk-through of a complete Session Mode Application, showing code samples that demonstrated in a practical manner how Session Mode Applications are initiated, how some of the Inner Pages could work, and in particular, stopping to discuss a few Form and Field Components.

A deeper understanding of Session Mode can be obtained by reading the heitml Ses Library documentation, and by studying the code in the files provided as part of the heitml Download Package, located in the "Tutor" sub-directory.