
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 and 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 in the page
------------------------
At the end of each page, something like this is appended 
automatically by the framework:

<script language="JavaScript" src="class.Session.js"></script>
<script language='JavaScript'>
    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.

In 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)

The session variables are always kept in session as string. If you
want to save an array, an object, etc. then you should use the PHP
functions serialise() and unserialise(), to convert them to and from
string format.


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


----- state vars (or session or persistent vars) added to webox ----
* - Now each webox can have its own state vars (or session vars, or
    persistent vars). Inside the class of the webox, its state vars
    can be accessed like this:
    $this->addSVar ($var_name, $var_value);
    $this->addSVars($associated_array);
    $this->setSVar ($var_name, $var_value);
    $this->setSVars($associated_array);
    $var_value = $this->getSVar($var_name);
    $assoc_arr = $this->getSVars();
    These variables can be accessed inside the webox in the usual way:
      {{var_name}} 
    and they are valid only in the scope of this webox (and shadow any
    other {{variables}} with the same name that are defined in the
    enclosing scopes.

    In case that some state variable of a webox needs to be used
    from the template of another webox, they can be accessed like this:
     {{boxID->var_name}}

    From the JS code as well, they can be accessed like this:
     session.setVar("boxID->var_name", var_value);   etc.

    Also, when you need to access the state var of another box from
    the PHP code of this webox, you can use this function:
    $var_value = WebApp::getSVar("otherBoxID->var_name");
    The function $var_value=WebApp::getSVar($var_name) can also 
    be used to get the session variables (instead of 
    $var_value=$session->Vars[$var_name]).
    Also the function:  WebApp::setSVar($var_name, $var_value)
    is available (instead of $session->Vars[$var_name] = $var_value;),
    and the function:  $wb = WebApp::getWBox("wbox_id");
    which returns a reference to the webox with the given id (this
    reference can be used to access the variables, state variable or
    functions of this webox, e.g. $wb->getQuery(); ).
    
    If the constant DEBUG_STATEVARS in the 'config/const.Settings.php'
    is set to true, then the framework outputs the state variables
    for each webox.

----------------- Session -------------------------------------
* - The special variable 'sessChange' is removed as obsolete. The
    programer can change the session on client side, before calling
    GoTo(), instead of changing session variables using 'sessChange'.

* - 'init.Session.php' is removed as obsolete. The session (state)
    variables can be initialized either in the 'init()' function
    of the weboxes or in the 'on.firstTime.php'.

* - Added session.rmVar(var_name) so that session vars can be
    removed from JS code as well. The names of the session functions
    in JS have been changed so that they are more consistent with the
    other function names in framework. Now they are:
    session.addVar("var_name", "var_value"); 
    session.rmVar("var_name");
    session.setVar("var_name", "var_value"); 
    session.getVar("var_name");

* - The names of the functions of the session object are:
    $session->addVar($var_name, $var_value);
    $session->rmVar($var_name);  //removes a variable from session
    $session->setVar($var_name, $var_value);  //sets a new value
    $session->getVar($var_name); //get the value of the var

    The names of the functions for the state vars of a webox are:
    $this->addSVar($var_name, $var_value);
    $this->addSVars($arr_vars);
    $this->setSVar($var_name, $var_value);
    $this->setSVars($arr_vars);
    $this->getSVar($var_value);
    $this->getSVars();

    The session and state vars can also be accessed using this functions:
    WebApp::addSVar($var_name, $var_value);
    WebApp::setSVar($var_name, $var_value);
    WebApp::getSVar($var_name);
    

* - DB Session Vars (or DB State Vars)
    Some of the state (session) variables now can be optionally stored
    in DB instead of storing them in the HTML page itself (using JS code).
    This increses the security of an application based on the framework,
    because the variables that are stored in the JS code potentially can
    be viewed and manipulated by malicious users. So, some of the
    session vars can be stored in DB and they are invisible on the client
    side, and the others (most of them) can be stored in the page, so that
    they can be accessed and used by the JS code of the application.

    To add a DB var, we use the same functions that are used to add a JS
    var, but add a third parameter that is not false, like this:

    $session->addVar($var_name, $var_value, true);
    $session->addVar($var_name, $var_value, "DB");
    $session->addVar($var_name, $var_value, "secure");  etc.

    $this->addSVar($var_name, $var_value,"DB");
    WebApp::addSVar($var_name, $var_value, "DB");

    To change or get the value of a DB variable we use the same "set"
    and "get" functions that we use for JS vars, without additional
    parameters (the framework finds itself whether this is a DB or a
    JS state variable). Usually a DB and a JS var have different names,
    but in case that they have the same name, DB vars have priority
    over JS vars (which means that "get" returns the value of the
    DB var and "set" sets the value to the DB var, instead of to the
    JS var).

    The array: '$session->dbVars' can be used to access the DB vars
    as well, like this:
    $session->dbVars[$var_name] = $var_value;
    $var_value = $session->dbVars[$var_name];
    but it is not neccessary and it is not recomended to use it
    (in fact, it is discouraged to use it).

    The function $this->getSVars() behaves a little bit different
    from the others. Without argument it returns a list of all
    the state vars of the webox, both DB vars and JS vars. With
    an argument "DB" it returns only the DB vars, and with argument
    "JS" it returns only the JS vars.

    For DB vars to work properly, there should be a DB connection
    with a database and the USES_DB constant in 'config/cont.Settings.php'
    must be true. Otherwise the DB vars are converted and stored as
    JS vars. Also, in database there must be the table session(id, vars),
    but if it does not egzist, it is created automatically by the framework
    (if the connection has permition to create tables).

---------------- session var values ----------------------------
* - The session JS vars can contain: ' (single quote), " (double
    quote), \n (new line character), \ (slash), \t (tab), etc.

    They cannot contain, however, \' (slash single quote),
    \" (slash double quote), \n (slash n).

--------------------------------------------------------------------
* - The function: session.isset(var_name) can be used to check
    whether a certain variable egzists in the session or not.

