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

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

Added some optional attributes of the tag <webbox> in order to tell it
where to find the other parts of the webbox (css, js, php, db).

Example:
    <webbox id="view" css="{{CSS}}view.css" js="{{./}}view-1.js">

Since the attribute 'php' is missing, then its default value is
"{{./}}view.php" (where 'view' is the ID of the webbox).

If the value of the attribute 'css' ends with a slash (/), then it is
considered to be the path where the css file can be found and the name
of the file that is used is 'ID.css'. The same goes for the attributes
'js', 'php' and 'db' as well.

The attribute 'path' specifies where to find the parts of the webbox
by default. Its default value is "{{./}}" (the current directory).

The same attributes can be used in <webclass> as well.

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

The 'docbook' webbox is used just to display the cache (HTML) files
of a DocBookWiki application. It is useful for including a docbook
document in an application.

It can be included like this:
<include src="{{DOCBOOK_PATH}}docbook.html" />
where DOCBOOK_PATH is defined by the framework itself.
If you make a local copy of the webbox, then you have 
to use the right path. 

It has these state variables which can be initialized or changed
by the application that includes it:

docbook->cache_path  -- the path of the HTML files (usually the
                        directory 'contents/books/cache/' of the DocBookWiki
docbook->book_id     -- the id of the book
docbook->node_path   -- the path of the node to be displayed (default './')
docbook->lng         -- the language of the book (default 'en')
docbook->webnotes    -- show webnotes if it is 'true' (default 'false')

The JS function set_node(node_path) can be used by the application
to change the node that is currently displayed.

If the state var 'docbook->webnotes' is 'true', then webnotes
will be appended at the end of each section, but first the database
of the webnotes must be installed.

-------------------------------------------------------------------
The webbox 'webnotes' can be used to append comments or notes
to documentation pages or to other web pages. It can be included
in a template like this:
  <include src="{{WEBNOTES_PATH}}webnotes.html" />
where WEBNOTES_PATH is defined by the framework.

The application or the webbox that includes the webnotes component
should also give a value to its state variables, in order to modify
its appearance and behaviour. These state variables are:

* webnotes->page_id -- Only the notes with the given page_id will be
    selected from the database and displayed. Any new notes that are
    added will get automatically this page_id as well (which means that
    they will be appended at the end of this page). If page_id is an
    empty string (''), then webnotes are not displayed at all (are
    disabled). The default value of this variable is empty string.

* webnotes->unmoderated -- If this is 'true', then the new notes
    that are submitted are approved automatically, otherwise they
    will have to be reviewed and approved by an admin or moderator
    before being published in the page. The default value is 'true'.

* webnotes->notify -- If this is 'true', then a notification will be
    sent by e-mail whenever a new note is submitted. The default value
    is 'false'.

* webnotes->emails -- The email(s) (can be a comma separated list) to
    which the notification will be sent. The fedault value is empty.

* webnotes->approve -- If this is 'true', then the webnotes will be
    displayed in the moderation mode. In this mode it is possible to
    see all the notes of the page and to filter them by status or by
    the e-mail of the note author. It is also possible to change the
    status of a note (e.g. from 'queued' to 'approved'). By default it
    is false.

    The field 'status' of the webnotes can have the values 'edit',
    'queued', 'approved', 'declined' or 'archived'. When a new note is
    created and it is saved, its status is 'edit'. When it is
    submitted, its status becomes 'queued' (or 'approved' if there is
    no moderation).  In general, only the notes with the status
    'approved' are displayed (when 'webnotes->approve' is not
    'true'). In the approve mode, only the notes with status 'queued'
    are displayed by default, but the status filter can be
    changed. Then, the status of each note can be changed to
    'approved', 'declined', 'archived', and even back to 'queued'.

* webnotes->admin -- If this is 'true', then the webnotes will be
    displayed in the admin mode. In this mode it is also possible to
    delete a note (besides the moderation functionality). It is also
    possible to open the admin interface, where the notes of several
    pages can be managed at once. By default it is 'false'.

* webnotes->admin_pageid_filter -- This is used only when
    'webnotes->admin' is 'true'. It is an SQL select condition (used
    in WHERE), which filters the pages whose notes are going to be
    displayed in the admin interface of the notes. The default value
    is '1=1', which means select all the pages.

Being a lightweighted component, webnotes does not provide user
authentication of its own and decisions like who is going to be
moderator, who is going to administrate what, etc. Instead it relies
on the application to make this kind of decisions and to let it know
about them. The application that includes webnotes, tells it what
to do by setting propper values to the state variables above.

The webnotes are stored in a database table which is created with this
command:

CREATE TABLE webnotes (
  note_id int(10) unsigned NOT NULL auto_increment,
  page_id varchar(255) NOT NULL default '',
  email varchar(100) default '',
  ip varchar(100) default '',
  date_modified datetime default '0000-00-00 00:00:00',
  status varchar(100) default '',
  note_text text,
  PRIMARY KEY  (note_id)
) TYPE=MyISAM;

If the application that uses webnotes uses DB as well, then this table
can be created with a command like this:
--scr
bash$ mysql -h host -u username -p -D dbname \
            < web_app/boxes/webnotes/db/webnotes.sql
----

If the application does not use a database, then a new database for
keeping the webnotes must be created as well, like this:
--scr
bash$ echo "create database webnotes;" | mysql -h host -u username -p
bash$ mysql -h host -u username -p -D webnotes \
            < web_app/boxes/webnotes/db/webnotes.sql
----
Several applications can use the same database for keeping webnotes,
provided that they use different page_id-s for their pages. 

When the application itself does not use a database, then it should
provide to webnotes the neccessary parameters for creating a database
connection. These parameters are:

* webnotes->dbhost -- The MySQL server, default value 'localhost'.
* webnotes->dbuser -- The database user, default value 'root'.
* webnotes->dbpasswd -- The password of the user, default value ''.
* webnotes->dbname -- The name of the database, default value 'webnotes'.

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

* - The messages of the framework itself (errors, warnings, etc) now
    support i18n/l10n (translation). The messages displayed from JS
    code (alerts) support multiple languages as well.

The function TF_("...") is used in the PHP code of the framework
classes to get the translation of a string, like this: $var =
TF_("..."). It can also be used in the JS code and in the templates
(HTML code).

For the application components and templates the framework finds out
outomatically which translation file to use and where it is located,
depending on the location of the component its id, and some
conventions. However, the translations of the framework messages are
in a separate translation file. So, TF_("...")  is used instead of
T_("...") in order to distinguish that this is the translation of a
framework message.

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

* - function formWebObj::add_listbox_rs($rs_id, $arr_options)
  /**
   * From the items of the given array create a listbox recordset
   * (with the fields 'id' and 'label'), and insert it in the $webPage.
   * $arr_options can be an associated array, a simple array, or mixed.
   * In case of the associated array, the keys are used as id-s and 
   * the values are used as labels.
   */

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