Chapter 3. User interaction

Table of Contents
Templates
Reading records
Editing a database
Sending email

Now, after having created a database definition file and a framework XML file, you are ready to build a user interface for your database application.

Templates

Almost everything in xmlbase is about templates. Templates usually are HTML files with embedded template commands that perform database queries and control what is output to the user's browser. Editing records is covered later in this chapter. For now, we will assume that we already have an existing database with some records to query.

You are not limited to HTML templates. xmlbase is well suited to produce any kind of text format such as simple plain text documents, interchange formats like comma-separated (.csv) files which can be read by a number of popular spreadsheet and database applications, simple PostScript files or even XML files intended for further processing. As xmlbase doesn't impose any arbitary restrictions on the contents of template files, even binary formats are possible; however, binary formats tend to be a little trickier in generation than text formats.

Executing templates

Template files must be located somewhere in the public space below your web server root. To execute a template with xmlbase, simply append its local address to the URL of your copy of xmlbase:

http://www.myserver.com/cgi-bin/xmlbase.pl/mydirectory/mytemplate.htt

HTML templates are customarily given the file name extension .htt. If you have access to your server's configuration, you are free to encapsulate /cgi-bin/xmlbase.pl or even the whole local part of the address in a server alias.

Passing parameters to a template

xmlbase accepts input data in any combination of parameters specified in the query string (hard-coded or by using the CGI method GET) or posted using the CGI method POST. Both encoding types application/x-www-form-urlencoded (the CGI default if no encoding is specified) and multipart/form-data (which is better suited for transferring large amounts of binary data as with file upload fields) are supported.

In addition, xmlbase provides a means to specify parameter defaults in the template file using so-called header lines. The default values are used if the parameters (or form fields) in question are not expressly specified on execution of the template; if they are, the default values are ignored. Header lines are located at the very top of the template file and are separated from the rest of the file by a single empty line. Both the header lines and the separator line are removed from the output.

Each header line starts with a parameter name, followed by a colon, followed by one or more spaces or tabs and then followed by the desired default value for the parameter. The parameter name must meet several syntactical requirements when used in a header line: It must consist of one or more parts separated by dashes, with each part starting with an upper-case letter optionally being followed by lower-case letters. (After being read, all upper-case letters are transformed into lower-case letters, and all dashes are replaced by underscores.)

The following example defines the default values user=guest, id=create and content_type=text/plain before going on with the template:

User: guest
Id: create
Content-Type: text/plain

<html>
<head>
<title>Customer database</title>

Actually, the content_type parameter has a special meaning: Its content is directly fed into the HTTP header Content-Type that is returned to the user's browser as the result of executing the template. pragma and cache_control have similar built-in magic.

Parameters are passed through to the template code in the param hash. For instance, to access the contents of the user parameter in a template command, simply refer to param.user. (For detailed information on how to use variable references see Referring to data fields.)

User authentication

Everybody requesting access to a database must be authenticated first. The initial authentication happens by passing a user name and a password to xmlbase using the parameters user and password; if the given user name/password combination exists in the users and permissions section of the database definition file of the database to which access is requested, the IP address of the machine requesting access is associated with the user name and access is granted according to the permissions specified for this user.

For all subsequent requests by this user from the same IP address, specifying the user name is sufficient until the session times out or the user is logged out. By default, a session times out half an hour after the last access. You can change this timeout by specifying a number of seconds in the timeout parameter on initial authentication. To expressly end a user session, the user name must be specified in the logout parameter passed to xmlbase.