[phpWebApp-commits] CVS: documentation/templates/user_manual/manual_pages database.txt,1.1.1.1,1.2 events.txt,1.1.1.1,1.2 intro.txt,1.1.1.1,1.2 new_app.txt,1.1.1.1,1.2 session.txt,1.1.1.1,1.2 templates.txt,1.1.1.1,1.2 variables.txt,1.1.1.1,1.2 webox.txt,1.1.1.1,1.2

[Dashamir H. <das...@us...>]

Update of /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages
In directory sc8-pr-cvs1:/tmp/cvs-serv11335/templates/user_manual/manual_pages

Modified Files:
	database.txt events.txt intro.txt new_app.txt session.txt 
	templates.txt variables.txt webox.txt 
Log Message:


Index: database.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/database.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** database.txt	21 Feb 2003 08:18:29 -0000	1.1.1.1
--- database.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 177,178 ****
--- 177,337 ----
  
  	WebApp::execQuery($query_str, $cnn1);
+ 
+ 
+ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ 
+ ---------------- Recordsets ------------------------------------
+ * - Satic Recordsets:  <Recordset rs="rsID" static="true">
+     These are recordsets that are opened only once during the
+     page construction. Usually the recordsets are opened as
+     many times as they are needed (i.e. their query is executed
+     and the results retrieved from DB). This has the advantage 
+     that the query can be different each time that the recordset
+     is opened (depending on the {{variables}} that it contains),
+     and this provides for more flexibility and dynamicity.
+ 
+     However, in some cases, the same query is executed all the
+     times that the recordset is opened, e.g. when this recordset
+     is used to fill a listbox and this listbox can be 20 times
+     in the page. In this case it is more efficent that the
+     recordset is opened only once and it is used in the 20 cases.
+ 
+ * - The syntax of tag Recordset now is:
+ 	<Recordset ID="rsID" type="rsType">
+     where 'rsType' can be one of the values: "StaticRS", "DynamicRS",
+     "EditableRS", "PagedRS", "TableRS". The attibute type can be
+     omitted; in this case the default value is "StaticRS".
+ 
+     A 'static' recordset is the recordset described above, a RS that
+     cannot be opened more than once per page. A 'dynamic' RS is a
+     recordset that evaluates its query (replaces its {{variables}}),
+     executes it and refreshes the content each time that its
+     method Open() is called. Notice that before a recordset was
+     'dynamic' by default and 'static' only if specified, but now a
+     RS is 'static' by default (if no type is given). This is
+     because 'static' recordsets are more common in web applications
+     and 'dynamic' recordsets are useful only in special cases, 
+     e.g. when we have two nested recordsets (associated with two
+     nested <Repeat>s) and the inner RS uses a {{variable}} provided
+     by the outer RS.
+ 
+     A 'PagedRS' is a recordset that divides  the results of the
+     query into pages of certain size, and retrives from DB only
+     one page of them. It requires the attribute 'recs_per_page',
+     which specifies the size of the page. It is used to display
+     big recordsets, when they cannot fit in a single HTML page.
+ 
+     An 'EditableRS' is a RS that can be modified from the PHP code.
+     The programer can retrive the results of a query from DB and
+     then modify them, or start with an empty RS and fill it 
+     programatically. It makes possible to use templates for results
+     that don't come from DB (e.g. when you want to display a folder
+     listing and you get the files and folders using some PHP functions).
+ 
+ 	This feature can be used in the "folderListing" webbox, for
+ 	example. Instead of generating all the html code of the 
+ 	folder listing programatically, a <Repeat> template, associated
+ 	with a <Recordset> could be used, and this recordset could be
+ 	filled from an array or from php code (instead of being filled
+ 	from database).
+ 	The benefit of this aproach (vs. generatin all the html code
+ 	in php) would be that we are able to change the layout of the
+ 	'folderListing' webbox more easily, because instead of changing
+ 	the php code, we change only a template.
+ 
+     The functions of EditableRS are:
+ 	$rs->apply($fun_name)
+ 		//applies the function $fun_name on each record
+ 		//of the recordset; $fun_name is a global function
+ 		//that takes as parameter a reference to an associated 
+ 		//array (a reference to a record), like this:
+ 		// function fun_to_be_applied(&$rec)
+ 	$rs->setFld($fld_name, $fld_value)
+ 		//sets a new value to the given field (in the current record)
+ 	$rs->setFlds($arr_flds)
+ 		//changes some fields of the current recordset
+ 	$rs->addRecs($arr_recs)
+ 	$rs->addRec($rec)
+ 		//adds a new record after the current record,
+ 		//the new record becomes current
+ 	$rs->insRecs($arr_recs)
+ 	$rs->insRec($rec)
+ 		//insert a new record before the current record,
+ 		//the new record becomes the current record
+ 	$rs->rmRec()  //removes the current record
+ 	$rs->rmRecs($nr)
+ 		//removes $nr recs from the recordset, 
+ 		//starting with the current record;
+ 		//if $nr is not given or exeeds the EOF, 
+ 		//then removes all the recs up to the EOF
+ 	$rs->slice($offset, $length)
+ 		//returns a new recordset that contains a slice of this recordset;
+ 		//see the documentation of array_slice of PHP
+ 	$rs->match($condition, $pos)
+ 		//returns true if the query at the given position
+ 		//matches the $condition (usually used by the functions
+ 		//find() and filter() above); if no position is given
+ 		//matches the current record;
+ 		//currently the $condition supports only one field
+ 	$rs->filter($condition)
+ 		//returns a new recordset with the recs that match the
+ 		//given condition, $condition is like the WHERE condition
+ 		//of a query, but it matches using regexp-s, e.g.
+ 		//(username=/^d.*/ AND (firstname=/[^a]+/ OR NOT lastname='Hoxha'))
+ 		//(currently it supports only one field, no AND, OR, (, ) etc.)
+ 	$rs->find($condition)
+ 		//finds the subset of the recordset that matches the
+ 		//condition and positions the pointer to the first
+ 		//record found; $condition is like the condition in filter();
+ 		//if called without parameter, if finds the next one,
+ 		//and so on up to EOF;
+ 	$rs->search($condition)
+ 		//used by find(), finds all the records that match 
+ 		//the condition and stores their indeces in
+ 		//the array $this->found_positions
+ 	$rs->find_next()
+ 		//used by find(), returns the next found record
+ 		//or UNDEFINED if there are no more records
+ 	$rs->getColumn($fld_name)
+ 		//returns an array with the values of the specified field
+ 	$rs->getColumns($fld_names)
+ 		//$fld_names is a comma separated list of field names;
+ 		//returns a new recordset that contains only the specified
+ 		//columns
+ 
+     A "TableRS" is an editable RS which is associated with a table in
+     a DB. After editing this RS, the programer can save the changes
+     back to DB. (This is not implemented yet.)
+ 
+ * - WebApp::execQuery($query) now returns an EditableRS.
+ 
+ * - Function: WebApp::openTable($table, $condition) added.
+ 	//opens the given table and returns the records that
+ 	//satisfy the given $condition; returns a TableRS
+ 
+ ----------------------------------------------------------------
+ * - The constant DB_TYPE in 'config/const.Settings.php' specifies
+     the type of the DB that the application is using, like this:
+ 
+     define("DB_TYPE", "MySQL");
+ 	    //this constant defines the type of DB that the application uses
+ 	    //it can be: "MySQL", "Oracle", "ODBC", "ProgreSQL", etc.
+ 	    //(except "MySQL", the others are not implemented yet)
+ 
+ * WebApp::openRS($rs_id, $params =array())
+   WebApp::execDBCmd($cmd_id, $params =array())
+   
+   These functions now take an optional array of parameters, which
+   are replaced in the query as {{tpl_vars}}.
+ --------------------------------------------------------------------
+ * - PagedRS can also handle the queries which have GROUP BY.
+ 
+     Along to the state variable 'rs_id->current_page' which keeps
+     the current page of the PagedRS, there is the state variable
+     'rs_id->recount' which is set to true by the application when
+     the records need to to be recounted (e.g. when a new record is
+     added in DB, or when a record is deleted).
+ 
+     Before, the number of the records in a PagedRS was counted only
+     when current_page was 1, but this is not very convenient.
+ --------------------------------------------------------------------

Index: events.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/events.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** events.txt	21 Feb 2003 08:18:29 -0000	1.1.1.1
--- events.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 185,186 ****
--- 185,246 ----
  become obsolete or not supported.
  
+ 
+ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ 
+ ------------------ event handling -------------------------------
+ * - The class of a webox can declare an event handler function,
+     with the name "on_eventName". If such a function exists,
+     then this function is called to handle the event, otherwise
+     the function eventHandler($event) is called, as before. This
+     is useful both for backward compatibility and for flexibility:
+     the programer chooses how to handle the events, either with a
+     separate event handler for each event, or with a common event
+     handler for all the events.
+ -------- transmitVars() --------------------------
+ * - function transmitVar(var_name, var_value)
+     This function sends the var_name (which has the given var_value)
+     to the server side as a PHP global variable. It can also be used
+     in the template as a tpl variable: {{var_name}}, since all PHP
+     global variables can be used as tpl variables. It should be used
+     carefully, because any tpl variable with the same name will 
+     override its value.
+     It must be called before GoTo().
+ 
+   - function transmitVars(var_list)
+     Similar to transmitVar() but can transmit more than one variable.
+     The format of var_list is: var1=val1&var=val2&var3=val3.
+     Must be called before GoTo().
+ 
+ ---------------- SendEvent() ----------------------------------------
+ * - js function: SendEvent(obj_id, event_name, event_args)
+     
+     Sends an event to the server-side (PHP) code.
+     obj_id  -- the object to which the event is sent
+     event_name -- the name of the event
+     event_args -- the arguments of the event, optional
+ 
+     It is defined in 'func.GoTo.js' which is included automatically
+     by the framework in each page. This function uses GoTo() to
+     send an event to a webobject (or webbox). Its target is always
+     'thisPage' (so, it cannot switch to another page of the application,
+     like GoTo()) and it cannot send global PHP variables (like GoTo()).
+     So, GoTo() is more general, but SendEvent() should be more common
+     and more frequently used. 
+  
+ --------------------------------------------------------------------
+ * - The GoTo() function accepts only a string of the form
+     GoTo("target.html?event=obj_id.event_name(event_args)");
+     Before it was possible to send some global PHP vars, by appending
+     them after the event like this: &var1=val1&var2=val2 etc.
+     This was deprecated and actually it is almost never used. In the
+     rare cases when it is needed to send a global variable to PHP,
+     the functions transmitVar() and transmitVars() can be used.
+     The values of the event arguments could not contain '&' before,
+     but now they can.
+ 
+     They cannot contain ';', because it is used to separate event args
+     from each-other, however, the JS function encode_arg_value(str),
+     which is defined by the framework, can be used to replace them
+     with '#semicolumn#', in cases that they need to contain ';'.
+     The decoding (replacing '#semicolumn#' by ';') is done by the
+     framework itself.

Index: intro.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/intro.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** intro.txt	21 Feb 2003 08:18:29 -0000	1.1.1.1
--- intro.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 1,18 ****
  
- 0 - Table of contents
- ----------------------
-  0 - Table of contents
-  1 - What is phpWebApp
-  2 - Templates
-  3 - Transitions
-  4 - WebBox-es
-  5 - Events
-  6 - Variables
-  7 - Session
-  8 - Database
-  9 - How to create a new application
- 10 - Common WebBox-es and Tools
- 
- 
  1 - What is phpWebApp
  ----------------------
--- 1,3 ----
***************
*** 156,157 ****
--- 141,144 ----
  
  For more details read the file: 'common_weboxes.txt' .
+ 
+ 

Index: new_app.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/new_app.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** new_app.txt	21 Feb 2003 08:18:29 -0000	1.1.1.1
--- new_app.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 25,29 ****
  The file 'application.php'
  ---------------------------
! <?php
  $app_path = dirname(__FILE__);
  $app_path = str_replace("\\", "/", $app_path);	//could be a Windows path
--- 25,29 ----
  The file 'application.php'
  ---------------------------
! <?
  $app_path = dirname(__FILE__);
  $app_path = str_replace("\\", "/", $app_path);	//could be a Windows path
***************
*** 56,60 ****
  The file 'index.php'
  ---------------------
! <?php
  include "application.php";
  
--- 56,60 ----
  The file 'index.php'
  ---------------------
! <?
  include "application.php";
  
***************
*** 95,99 ****
  The file 'config/const.Paths.php'
  ----------------------------------
! <?php
  //constants of the paths in the application
  define("APP_URL",			"/phpWebApp/app1/");
--- 95,99 ----
  The file 'config/const.Paths.php'
  ----------------------------------
! <?
  //constants of the paths in the application
  define("APP_URL",			"/phpWebApp/app1/");
***************
*** 128,132 ****
  
  Below is another example of this file:
! <?php
  //constants of the paths in the application
  define("APP_URL",			"/vodafone/");
--- 128,132 ----
  
  Below is another example of this file:
! <?
  //constants of the paths in the application
  define("APP_URL",			"/vodafone/");
***************
*** 159,163 ****
  The file 'config/const.Settings.php'
  -------------------------------------
! <?php
  //The constants defined here change the behaviour of the framework
  //and the application. You can change the values of the constants
--- 159,163 ----
  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
***************
*** 201,205 ****
  The file 'event_handlers/on.firstTime.php'
  -------------------------------------------
! <?php
  //this function is called the first time
  //that the application is opened
--- 201,205 ----
  The file 'event_handlers/on.firstTime.php'
  -------------------------------------------
! <?
  //this function is called the first time
  //that the application is opened
***************
*** 222,226 ****
  The file 'event_handlers/on.beforePage.php'
  -------------------------------------------
! <?php
  //this function is called before any page is constructed
  function on_beforePage()
--- 222,226 ----
  The file 'event_handlers/on.beforePage.php'
  -------------------------------------------
! <?
  //this function is called before any page is constructed
  function on_beforePage()
***************
*** 238,242 ****
  The file 'event_handlers/on.afterPage.php'
  -------------------------------------------
! <?php
  //this function is called after any page is constructed
  function on_afterPage()
--- 238,242 ----
  The file 'event_handlers/on.afterPage.php'
  -------------------------------------------
! <?
  //this function is called after any page is constructed
  function on_afterPage()
***************
*** 256,257 ****
--- 256,265 ----
  - '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).

Index: session.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/session.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** session.txt	21 Feb 2003 08:18:29 -0000	1.1.1.1
--- session.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 105,106 ****
--- 105,249 ----
  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.
+ 

Index: templates.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/templates.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** templates.txt	21 Feb 2003 08:18:32 -0000	1.1.1.1
--- templates.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 274,275 ****
--- 274,365 ----
  	For more details see the file: 'webox.txt' .
  #-->
+ 
+ 
+ * - Variables can also be used in the 'rs' attribute of a <Repeat> tag,
+     e.g.   <Repeat rs="{{rs_id}}"> . . . </Repeat> .
+     This allows a repeat block to use different queries in different
+     cases (according to the logic of the program). These variables
+     are evaluated at the parse time, at the time that the repeat
+     element is parsed. So, if you give value to this variable inside
+     the function onRender(), it will not get it; instead it should be
+     given value in the function onParse(), or it should be a state 
+     variable or global variable.
+ 
+ * - The syntax of tag Recordset now is:
+ 	<Recordset ID="rsID" type="rsType">
+     where 'rsType' can be one of the values: "StaticRS", "DynamicRS",
+     "EditableRS", "PagedRS", "TableRS". The attibute type can be
+     omitted; in this case the default value is "StaticRS".
+ 
+     A 'static' recordset is the recordset described above, a RS that
+     cannot be opened more than once per page. A 'dynamic' RS is a
+     recordset that evaluates its query (replaces its {{variables}}),
+     executes it and refreshes the content each time that its
+     method Open() is called. Notice that before a recordset was
+     'dynamic' by default and 'static' only if specified, but now a
+     RS is 'static' by default (if no type is given). This is
+     because 'static' recordsets are more common in web applications
+     and 'dynamic' recordsets are useful only in special cases, 
+     e.g. when we have two nested recordsets (associated with two
+     nested <Repeat>s) and the inner RS uses a {{variable}} provided
+     by the outer RS.
+ 
+     A 'PagedRS' is a recordset that divides  the results of the
+     query into pages of certain size, and retrives from DB only
+     one page of them. It requires the attribute 'recs_per_page',
+     which specifies the size of the page. It is used to display
+     big recordsets, when they cannot fit in a single HTML page.
+ 
+     An 'EditableRS' is a RS that can be modified from the PHP code.
+     The programer can retrive the results of a query from DB and
+     then modify them, or start with an empty RS and fill it 
+     programatically. It makes possible to use templates for results
+     that don't come from DB (e.g. when you want to display a folder
+     listing and you get the files and folders using some PHP functions).
+ 
+ 	This feature can be used in the "folderListing" webbox, for
+ 	example. Instead of generating all the html code of the 
+ 	folder listing programatically, a <Repeat> template, associated
+ 	with a <Recordset> could be used, and this recordset could be
+ 	filled from an array or from php code (instead of being filled
+ 	from database).
+ 	The benefit of this aproach (vs. generatin all the html code
+ 	in php) would be that we are able to change the layout of the
+ 	'folderListing' webbox more easily, because instead of changing
+ 	the php code, we change only a template.
+ 
+ --------------------------------------------------------------
+ * - <Repeat rs="{{tpl_var}}">
+     The attribute rs of the <Repeat> tag can contain variables
+     (so that the same repeat can use different recordsets, 
+     according to the logic of the program). These variables
+     are evaluated now in render time (before they were evaluated
+     in parse time) because this is more convenient.
+ 
+ --------------------------------------------------------------------
+ * - The tag <WebObject> can be written in several lines (for making it
+     more readable, in case that it has many attributes) and the parser
+     can handle it. E.g.
+         <WebObject Class = "listbox" Name  = "country" 
+                    rs    = "rs_id" 
+                    width = "---------------" />
+ 
+ --------------------------------------------------------------------
+ * - The recordsets declared by the <Recordset> tag were by default
+     of type "StaticRS". Now the default type is "EditableRS",
+     because this is more useful (and anyway EditableRS extends StaticRS).
+     It can be declared explicitly as "StaticRS" only when the programer 
+     has strong reasons to disallow the modification of this recordset
+     from the PHP code.
+ 
+ TODO: Add a separate section for Recordsets and the <Repeat> tag.
+ 
+ * - The expression of the <Var> tag can now be declared in several 
+     lines, like this:
+ 	<Var name="class">
+ 	  ( 
+ 	    "{{item}}"=="{{{{obj_id}}->selected_item}}" ? 
+ 		    "leftMenu-item-selected" 
+ 		    :"leftMenu-item"
+ 	  )
+ 	</Var>

Index: variables.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/variables.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** variables.txt	21 Feb 2003 08:18:32 -0000	1.1.1.1
--- variables.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 135,136 ****
--- 135,148 ----
  	(e.g. {{#var1}} is replaced by "var1").
  
+ 
+ 
+ * - Variables can be nested, like this: {{checked_{{id}}}}
+     First the innermost variable is replaced, then the outer variable.
+     If {{id}} has the value "2" and {{checked_2}} has the value "true",
+     then the whole variable above will be replaced by "true";
+ 
+     If the value of a variable contains another variable inside,
+     it will be replaced as well. E.g, if the variable {{nr}} has the 
+     value "5" and the variable {{msg}} has the value
+     "This is message number {{nr}}.", then using {{msg}} inside a
+     template will produce the string: "This is message number 5."

Index: webox.txt
===================================================================
RCS file: /cvsroot/phpwebapp/documentation/templates/user_manual/manual_pages/webox.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** webox.txt	21 Feb 2003 08:18:32 -0000	1.1.1.1
--- webox.txt	23 Feb 2003 14:29:07 -0000	1.2
***************
*** 135,136 ****
--- 135,372 ----
  It is better that a WebBox and all the files related to it be 
  placed in a folder with the same name as the boxID. 
+ 
+ 
+ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ 
+ 
+ -------- the PHP code of a webox -----------------------
+ * - The PHP code of a webox: <WebBox ID="boxID" 
+     is placed in the file "boxID.php" which is in the
+     same folder as the template containing the webox.
+     
+     The code of the webox now is organized inside a class:
+     "class boxID extends IWebBox {...}"
+     which extends the interface (or the abstract class) IWebBox.
+     This makes the PHP code of the application more object-oriented
+     and better organized.
+     
+     The class "boxID" can override the functions:
+ 	eventHandler($event), onParse() and onRender()
+     of IWebBox, or can define other functions that can be
+     used inside these functions. These functions replace 
+     the old functions: boxID_eventHandler($event), boxID_onParse()
+     and boxID_onRender()
+ 
+ 
+ ---------- the function init() ----------------------------------
+ * - The class of the webox can also define the function init(),
+     which is like the functions eventHandler(), onParse() and
+     onRender(), and overrides the abstract function with the same
+     name of the class IWebBox. This function is called only when
+     the webox is loaded for the first time (only once in a session
+     of the application). 
+ 
+     This function is the right place for initializing the state 
+     vars of the webox with default values. Previously, this was 
+     done in the onParse() with a statement like this:
+ 	 if (!isset($session->Vars["state_var"]))
+ 	 {
+ 		$session->Vars["state_var"] = "initial_value";
+ 	 }
+     Now it should be done in the init() function, like this:
+ 	 $this->addSVar("state_var", "initial_value");
+ 
+ 
+ ----- 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.
+ 
+ * - The callback function onLoad() is renamed to onParse(). As before,
+     it is called just before the webbox is parsed. 
+ 
+ -----------------------------------------------------------------
+ * - The framework supports WebClasses and WebObjects.
+ 
+ 	<WebClass ID="className" Path="path/to/className.php">
+ 	        <Parameter name="param1" default="default value" />
+ 	        <Parameter name="param2" />
+ 	    <!--# . . . . . . . . . . . . . . . . #-->
+ 	    <!--# the template of the web class   #-->
+ 	    <!--# . . . . . . . . . . . . . . . . #-->
+ 	</WebClass>
+ 
+ 	<WebObject Class="className" name="wObj1" param1="value1" param2="value2" />
+ 	<WebObject Class="className" name="wObj2" param2="value2" />
+ 	<WebObject Class="className" name="wObj3" param1="{{nr}}+1" param2="red" />
+ 
+     The element <WebClass> defines a web class, but it by itself
+     does not produce any HTML output in the rendered page. The element
+     <WebObject> declares an object of the class and the content (the template)
+     of the <WebClass> is used to render this object.
+ 
+     The 'Path' attribute of the <WebClass> declares the path of the 
+     file that defines the PHP code of the WebClass. It is optional, 
+     and if it is not given, then the current folder (the folder of the
+     template that contains the <WebClass> definition) is searched for
+     the file "className.php".
+ 
+     The <Parameter> elements declare the names and optionally the default
+     values of the parameters of the webobjects. (The current implementation
+     requires that they come immediately after the <WebClass> line and have
+     no empty lines or other lines between them, otherwise they will not be
+     parsed correctly.) These parameters can be used inside the template of
+     the webclass like template variables, e.g. {{param1}}. If a parameter
+     doesn't get a value in the <WebObject> declaration, then its default
+     value is used (if it doesn;t have a default value, then it is handled
+     like an undefined variable). When a <WebObject> is rendered, the value 
+     of the parameters is evaluated as a mixed expression (a PHP expression
+     that contains {{template vars}}).
+ 
+     When several objects of the same class are declared, the template of the
+     webclass is repeated for each of them. The webclass designer should
+     take this into account when building the webclass. E.g. if there is
+     such an input in the webclass template:
+         <input type="text" name="staff">
+     There will be several such inputs in the HTML code, and its value
+     cannot be accessed like this: document.form.staff.value
+ 
+     ToDo: The framework declares some variables like: {{className}}
+     {{objName}}, {{objID}} (which usually is {{className}}::{{objName}}),
+     {{objCount}} (counts the objects of the same class, starting from 1),
+     etc. These vars can be used inside the template of the webclass,
+     if the webclass designer needs them, e.g.:
+         <input type="text" name="staff_{{objCount}}">
+ 
+     The PHP code 
+     -------------
+     The file "className.php", if it egzists, contains this class definition:
+ 	<?
+ 	class className extends WebObject
+ 	{
+ 	  . . . . .
+ 	}	
+ 	?>
+     Where 'WebObject' is a class defined by the framework that supplies
+     some useful functionality for all webclasses. 
+     This functionality is:
+         1 - The callback functions that are called by the framework at 
+ 	    certain moments during the time that the webobject is processesed.
+ 	    These callback functions are:
+ 		+ init()
+ 		+ on_eventName($event_args)
+ 		+ eventHandler($event)
+ 		+ onParse()
+ 		+ onRender()
+ 
+ 	2 - The ability to keep persistent variables that define the
+ 	    state of the object. These state variables can be used 
+ 	    inside the "className" like this:
+ 		+ $this->addSVar($var_name, $var_value);   
+ 		+ $this->addSVar($var_name, $var_value, "DB");  
+ 		+ $this->setSVar($var_name, $var_value);
+ 		+ $this->setSVars($var_name, $var_value);
+ 		+ $var_value = $this->getSVar($var_name); 
+ 		+ $arr_values = $this->getSVars($var_name);
+ 		+ etc.
+ 	    Outside the scope of the WebClass, these state variables can 
+ 	    be accessed like this: 
+ 	        + WebApp::setSVar("className::objName->var_name", "var_value")
+ 		+ $var_value = WebApp::getSVar("className::objName->var_name");
+ 		+ {{className::objName->var_name}} (in templates)
+ 		+ session.setVar("className::objName->var_name", "var_value")
+ 		+ etc.
+ 
+ 
+     WebBox-es
+     ---------
+     The <WebBox>-es are handled by the framework as a special case of 
+     <WebClass>-es and <WebObject>-s. When the framework parses:
+         <WebBox ID="boxID">
+ 	  . . . . .
+ 	</WebBox>
+     it interprets it as:
+         <WebClass ID="boxID">
+ 	  . . . . .
+ 	</WebClass>
+ 	<WebObject Class="boxID" />
+     and the ID of the created object, instead of being "className::objName"
+     is just "boxID", so it is handled the same as before 
+     (e.g. $var_value = WebApp::getSVar("boxID->var_name"), etc. )
+     Thus, when upgrading an egzisting application, the only change that
+     needs to be done is to replace:
+         class boxID extends IWebBox
+     with
+         class boxID extends WebObject
+ 
+ -------- afterParse() ----------------------------
+ * - WebObject::afterParse()
+     is like WebObject::onParse(), only that it is called after
+     the WebObject is parsed.
+ 
+ -------- webobject vars --------------------------
+ * - The framework declares for each webobject these variables: 
+ 	{{obj_id}}	-- the object id ({{class_name}}::{{obj_name}})
+ 	{{class_name}}	-- the name of the class
+ 	{{obj_name}}	-- the name of the object
+ 	{{obj_count}}	-- counts the objects of the same class, 
+ 				starting from 1
+     These vars can be used inside the template of the webclass,
+     if the webclass designer needs them, e.g.:
+         <input type="text" name="staff_{{obj_count}}">
+ 
+ --------------------------------------------------------------------
+ * - The tag <WebObject> can be written in several lines (for making it
+     more readable, in case that it has many attributes) and the parser
+     can handle it. E.g.
+         <WebObject Class = "listbox" Name  = "country" 
+                    rs    = "rs_id" 
+                    width = "---------------" />
+ 
+ --------------------------------------------------------------------
+ * - The JS code of a <WebBox> is included automatically by the 
+     framework at the <head> of the page. The framework looks for
+     the file 'box_id.js' (or 'class_id.js', in case of a <WebClass>)
+     in the same folder with the <WebBox>. If it exists there, then
+     the framework includes a line like this in the <head> of the page:
+ 	<script language='javascript' src='path/to/box_id.js'></script>
+     
+     Similarly, for the CSS code, the framework includes a line like
+     this: <link type='stylesheet' src='path/to/box_id.css' ....>
+     in the <head> of the page.
+