
How to create a new application
================================

When you want to create a new application based on phpWebApp, 
the most fast and the most easy way is to copy one of the egzisting
applications (e.g. one of the sample applications of the tutorial)
and then to modify it according to the needs of the new application.
In order to modify it easily and correctly you should know about the
structure of the folders and files and how they can be modified.


The required folders and files
-------------------------------
Each application has a folder and 2 files that are required by the
framework, these are the folder 'config' and the files 'index.php'
and 'application.php'. The folder 'config' contains the files
'const.Paths.php' and 'const.Settings.php' which are also required.
There is also the folder 'event_handlers' which contains the required
files: 'on.firstTime.php', 'on.beforePage.php' and 'on.afterPage.php'.
The name of the folder 'config' cannot be changed, however you can
change the name of the folder 'event_handlers', if you don't like it.


The file 'application.php'
---------------------------
<?
$app_path = dirname(__FILE__);
$app_path = str_replace("\\", "/", $app_path);  //could be a Windows path
define("APP_PATH",      $app_path."/");

define("CONFIG_PATH",   APP_PATH."config/");
include CONFIG_PATH."const.Paths.php";

//include configuration constants
include CONFIG_PATH."const.Settings.php";
if (USES_DB)    include CONFIG_PATH."const.DB.php";

//include the WebApp framework
include WEBAPP_PATH."WebApp.php";
?>

If finds the current path and declares the APP_PATH, then includes
the constant paths and the configuration files, and finally it 
includes the framework.

It is the same and remains unchanged for almost all the applications. 
But if you need to add something, add it at the end. E.g. you can
include another php file at the end, and in this php file you can
declare another database connection, or can add some variables that
are commonly used in the templates of the application, or can check 
if this user can access this application or the requested page of the
application, etc.


The file 'index.php'
---------------------
<?
include "application.php";

if ($event->targetPage==UNDEFINED)
{
    //first time that the user enters in the application
    $fname = EVENTHANDLER_PATH."on.firstTime.php";
    if (file_exists($fname))
    {
        include $fname;
        on_firstTime();
    }
}

if ($event->target=="none")
{
    //call the free event
    WebApp::callFreeEvent($event);
}

//construct the target page of the event
$targetPage = $event->targetPage;
$tpl_file = TPL_PATH.$event->targetPage;
WebApp::constructHtmlPage($tpl_file);
?>

It includes the 'application.php' (which includes the framework),
then it handles the case that the user opens the application for
the first time (if the targetPage of the $event is undefined, it
is assumed that the application is opened for the first time), 
then it handles the event (if it is a free event) and constructs 
the requested target page.

Usually, this file doesn't need to be changed, as well. However,
if you know what you are doing, you can modify it.


The file 'config/const.Paths.php'
----------------------------------
<?
//constants of the paths in the application
define("APP_URL",           "/phpWebApp/app1/");
define("WEBAPP_PATH",       APP_PATH."../web_app/");
define("EVENTHANDLER_PATH", APP_PATH."event_handlers/");
define("TPL_PATH",          APP_PATH."templates/");
?>

Here are declared some constants that contain the paths of several 
folders in the application. The above 4 constants are all required
by the framework. The first one defines the URL of the application
(starting from the DocumentRoot of the web server) and it must be
modified for each new application. The second one defines the path 
of the framework. The second and the third ones define the paths 
of the event handlers and of the templates.

It is recomended that for almost each folder in the application you 
add here a constant that contains its path, and use this constant
in the application, instead of hardcoding its name. This provides for
more flexibility of the application, because if you decide later to
change the name of the folder, or to place it in another path, then
all you have to change is the definition of its constant, and the rest
of the application remains the same.

As a general rule, all the url paths end with "_URL", all the folder
paths end with "_PATH", and all the paths end with a "/". These are
just conventions, but it is better to follow them for being 
consistent throughout the application. 

There is also the function WebApp::to_url_path($folder_path), which
takes a folder path and returns it as an url location.

Below is another example of this file:
<?
//constants of the paths in the application
define("APP_URL",           "/vodafone/");
define("WEBAPP_PATH",       "/var/www/html/web_app/");

//mix paths
define("EVENTHANDLER_PATH", APP_PATH."event_handlers/");
define("GRAPHICS_URL",      APP_URL."graphics/");
define("INCLUDE_PATH",      APP_PATH."include_php/");

//template paths
define("TPL_PATH",          APP_PATH."templates/");

define("TOPMENU_PATH",      TPL_PATH."topMenu/");
define("LEFTSIDE_PATH",     TPL_PATH."leftSide/");
define("CONTENTMENU_PATH",  TPL_PATH."contentMenu_old/");
define("CONTENT_PATH",      TPL_PATH."content/");
define("DBCONTENT_PATH",    TPL_PATH."dbContent/");

define("EDIT_PATH",         TPL_PATH."edit/");
define("EDITMENUS_PATH",    EDIT_PATH."editMenus/");
define("EDITDOCS_PATH",     EDIT_PATH."editDocs/");

//module paths
define("MENU_PATH",         CONTENTMENU_PATH."buildMenus/");
define("SPONSOR_PATH",      APP_PATH."modules/sponsorat/");
define("SNIFFER_PATH",      APP_PATH."modules/clientsniffer/");
?>

The file 'config/const.Settings.php'
-------------------------------------
<?
//The constants defined here change the behaviour of the framework
//and the application. You can change the values of the constants
//according to the instructions given in comments, or add new
//constants that you use in your application

define("USES_DB", false);
    //if this constant is true, the framework will load the DB component
    //and will open a default connection with the db specified in the
    //file 'config/const.DB.php'

define("DEBUG_GOTO", false);
    //if this constant is true, the framework displays an alert
    //each time that the function GoTo() is called  (for debug)

define("DEBUG_SESSION", false);
    //if this constant is true, the framework outputs the session
    //variables as an HTML table (for debug)

define("DEBUG_RECORDSETS", false);
    //if this constant is true, the framework outputs all the 
    //recordsets of the page and their contents (for debug)

define("DEBUG_TEMPLATES", false);
    //if this constant is true, the framework outputs the tree
    //structure of the templates of the page (for debug)

define("EXECUTION_TIME_INFO", false);
    //if this constant is true, the framework outputs information
    //about the execution time of several processes (for debug)

//etc.
?>

It is self explanatory. Notice the debug constants that enable or
disable the debugging of various components of the application.
You can also add at the end other constants that are needed by your
application.


The file 'event_handlers/on.firstTime.php'
-------------------------------------------
<?
//this function is called the first time
//that the application is opened
function on_firstTime()
{
    //initialize the event
    global $targetPage, $event;
    $targetPage = "page1.html";
    $event->targetPage = $targetPage;
}
?>

It tells to the framework which page is to be opened first. The
global variables $targetPage and $event that are used by the 
framework, are modified. You can also add here code to sniff the
browser, to check whether the user is allowed to open the application,
etc.


The file 'event_handlers/on.beforePage.php'
-------------------------------------------
<?
//this function is called before any page is constructed
function on_beforePage()
{
  //measure the time of page generation
  global $webPage;
  $comment = "Time that spends the application for constructing the page";
  $webPage->timer->Start("WebApp", $comment);
}
?>

You can also add other code here, e.g. for keeping statistics.


The file 'event_handlers/on.afterPage.php'
-------------------------------------------
<?
//this function is called after any page is constructed
function on_afterPage()
{
  //output to browser the execution times
  global $webPage;
  $webPage->timer->Stop("WebApp");
  $webPage->timer->OutputInfo();
}
?>


Other files
------------
Some other files that are added optionally are:
- 'config/const.DB.php', which defines the constats for the DB link
- 'browser.php', which includes the preview tool


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

--------------------------------------------------------------------
* - config/const.Settings.php is divided into const.Options.php
    (some constants that can have optional values, depending on the
    application), and const.Debug.php (constants that enable or
    disable several debugging features of the framework).
