
Transitions
===========

    
What is a Transition
---------------------
A transition is the move of the application from one state to
another (usually from one page to another). A state of the 
application is composed of a certain template file and some
session variables (session variables are persistent variables
of the application whose lifetime may be as long as the time that
the application is active). A transition is usually triggered by
a client-side event in the browser, such as: clicking a link,
pressing a button, submiting a form, timeout of a javascript timer,
etc. 


How is Done a Transition
-------------------------
In the phpWebApp a transition is done by calling the function GoTo()
which is declared by the framework itself, e.g. GoTo('page1.html').
In this case, the GoTo() function sends a request to the web-server
for another page. This request is processed by the framework, which
loads the template 'page1.html' (in the folder TPL_PATH of the
application) processes it and sends it to the browser. 

If a path is specified for the template, e.g.
GoTo('folder1/page1.html'), then this path is found in the 
folder TPL_PATH. If the page that is to be loaded is the same as
the current page (e.g. we are in page 'page1.html' and we want to
load again the page 'page1.html'), then this syntax can be used:
GoTo('thisPage'); the framework remembers itself what is the current
page and loads it again. This syntax is handy in the case of generic
weboxes which may be included in several pages, and they don't know
in which page they will be included.

Usually, before making a transition you need to make some 
validations (e.g. when the user fills a form and submits it to the
application). These data validations can be done in the client-side
by using a javascript function. For example:
    <a href="javascript: on_link()"> Link </a>
    <input type="button" value="Button" onClick="on_button()">
    <form onSubmit="on_submit(); return false;">
The functions on_link(), on_button() and on_submit() usually do some
client-side validations and error checkings and then, if everything
is OK, they cause a transition by calling the function GoTo().


Sending PHP Variables to the Application
-----------------------------------------
Like usual links which can send variables to the server, like this:
    <a href="page1.php?var1=val1&amp;var2=val2"> Link </a>
a transition can send variables as well:
    <a href="javascript: GoTo('page1.html?var1=val1&amp;var2=val2')"> Link </a>
These variables will be declared as PHP global variables by the
framework and may be used in the PHP code of the application. However
the use of these global variables is discouraged, because there are
better ways to send variables to the application.


Sending an Event to the Application
------------------------------------
An important variable that is sent to the application almost in each
transition is the variable 'event'. This variable sends to the 
application a server-side event that should be handled by the 
application. The format of an event variable is like this:
    event=targetBox.eventName(arg1=val1;arg2=val2;arg3=val3)
When the framework gets the variable 'event', it builds an object
of class Event and forwards it to the appropriate WebBox for handling.

(For more details on events read the file: 'events.txt'.)


The Difference Between Transitions and Links
---------------------------------------------
Caution: Although the transitions seem quite similar to the HTML links,
they are actually very different. An HTML link requests a page from
a web-server, while a transition requests a page of the application
from the framework. So, all the pages of the application should 
refer to each-other only by using transitions, and to the external 
pages (pages outside the application) only by using links. If a page
of the application refers to another page of the application by a
link, this may break the consistency of the application. Such a 
mistake may happen if the page has an HTML form, because this form
usually submits to its action, by not using a transition. To overcome
this, we should declare the form like this:
    <form name="form1" onSubmit="return false;">    or
    <form name="form1" onSubmit="on_submit(); return false;">
