The addressbook application

As you may have noticed when installing the sample Addressbook application, it consists of two custom wsql files. One is called search.wsql, and that is a simple html form. The other one is admin/index.wsql, and is also a simple form. All the rest of the functionality is achieved through the files edit.wsql, list.wsql and details.wsql, which are standard scripts that work closely together with some functions in addressbook.pm.

They make use of the files 'views' and 'forms', that are used to describe the application in a very simple way. List.wsql uses the 'views' file, edit.wsql and details.wsql use the 'forms' file. Both of these files have the same structure: they contain blocks of definitions, separated by a double newline (\n\n). The first line of each of these blocks contains just one word, and that is the identifier of the block.

For example, say we want to use the list.wsql script, the parameters given in the 'views' block with identifier 'people'. We would call the script like this:

http://addressbook.wesql.org/list.wsql?view=people

The 'view' parameter passed is the identifier of the block, the first line of it.

Many other parameters can be configured in the 'views' and 'forms' files. There is no documentation yet, but if you look at the code for the Addressbook application, and have a look at the edit.wsql, details.wsql and list.wsql files, you'll get the idea. Just experiment - and I will try to write some more documentation. Or if someone else would like to... please feel free!! My gratitude will be eternal ;-)

When submitting a form generated by the edit.wsql script, it is fed to the modify_journalled sub in the addressbook.pm file. This sub takes care of the the input in the database, consulting a file called 'permissions', which discribes what permissions a view has. The syntax of this file is trivial, here is a typical example:

user
table:users
modify:login,password,superuser
delete:no

As you can see the first line is the name of the view, the second one determines the table the view applies to. With the third line, one can say which columns in the table may be updated by this view. Changes to the other columns are silently ignored. With the last line, (journalled!) deleting of records can be (dis)allowed. A denied delete will result in an error message.

The journalled database

Together with these scripts, the Addressbook application also introduces the 'journalled' database-layout. Basically this means that records are never deleted from the database, they are only disabled by setting the 'status' field to zero.

Every table that wants to make use of the jUpdate, jAdd and jDelete subs (recommended!!!) needs to have the following four fields defined:

The MySQL definitions:

        id bigint(20) unsigned not null,
 
        uid bigint(20) unsigned not null,
		suid bigint(20) unsigned default '0' not NULL,
        epoch bigint unsigned not null,
        status tinyint default '1' NOT NULL,

The PostgreSQL definitions:

        id int8 not null,
 
        uid int8 not null,
	    suid int8 not null,
        epoch int8 not null,
        status boolean default '1' NOT NULL,

You will notice that in most tables in the Addressbook application, I have also defined a 'pkey' field, which is a simple auto-incrementing unique identifier. It has no use other than easy reference of records by humans, and for debugging.
The id field is not unique, but there should never be more than one record with a status = 1 and a certain id value.
The uid field contains the userid of the user that caused the record to change.
The suid field contains the userid of the superuser that caused the record to change. If the change was made by an ordinary user, the suid field will be zero. If the suid field is not zero, the uid field will still contain the userid of the record as it was before the superuser started changing it.
The epoch field contains the number of seconds that have elapsed since 1 January 1970, thus giving a very precise indication of when this record was created.

The downside of this approach is that the databases have four extra fields per table, and that they grow in size much more quickly. But the upside is that every change can be traced to when and by whom it was done.

Of course, the database could be 'cleaned' every now and then, removing all old records with status=0.

Finally, have a look at the online addressbook application