Session mode keeps data structures available between subsequent page accesses. All variables named se.name, and page.name are kept. Session variables can use any data type you like, including objects and arrays.
The variables named se.name are global while the variables page.name are local to a particular page (and window see below). Each page has an own set of page variables. Page and session variables remain accessible until they are explicitly freed or a certain expiry mechanism is selected. Page variables stay available even if other pages are displayed in between.
To use session mode you need to include the Ses Library
< include name="ses.hei" />
and put a <session> tag on the page.
So the simplest example for session mode is
This will show a counter, and whenever the user clicks on increment it will increment the counter by one. Each page that uses this code has its own counter.
How does it work ?
Session mode saves the content of se (the session object) and page after processing a page. When the same user requests a subsequent page, the session object and the page object are restored before processing the page. Currently heitml uses a file to store the session variables.
Once a user enters a session mode page for the first time, he gets a session card number assigned (currently made up by the date, time, and ip-number). After the processing of this page the session variables are written to a file (named as the card number). Now when the user requests the next page session variables are automatically read again.
To make this work the session card number must be passed from each page to the next. There are two ways to accomplish this, either by passing on the card number in the URL or by using cookies.
Cookie Session Mode
With cookie session mode the card number is stored inside the client browser using a cookie. This works fine and does not need any additional programming.
A technical disadvantage is that the cookie is automatically shared between all browser windows. This makes it impossible to run two independent sessions in two windows of the same browser.
URL Parameter Session Mode
An alternative to cookies is to pass the card number by adding it to the URL. This however requires, that each link shown on a page contains the card number as a parameter.
Another disadvantage is that if a user leaves your heitml pages and views some HTML pages from your server or somewhere else, the session information is lost. When the user returns he gets a new session.
To use the URL parameter session mode the card number must be added to each link. This means either the basic.hei library must be included or all anchor tags (<a ... >) must be replaced by an <sa ...> tag. For forms there is another way to add something to the URL. It is called hidden fields. You need to add a <sessionhidden> tag somewhere within each form, and session mode will work fine.
Starting Pages and Inner Pages
When using session mode many of your pages will require that certain session variables have been set already. Such a page must always be called from another session mode page. So we call it an inner page. In contrast pages where a session can start are called starting pages. By carefully setting your links, you can make sure inner pages are always called from another session mode page ..., except when a user types in an URL of such a page directly.
heitml allows you to specify which pages are starting pages and which are inner pages using the mode parameter of the <session> tag. When a user tries to directly access an inner page, he gets an error message, referring him to a starting page.
However the user could confuse session files by manually modifying URLs for several applications. This is why you can specify an application name in the session tag. Then heitml automatically makes sure that a session file and a page both belong to the same application.
Multi Window Session Mode
The following things are important when writing applications that work with multiple windows or frames of a single browser.
In case a frameset is (re)loaded the browser sends multiple concurrent requests to the server. In case of session mode heitml will not process these requests in parallel (which could cause data loss in the session file). Instead all requests from the same session are serialized. This happens automatically,
Page variables are not only local to specific page but also to a window. Suppose your application displays the same page in two windows or two frames. Then you certainly want both of them to behave naturally, without interfering with each other. This is only possible if the same page has different sets of page variables for each window it is working with.
Unfortunately heitml does not know in which window or frame the current page will be displayed. For example a page might contain an anchor tag with a target attribute. When clicked the browser displays the linked page into the window or frame specified by the target attribute. But unfortunately the browser tells the server the value of the target.
This is why a heitml multi window application must be programmed in a way, that gives heitml information about the target window of a page. The <session> tag has a parameter target, that must be set correctly to the name of the target window. In most cases it is easy because target can be set to a fixed window name. In dynamic cases, it is also possible to pass the target window name as an URL parameter.
Session Mode Tags
To use the following tags the file ses.hei needs to be included.
< session mode="std" start="/" appkey="" target="heitmlmain" > ... </session>
This is the basic session mode environment. It must be placed around the content of the page and only one session tag per page is allowed. The mode parameter can be "std" for an inner page and "create" or "createcookie" for a starting page. Should an inner page be called directly an error message will be displayed. It tells the user to start at the URL given as the start parameter of session. "createcookie" will start cookie session mode. Finally mode can be set to "accept". Accept will use an existing session but will not open an new one if there is no current session.
The appkey parameter passes an application name on to heitml which makes sure that the session variables belong to the same application. The target parameter must denote a browser window that the current page is loaded into. See multi window applications for details.
< sa href par=null urlpar="" > ... </sa>
The <sa> environment acts as a replacement for the < a > tag. It adds the card number to the URL called. par can be an object. The content of this object is added in the appropriate format to the current URL. The urlpar parameter is a string, that is also added to the URL.
If for some reason the <sa> tag is to restrictive, please use the <sessionurl> tag.
< sessionUrl />
creates URL parameters to be added to a URL for session mode. Normally you can just use <sa>, however, in some special cases <sessionurl> is more flexible. An example how to use <sessionurl> is <a href="mypage.hei?<sessionurl>">.
< sessionHidden />
adds the necessary parameters as hidden fields to a from.
In session mode, you just add < sessionCreate >
The body of the <sessioncreate> environment is executed only if the user just
entered session mode. This is a convenient way of initializing variables for
< sessionCreate > ... </sessionCreate>
The body of the <sessioncreate> environment is executed only if the user just entered session mode. This is a convenient way of initializing variables for session mode.