
A non-exhaustive list of things that are to be done
====================================================

-------------------------------------------------------------
* - Periodic Task:
    Update the documentation with the new changes.
-------------------------------------------------------------

* - Automatic Documentation
 -----------------------
    Find a way for keeping the documentation of the framework
    up to date automatically. There are some programs that
    parse all the PHP classes and build the documentation 
    automatically in HTML format, pdf format, ps format, etc.
    + phpDocumentor (http://phpdocu.sourceforge.net/)
      is installed and works.
    + Change all the comments to be conform the rules
      required by phpDocumenter.
    + Write a converter and templates that use phpWebApp.
    + Improve the converter and templates to display as
      well the model of the framework and the model of the
      applications, e.g. the tree of inheritance of the
      classes can be a graphical UML diagram, probably a
      graphical statechart diagram of the webboxes can be
      generated as well, packages can be represented in
      UML notation, etc.
    + Can phpDocumenter be improved to document JS code as
      well? If phpDocumenter cannot document JS code etc.
      probably doxygen (http://www.stack.nl/~dimitri/doxygen/manual.html)
      or any other tool can be considered.
    + What about DB code, HTML templates, web_app
      tags etc.? The final goal is to transform phpDocumenter
      into phpWebApp_Documenter, which can be used to 
      document the phpWebApp itself and any application
      based on it.
-------------------------------------------------------------
* - Find a better way for keeping the tasks, changes and bugs.
-------------------------------------------------------------
* - See whether an emacs mode can be created, that can help
    when working with the framework.
  - See whether a plug-in tool can be developed for Quanta
    that helps when working with phpWebApp.
-------------------------------------------------------------
* - Parse and process the templates using a DOM XML parser.
-------------------------------------------------------------
* - Implement Template Merge/Separator Tool
    Write a tool that merges all the templates of a page
    in a single html page, but by adding some comments which
    would allow to do the reverse process (separating the 
    templates as they were originally). This tool may be useful
    if we want to process the templates (e.g. convert them to
    XHTML automatically) using an advanced HTML editor (like
    Adobe GoLive, Dream Waver, etc.) and then separate them
    again in the structure that they were before.
-------------------------------------------------------------
* - Build a tool for the web (graphical) designer so that he
    can preview the templates. (The "browse.php" does this).
        
    Also, the tool will display a tree of all the templates in
    the application to the designer, from which he will select
    the template to preview.

        - Use a config file for each template, which will contain 
          the variables that are needed to display the template
          appropriately.
        - Use code-colorizer for displayingcodes of different types.
        - Upgrade the code.
        - Update the documentation.

    + Make WebBox-es to expand, collapse and to be editable. The
      same for <Include>s as well.
-------------------------------------------------------------
 DB component
==============

  - Write implementations on interface 'Connection'
    for databases other then MySQL, like this:

        class OracleCnn extends Connection {}
        class ProgreSQLCnn extends Connection {}
        class SQLServerCnn extends Connection {}
        class ODBCCnn extends Connection {}
        etc.

    where Connection is an interface, or an abstract class,
    or a general class, and the other classes contain the 
    code that is specific for each database.
    The application will use only one of these classes.

  - If $rs is a Recordset, then 
        $rs->fld_name
    should be used to get the field "fld_name" of the 
    current record, instead of:
        $rs->Field("fld_name")

  - Implement class TableRS.
    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. For example:

        //open the recordset
        $fld_list = "field1, field2, field3"; //optional, default "*"
        $condition = "... AND ... OR ...";    //SQL WHERE condition, optional
        $rs = new TableRS("tbl_name", $fld_list, $condition);

        //make some changes to the recordset
        $rs->MoveNext();
        $rs->rmRec();  //remove the second record
        $rs->find("field1='$value'");
        do
          {
            $rs->setFld("field2", $value2);
          }
        while ($rs->find_next());
        $rs->MoveLast();
        $rec = array("field1"=>$val1, "field2"=>$val2, "field3"=>$val3);
        $rs->addRec($rec);

        //save in the DB table all the changes made to the recordset
        $rs->save();

-------------------------------------------------------------
* - Add the tag connection that specifies a new connection

        <Connection ID="cnnID" type="MySQL">
          <Server>192.168.1.114</Server>
          <Port>1234</Port>
          <Username>db_user</Username>
          <Password>passwd</Password>
          <Database>db_name</Database>
        </Connection>

    Then it can be used optionally to the tag <Recordset>
    or <dbCommand>, like this:

        <Recordset ID="rsID" conn="cnnID">
          <Query></Query>
        </Recordset
 
-------------------------------------------------------------
* - The <Recordset> and <dbCommand> tags can contain inside
    only the <Query> element. Make them reckognize the <If>
    tag as well. In this case the same recordset can have
    different queries, depending on the conditions of the
    <If> tags. E.g. in the DT project, the same recordset
    can have another query for the superuser and another
    query for a usual user.

  - PagedRS requires a count query to get the number of 
    records. It transforms the <Query> in order to
    get from it a count query, but this doesn't work for
    all the types of queries. It would be better to have
    an optional <CountQuery> element inside the <Recordset>
    element. So, if the <CountQuery> element is present,
    then this query is used, otherwise the PagedRS tries
    to guess a count query by transforming the <Query>.

  - <Recordset>s and <dbCommand>s are kept by the framework
    in $webPage->rs_collection and they have an ID which is
    global to the application. Probably it would be better
    that each WebBox (or WebClass) keeps its own collection
    of recordsets. In this case that would be accessed like
    this:
        $rs = $this->openRS("rs_name");
        $this->execDBCmd("cmd_name");
        $rs = $this->getRS("rs_name);
        $this->setRS($rs);

        $rs = WebApp::openRS("class_id->rs_name");
        WebApp::execDBCmd("class_id->cmd_name");
        $rs = WebApp::getRS("class_id->rs_name");
        WebApp::setRS("class_id", $rs);
-------------------------------------------------------------

* WebClass & WebObject
  --------------------
  - Add this functionality to the framework: any webobject can
    handle an event sent to another webobject, if it defines the
    event handler "on_className_eventName()" (usually the event 
    handlers are named like this: "on_eventName()"). 
    Here 'eventName' is the name of the event, and 'className' is 
    the class of the webobject that receives or sends the event 
    (whichever is more appropriate).
    This may make obsolete the "event_target='any'", which was used
    to allow a webbox to handle the events of another webbox.
 
  - The state var 'objID->initialized' is used to see whether a webobj
    is initialized or not, and it has a value 'true' or 'false'.
    Instead of it we can keep a state var that is more useful, e.g.
    'objID->class_path' which keeps the path of the PHP code of the
    webclass. This path can help to run the event handler for the
    $event before the parsing starts at all. This also allows to run 
    the event handler of a webobj that is not parsed at all (at present,
    the framework runs the event handler of a webobj just before 
    parsing it, and it cannot run it if the webobj is not parsed).
    We can also call 'objID->class_path' with another name and keep in
    it other usefull info about the webobj and its state, e.g ??.

  - For accessing the state vars of a webobj we use this syntax:
        $s_var = $this->getSVar("varName");
    Probably it would be more convenient to use this syntax:
        $s_var = $this->varName;
    or  $s_var = $this->s_varName; 
           (to emphasize the difference
            between state vars and any other usual (non-persistent)
            vars that the webobj might have)
    However, 
        $this->s_varName = "new_var_value";
    cannot be better (in functionality) than 
        $this->setSVar("varName", "new_var_value");
    because the value changed in the first one will be available
    after $this->onParse(), and the second one changes it everywhere
    immediately.

  - It may be useful that the webobjects also have functions like:
        $this->constructor();
        $this->destructor();
    which are called by the framework after the object is created
    and before it is destroyed. The destructor can be called
    just before the session vars are saved, so that it has the
    possibility to remove its state vars from the session by
    calling WebObject::destroy(), which is the oposite of
    WebObject::init(). When WebObject::destroy() is called, it
    removes all the state vars from the session, so that next
    time that this webObj is parsed, it will be initialized
    again ($this->init() will be called again).

    + Probably it is better to rename:
         $this->init()  to  $this->initState()
      and
         WebObject::destroy()  to  WebObject::destroyState()

  - Would it be better if we can access the templates and recordsets
    of the $webPage like this: ?
        $webPage->"tpl_$tpl_id";
        $webPage->"tpl_$wb_id";
        $webPage->"rs_$rs_id";
    and then:
        $webPage->"tpl_$wb_id"->$sub_wb_id;
        $webPage->"tpl_$tpl_id"->$sub_wb_id->$sub_sub_wb_id;
        $webPage->"tpl_$tpl_id"->$sub_wb_id->$sub_sub_wb_id->parent;
        $webPage->"rs_$rs_id"->MoveNext();
        $webPage->"rs_$rs_id"->fld_name;

  * At project 'documentation', webclasses tabs1, tabs2, tabs3 have
    identical PHP and JS code, but change only on CSS and HTML files.
    It would be better to have only 1 webclass, 'tabs', which can have
    different styles (add a parameter 'style' to this webclass):
        <WebObject Class="tabs" Name="myTabs"
                items="{{./}}myTabs_items.php"
                style="geytabs" />

    Also, it would be useful to be able to override an aspect of a
    webclass, at the time that the webobject is declared, e.g.:
        <WebObject Class="tabs" Name="myTabs"
                js_file="{{./}}myTabs.js"
                html_file="{{./}}myTabs.html"
                css_file="{{./}}myTabs.css" />
    The above webobject declaration overrides the default client side 
    behaviour (JS code), the default layout (HTML) and the default
    stylesheet (CSS) of the WebClass 'tabs'. This overriding feature
    should be supported by the framework for each webobject, not just
    for the webclass 'tabs'.
 
-------------------------------------------------------------
* - Add page caching support to the framework. Before processing
    the templates, the framework should check whether the
    requested page is already in the cache (the cache folder is
    specified by the constant CACHE_PATH in 'const.Paths.php').
    Each component (WebBox or WebObject) should be cached 
    separately because this reduces the size of the cache. If there
    is a component that cannot be cached, because it interacts
    with the DB, then the framework will parse and render it.
-------------------------------------------------------------
* Terminology
  -----------
 Change the names of some vars, classes, functions etc. so they
 describe better the function, class, etc.

  - {{obj_name}}    to {{Name}}
    {{class_name}}  to {{Class}}

  - {{CurrentRecNr}}  to {{RecNr}}
    {{CurrentRowNr}}  to {{RowNr}}
    etc.

  - Rename path constants from 'XYZ_PATH' to 'XYZ/'. (!?)

  - Change from: 
        GoTo("page1.html?event=webclass::webobj.event_name(arg1;arg2;arg3)")
    to: GoTo("page1.html//webclass::webobj->event_name(arg1,arg2,arg3)")
  
  - Probably it is better to change the denotation of
    a slot (a variable) from {{var_name}} to a more
    familiar denotation like: ${var_name}, or something
    like this. (Why is it better? Does it have any 
    disadvantages?) 

  - Find another name (terminology) for free events.  E.g. they may be
    called 'independent events' (because the handler is not a member
    function on any webbox), 'global events' (because they are handled
    globally and before any page construction has started), 'switches'
    or 'conditionals' (because they usually switch on some conditions
    and decide which page to construct), etc.

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

* Improve the structure of the framework and the application so that
  two independent applications can comunicate easily with each
  other. E.g. one of the applications can include the other (like a
  webbox that can include another webbox) and both of them work
  independently in the same window. One of the applications can check
  or modify the state of the other application, can modify its
  behaviour, can use its resources (images, templates, etc.), etc.

  Such a capability would be useful for applications like "browse", 
  which browses and displays the templates of another application
  (actually 'browse' is implemented like a tool, or a webbox that
  is not totally independent from the application that it browses).
  It will also be useful for the WADE (Web Application Development 
  Environment), so that it is an independent application and 
  doesn't have to be mixed with the framework or with the application
  that is being built.

  In order to achieve this:
  * Path constants, Option constants, Debug constants etc 
    should not be constants, because the value of the constants 
    cannot be changed.
  * An event should tell (either implicitly or explicitly) to
    which application belongs, so that the framework can dispatch
    it to the correct webbox.
  * etc.

