
1 - What is phpWebApp
----------------------
phpWebApp is an application framework which makes easy and simple
the task of building PHP web applications based on relational
databases. It separates the task of designing and changing the
layout of the application from the task of implementing the logic
of the application, by using XML templates that are an extension
of XHTML. It also simplifies the task of implementing the logic of
the application by offering an event based programming model.
In addition, phpWebApp tries to offer modularity and code reusability
to the community of webApp developers.


2 - Templates
--------------
These are normal XHTML files which have some additional tags and
some variables. These tags and variables are processed by the
framework and are replaced with XHTML code when the web page is rendered.
These templates allow the web page designer to work almost independently
from the database designer and the php programer that implements the
logic of the application.

For more details read the file: 'templates'.txt .


3 - Transitions
----------------
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, submitting a form, timeout of a javascript timer,
etc. 

For more details read the file: 'transitions.txt' .


4 - WebBox-es
--------------
A WebBox is a template which has also its own PHP code, which
handles its server-side logic. It is an almost self-contained
and independent template which can be easily included in other
pages or in other projects. Each page of a webApp should contain
at least a webox, unless it is very simple (doesn't have 
server-side logic). A webox can be composed of other weboxes.

For more details read the file: 'webox.txt' .


5 - Events
-----------
In a web application there are two kinds of events: client-side
and server-side events. Client-side events are events that happen
in the browser. Server-side events are events that are sent
to the application during a transition, which is done from a 
client-side event handler. The server-side events are usually sent
to a certain webox of the target page, which handles it. When we
refer to "events" we usually mean the server-side events, which are
more important in the framework. Thinking about a web application
in terms of sending events and event handling makes simpler the
construction of the application logic.

For more details read the file: 'events.txt' .


6 - Variables
--------------
Variables are used in templates to insert a dynamic string in it.
Its value is not known at the time that the template is designed,
it is given by the php part of the application or by the framework
(e.g. by getting it from the DB or by calculating it according to 
a certain logic). Their value is always a string, which replaces
the variable when the template is processed by the framework.
Template variables are denoted like this: {{#var_name}}. 

For more details read the file: 'variables.txt' .


7 - Session
------------
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 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.

For more details read the file: 'session.txt' .


8 - Database
-------------
The database component of the application is very important, because
most of the web applications are based on relational databases.
It allows an application to interact with a database, to get and
display data from it, to save, update and delete data in it, etc.
The framework tries to make this interaction as easy and as convenient
as possible for the application developers, without loosing the
flexibility. It also tries to ensure that the database is used in 
abstract way, so that it doesn't matter for the programer whether 
the database is MySQL, Oracle, etc.

For more details read the file: 'database.txt' .


9 - 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.

For more details read the file: 'new_app.txt' .


10 - Common WebBox-es and Tools
--------------------------------
Common weboxes are general weboxes that may be used in more than
one application or that are used commonly in web applications.
These weboxes are placed in the folder 'web_app/boxes' and are
general enough to be used any application.

Tools are utility programs, or applications, or plug-in pages that 
are used to help or to simplify or to automate the process of building
new web applications. The tools are placed in the folder 
'web_app/tools'.

For more details read the file: 'common_weboxes.txt' .


