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

