Changes made to the application framework
that the application developer should know:
===========================================

-------- 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}}">

-------- 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().

-------- formWebObj ----------------------------------
* - formWebObj is a webobject that makes easy the handling of big
    forms (which have many inputs) and their data connection to the
    databaze. It is used like this: when you have a webbox that
    has a big form, in the PHP code of the webbox you include the
    class 'formWebObj', and then inherit this class, instead of
    inheriting 'WebObject' ('formWebObj' itself extends 'WebObject',
    so this is OK). E.g.:

          <WebBox ID="editProject">
            <form name="bigForm">
             . . . . . . . .
             <!--# many <input>s, <select>s, etc. here #-->
             . . . . . . . .
            </form>
          </WebBox>
          ----------------------------------------------
          <?
          include_once FORM_PATH."formWebObj.php";

          class editProject extends formWebObj
          {
             . . . . . . . . . .
          }
          ?>
          ----------------------------------------------
          <?
          class formWebObj extends WebObject
          {
             . . . . . . . . . . . 
          }
          ?>

    Then, in the JS code of the webbox you can use these JS functions
    which have been declared and included by the 'formWebObj':
    
        getEventArgs(form);
        /**
         * Returns all the data in the inputs of the given form
         * so that they can be sent as event args, e.g.
         * GoTo("thisPage?event=editProject.save(" + getEventArgs(form) + ")");
         */

        saveFormData(form);
        /** 
         * Transmit the data of the form, so that 
         * the changed values are not lost.
         * Must be called before GoTo().
         */
         This is useful when the page is refreshed for some reason,
         but you don't want to lose the values that are inputed in it. 
 
    There are also these two functions that are used internally by
    'formWebObj', but you can use them as well, if you need them:
        function getFormData(form)
        //returns all the data filled in the given form
        function setFormData(form, formData)
        //fills the form with the given data

------------- date WebObject -------------------------------
* - The webobject date can be used to select the date from a calendar.
    It can be used like this:
    First include the webclass that defines it:
        <Include SRC="{{DATE_PATH}}date.html" />
        (DATE_PATH is defined by the framework)
    Then declare as many date objects as needed:
        <WebObject Class="date" Name="information_date" />
        <WebObject Class="date" Name="contact_date" />
        etc.

    When an object of class date is declared, the framework replaces
    it with this html code:
        <input type="text" class="datebox" onFocus="blur()"
                name="information_date" value="{{information_date}}">
        <input type="image" ...(the calendar that selects the date)>
    So, it requires a default value {{information_date}}, which can 
    be declared in the PHP code of the webox that uses the date object.

    If you want to modify it, you can copy it to a path local to
    the application, modify it and use the modified copy, e.g.
        <Include SRC="{{./}}date/date.html" />

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

------------- listbox WebObject -------------------------------
* - The WebClass "listbox" is used to display a list of values with the
    <select> tag of HTML. These values are taken from a recordset (which
    can be retrieved from DB or can be supplied by PHP code. The recodset 
    associated with the listbox must have two fields: 'id' and 'label'.
    'label' is the field displayed, and 'id' is the value that is selected,
    saved in DB and retrieved from DB.

    Recordset example:
      <Recordset ID="listbox::country">
        <Query>
          SELECT country_id AS id, country_name AS label
          FROM countries
        </Query>
      </Recordset>

    Usage example:
      <WebObject Class="listbox" Name="country" rs="rs_id" width="---------------" />

    The attribute "rs" is optional. Its default value (if not specified) is
    {{obj_id}} (in the example above, it would be 'listbox::country').

    The attribute "width" is also optional; it is used as the last line of the
    list, in order to keep the width of the <select> to a certain size (which
    can also be used as a nothing selected (none of the above) value).

    This WebClass uses a <select> tag like this:
            <select name="country">  (name="{{obj_name}}")
              . . . . .
            </select>
    So, this should be kept in mind when accessing the selected value
    and when giving an initial value.
    If the 'listbox' is used inside a 'formWebObj' webbox, then it 
    takes care of it automatically.

--------------------------------------------------------------------
* - 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 = "---------------" />

--------------------------------------------------------------------
* - define("VAR_NOT_FOUND", "{var_name}");
    is added to 'config/const.Settings.php'

    This constant sets the format of the error message that is displayed
    when a {{variable}} is not found. 'var_name' is replaced by
    the actual variable name. Examples: "'var_name' is not defined",
    "", "undefined", etc. It cannot contain "{{var_name}}" inside.

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

--------------------------------------------------------------------
* - 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 type='text/javascript' 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.

---------------- 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. 
 
---------------- WebObject table -------------------------------------
* - WebObject 'table' is used to display the content of a table inside a page.
    It is used like this:

        <Include SRC="{{TABLE_PATH}}table.html" />

        <WebObject Class="table" Name="offices" 
                   table="offices"
                   fields="off_id,name" 
                   where="off_id < 10" />

    If attribute 'table' is the name of the table that will be displayed. 
    If it is not specified, its default value is {{obj_name}} (the value
    of attribute 'Name').

    The attribute 'fields' is the list of fields that will be displayed.
    It is optional and its default value is "*" (all fields).

    The attribute 'where' is the select condition for selecting the records.
    It is optional and its default value is "" (all the records).

---------------- WebObject editableTable ---------------------------
* - WebObject 'editableTable' is used to display and edit the content
    of a database table inside a page. It is used like this:

        <Include SRC="{{EDITABLE_PATH}}editableTable.html" />

        <WebObject Class="editableTable" Name="offices" 
                   table="offices"
                   fields="off_id,name" 
                   where="off_id < 10" />

    WebObject 'editableTable' is like 'table', but it also allows to 
    add new records to the table, to edit the existing records, to delete
    a record from the table, or to remove all the records of the table
    that are displayed.

---------------- NULL values -----------------------------------------
* - For a DB value that was NULL, the framework used to return UNDEFINED
    and, as a result, in the page was displayed {var_name}.
    Now, the constant NULL_VALUE is returned, which can be specified
    in the file 'config/const.Settings.php'. It can be "", "NULL", NULL, etc.

---------------- leftMenu webobject ----------------------------------
* - WebObject 'leftMenu' displays a menu, usually on the left side of the page.
    It is used like this:

        <Include SRC="{{LEFTMENU_PATH}}leftMenu.html" />

        <WebObject Class="leftMenu" Name="su"
            items="{{./}}su_menu_items.php" />

    The attribute 'items' is a PHP file that contains the items of the menu,
    like this:
        <?
        /** 
         * The $menu_items array contains the items of the leftMenu. 
         */
        $menu_items = array(
                "item1" => " Menu Item 1 ",
                "item2" => " Menu Item 2 ",
                "item3" => " Menu Item 3 ",
                "etc1"  => " . . . ",
                "etc2"  => " . . . "
                );
        ?>

    The item of the menu that is selected can be retrieved like this:
        $selected = WebApp::getSVar("leftMenu::su->selected_item");

    If you need to change the look of the leftMenu, then make a local
    copy and modify 'leftMenu.css'.
--------------------------------------------------------------------
* - 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).
--------------------------------------------------------------------
* - 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.
--------------------------------------------------------------------
* - 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>

--------------------------------------------------------------------
* - WebObject 'dbTable' is used to display and edit the content
    of a database table inside a page. It is used like this:

        <Include SRC="{{DBTABLE_PATH}}dbTable.html" />

        <WebObject Class="dbTable" Name="offices" 
                   table        = "offices"
                   fields       = "off_id,name" 
                   where        = "off_id < 10" 
                   editable     = "true"
                   selectable   = "true" />

    It is like 'editableTable' but has two more attributes.
    The attributes 'editable' and 'selectable' have default values of "false".
    In this case the 'dbTable' behaves just like 'table'. 

    When 'editable' has a value "true", then the table is editable, 
    i.e. its records can be added, deleted or modified. 

    When 'selectable' has a value "true", then it is possible to select 
    a record from the displayed ones. The fields of the selected record
    are declared as global template variables and can be used where they
    are needed.

    It makes obsolete WebObjects 'table' and 'editableTable', however
    'table' is still left in the framework because it is simpler than 
    'dbTable' and it can be easier to modify and customize to fit 
    the needs of a certain application.

--------------------------------------------------------------------
* - config/const.Debug.php: define("SHOW_ERROR_MESSAGES", true);

    If this constant is 'false' than the framework suppresses
    all the error and warning messages (that are generated by the
    framework). Usually it should be 'true' during the development and
    should be switched to 'false' when the application is deployed, 
    in order not to confuse the users of the application with error 
    messages that have no meaning for them.

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

-------------- datebox WebObject -----------------------------------
* - The webbox 'date' is renamed to 'datebox' and the attributes
    (parameters) 'value', 'format', 'onchange' are added to it.

        <Include SRC="{{DATEBOX_PATH}}datebox.html" />
        <WebObject Class="datebox" Name="information_date"
               value="{{info_date}}"
               format="YYYY-MM-DD"
               onchange="check_selected_date(this)" />

        <WebObject Class="datebox" Name="proposal_date" />
        <WebObject Class="datebox" Name="contact_date" />

        etc.

    The attribute 'value' is used to initialize the datebox
    with an initial value. If it is not given, then the
    default is {{{{obj_name}}}} (in the example above it would
    be {{information_date}}).

    The attribute 'format' is used to specify the format of the
    date. The reckognized formats are:
         YYYY-MM-DD (default)
         MM/DD/YYYY
         MM-DD-YYYY
         DD/MM/YYYY
         DD-MM-YYYY
    Actually this is only the format of the display, because the
    internal format is allways YYYY-MM-DD, the format used by
    the databases. E.g. if the above datebox webobject is declared
    inside a form with the name 'editDoc', then 
    "document.editDoc.information_date.value" returns the date in
    the internal format (in the format YYYY-MM-DD).

    The attribute 'onchange' (be carefull, all lowercase) is used
    to call any validation function at the time that the date is changed.
    If you pass 'this' as a argument to this function, then it
    refers to the display format. E.g. if 'date' is the parameter to
    which 'this' is passed, then "d = date.value;" gets the selected
    date in the display format (which is specified by the attribute
    'format'), and "date.value = d;" sets the date of the datebox
    ('d' should be in the format specified by 'format').

--------------------------------------------------------------------
* - WebObject 'listbox' can now take another attribute, 'onchange'
    (all lowercase), where the programer can call some JS code
    when the selected value is changed.

--------------------------------------------------------------------
* - 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.
--------------------------------------------------------------------
* - define("DISPLAY_CGI_VARS", false); (at 'config/const.Options.php')
    When this constant is true, then the CGI vars are displayed
    at the URL window of the browser. See also SHOW_EXTERNAL_LINK
    at const.Debug.php.

--------------------------------------------------------------------
* - The framework now gets the user variables (browser variables)
    from $_GET, $_POST and $_REQUEST, in order to comply with PHP 4.2.0
    The global object $request (of class Request, declared in 
    /session/class.Request.php) can be used to get the browser variables:
    sourcePage, targetPage, sessionVars, strEvents, phpVars.
 
--------------------------------------------------------------------
* - Changes in the structure of the files of the application;
    event_handler/on.firstTime.php is replaced by 'init.php', which
    is called (if it exists) the first time that the application is
    opened.
    define("FIRSTPAGE", "main.html"); in 'config/const.Settings.php'
    sets the first page of the application.

--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------
--------------------------------------------------------------------