Session
========

What is the session and what are session variables
---------------------------------------------------
Session is the time from the moment that a user starts a web 
application, until he ends it (closes the browser or jumps to
another page). 

Usually, in a web application the variables do not persist from 
one page to another, e.g. in a PHP web application even the 
global variables of PHP are lost when the next page is opened. 
Session variables, on the other hand, are persistent variables
of the application who may live as long as the time that the 
application is active.

The session can be thought as a wide scope, a scope that contains 
all the pages of the application from the time that the user 
opens the application until it closes it. Actually, the session 
variables correspond to the global variables of the non-web 
applications (e.g. VB applications). Since the session spans all the
pages, it can be used to keep variables that should not be lost from
one page to another, such as variables that keep the states of the 
application, states of the weboxes, etc.


The phpWebApp session
----------------------
The phpWebApp framework offers the programmers the possibility to
keep session variables. These variables are available and can be
used and manipulated both in server-side and client-side.

The session has been incepted so that the session variables are
kept inside the web-page itself. The session variables are passed
from PHP (server) to HTML (client) and from HTML to PHP continuously.
If you view the source of a page of an application, you will notice 
in the end the session variables. These variables are appended 
automatically to the end of each page of the application by the 
framework itself. Also, whenever you make a transition to another
page of the application, using the function GoTo(), all the session
variables are sent to the server as well, and this is taken care
by the function GoTo() itself. This is also one of the reasons why 
all the transitions in the application should be done using GoTo().
If you use a method other then GoTo() then all the session variables
will not be transmitted, will be lost, and this may break the 
consistency of the application.


Initialising the session
-------------------------
The session is a default component of the application, it is used
by the framework even if the application doesn't need and doesn't
use it. When an application is opened for the first time, a new
session is created and initialised. This session then is the same 
for all the following pages of the application, provided that all 
the transitions are done using GoTo(). The session variables can 
be initialized in 'event_handler/on.firstTime.php', in the function
on_firstTime() which is executed the first time that the user opens
the application.


The session in the page
------------------------
At the end of each page, something like this is appended 
automatically by the framework:

<script type="text/javascript" language="JavaScript" src="class.Session.js"></script>
<script type="text/javascript" language="JavaScript">
//<![CDATA[
  session = new Session();
  session.addVar('ID_S','IP: 192.168.1.2; DATE: 2001/11/01/ 00:24:33');
  session.addVar('var1','val1');
  session.addVar('var2','val2');
//]]>
</script>

The session class that will contain the session vars is included, 
a session object is declared, and the session vars are added to it.
The session variable 'ID_S' is declared by the session itself and is
unique for each session.


The session in JavaScript
-------------------------
If we want to read or change the session vars in the client side
(in javascript code), we can do this using the global object 'session'
and its functions:

session.addVar(var_name, var_value)             //ads a new variable
session.getVar(var_name)                                //get the value of a variable
session.setVar(var_name, var_value)     //set the value of a variable


The session in PHP
------------------
In PHP files the session vars are kept in the global variable $session,
which is an instance of the class 'class.Session.php'. This variable
is declared by the application framework and can be used directly
in the PHP code of the application.

At the moment that the variable is instantiated (at the constructor of
the Session class), it checks for the existence of the variable
$sessionVars, which comes from the client (browser) and brings the
session vars from the web page. If it exists, then the session is
filled with the variables that it contains. If it does not exist then
this means that we didn't have any session previously, so a new
session is created. The format of the $sessionVars is:
        var1=val1&var2=val2&var3=val3

Then it checks for the variable $phpVars and if it is declared
extracts from it the variables that it contains and declares them
as global variables of PHP so that they can be accessed from php
code of the application. The format of $phpVars is the same as the
format of $sessionVars.

Inside the php code of the application, the session vars can be
accessed like this: $session->Vars["var_name"]. To add a new variable
in session we can use $session->addVar($var_name,$var_value), and
to remove a variable from the session we can use
$session->rmVar($var_name)


Sample
------
To understand better how the session works, study carefully the
example in the directory 'session/sample'.