DBT - DataBase Template CGI
http://hostname/path/DBT[.cgi]/path_to_template_file?query_parameters
http://hostname/path/DBT[.cgi]/path_to_template_file
<!--#config
[ TemplateName=``name'' ]
[ DBfile=``file path'' ]
[ DBfileDir=``directory path'' ]
[ DBfields=``field_name:field_type [field_name:field_type]`` ]
[ DBdelimiter=``character'' ]
[ DBallow=``[ delete | insert | select | update ]'' ]
[ AuthUserList=``username1 [ username2 ...]`` ]
[ AuthGroupName=``group1 [ group2 ...]`` ]
[ AuthGroupFile=``file path'' ]
[ ErrorTmpl=``file path'' ]
-->
<!--#include file=``file path''-->
<!--#include cgi=``cgi executable path''-->
<!--#include template=``file path''-->
<!--#echo var=``environment variable''-->
<!--#echo form=``form parameter name''-->
<!--#echo field=``field name''-->
<!--#exec cgi=``cgi executable path''-->
<!--#mktag tag=``a_href | input | img | select`` [ name=''value`` ...]-->
<!--#size file=``file path-->
<!--#flastmod file=``file path''-->
DBT allows elaborate database applications to be built by writing HTML containing a variation on NCSA-style SSI (Server Side Include) tags. Elaborate psuedo-relational database applications are facilitated through the application of nested templates, and a predictable precedence of SSI tag substitutions.
The databases are stored in flat text files, managed by the ``Sprite.pm'' package by Shishir Gundavaram.
Templates are complete or partial HTML files with an added config block and substitution (SSI) tags. Templates are intended to be nested, so only the overall or outermost template needs to have the main <HEAD> and <BODY> HTML tags.
Config blocks are deleted from the template file once processed and are not visible in the source code delivered to the web browser.
It is recommended that template files be given the extension ``.httml'', for HyperText Template Markup Language. However, this is only necessary if the processing of templates is added as an Action in the http server configuration (see ``Apache Configuration'' in the Notes section below).
The two types of supported HTML tags are the config block and substitution tags. Each one appears as an HTML comment to most browsers and servers, though some of them are identical to standard SSI tags, and would yield the same results if used in that context.
A config block describes a template's relationship to a database.
<!--#config
A config block begins with the config block ID tag. It is followed by a number of configuration parameters. The configuration parameters are in the form of name-value pairs, as in normal HTML tags. The values must be quoted with double quotes (``). The pairs may be separated by white space or newlines.
TemplateName="short name of template"
This is the name used to direct CGI query parameters to a particular template. It should be unique within a particular template hierarchy. Template names may contain any combination of alphanumeric characters (plus the underscore). This parameter is required, but defaults to the filename stripped of illegal characters.
DBfile="full or relative path name to a database file"
This is the database file handled by the template. Any relative file paths are local to the directory containing the template file. If this template has no associated database file, then this parameter may be omitted.
DBfileDir="full or relative path to attached-file directory"
This is a path name to a directory which DBT process owner can freely read from and write to. Any relative file paths are local to the directory containing the template file.
This directory is used for the FILE field type to store longer DBT field content. This parameter required if the FILE field type is used (see DBfields, below).
DBfields="field_name:field_type [field_name:field_type]"
A list of field-name field-type pairs, joined by colons, and separated by whitespace or newlines. Field names must match those in the database file exactly (including case), and must appear in the same order. Field names must be at least two characters in length, and may only contain letters, digits, and the underscore. Field types may be any of the following:
KEY
A database should include at least one key field, and it is recommended that it be the first column in the database. The operations of update and delete will fail when executed on databases without key fields.
A key field cannot be modified once a record is created. It must be unique to that record in the table. Numeric key field values are assigned sequentially if not provided at the time of record creation (insert commands).
FILE
File field types store a file name in the database table. The submitted data is stored into and retrieved from files stored in the directory indicated in the DBfileDir configuration parameter. The files are named by concatenating with separating periods the field name and the value of the first (left most) key field in the record.
Queries specifying searches of the contents of FILE fields will be ignored.
TEXT
Text is the default field type. It may contain any ASCII value excluding a newline (0Ah), the value of the DBdelimiter parameter (09h by default), or a backslash (\). There is no maximum length for a text field value, but some operating systems have a 255 character limit on line lengths, and excessively long lines in the database table will degrade search performance.
DBdelimiter="database field separator character"
The character or string that separates fields within each record (line) of a database table. Defaults to a tab (ASCII 09h) if omitted. Very strange behavior will occur if left blank.
DBallow="[ delete | insert | select | update ]"
A white space delimited list of operations permitted on the template. Select enables a query operation, insert enables adding a new database record, delete enables deleting a database record, and update enables modification of an existing database record.
If omitted, all operations are permitted. If included but left blank, no operations are permitted.
AuthUserList="username1 [ username2 ...]"
A whitespace delimited list of user names, as returned by the web server's REMOTE_USER environment variable, that are permitted to view the template.
This parameter only has an effect if the directory containing the top-level template is protected by your web server's authentication feature.
AuthGroupName="group1 [ group2 ...]"
A whitespace delimited list of group names, as found in an NCSA or Apache
style AuthGroupFile.
This parameter only has an effect if the directory containing the top-level
template is protected by your web server's authentication feature, and if the following AuthGroupFile parameter is also present.
AuthGroupFile="full or relative path to the web server's AuthGroupFile"
The path to the effective AuthGroupFile used by the web server to authenticate access to the top-level template.
To be used with the AuthGroupName parameter described above. The specified file is searched for lines
containing one of the AuthGroupName(s). Any user names found associated with the group names are compared
against the REMOTE_USER environment variable. The template is not shown if the REMOTE_USER is not found.
ErrorTmpl="full or relative path to error template"
The full file path to an alternate template to be displayed if fatal errors occur in the processing of the present template. Any relative file paths are local to the directory containing the template file. If this parameter is omitted or left blank, a plain text error message will be returned.
Warning: It is possible to create circular references, which could have unpredictable and dangerous results.
-->
A config block ends with a standard HTML end-of-comment string.
A substitution tag is modeled on the NSCA/Apache Server Side Include (SSI) tag syntax. They may be used anywhere within a template, even within enclosing HTML tags. They are listed in order of replacement.
<!--#include file="full or relative path name to included text or HTML file"-->
If the file can be opened and read, the tag is replaced by the file's entire contents. Any substitution tags present in the file will not be processed in the current template, but may be processed in a higher template in the nesting hierarchy. Any relative file paths are local to the directory containing the template file.
<!--#include cgi="full or relative path name to CGI executable"-->
If the external cgi executable can be executed, the tag is replaced by the output of the executable. Any substitution tags present in the results will not be processed. Any relative file paths in this call are local to the directory containing the template file.
If the executable returns a Content-type of ``text/html'', the output is included in the results unmodified. If the Content-type is anything else, the output is enclosed in <PRE> tags.
<!--#include template="full or relative path name to template"-->
If the template addressed by the file path can be processed, it is substituted for the tag. Otherwise an error result is returned. Any relative file paths are local to the directory containing the template file.
If the included template references database fields, and the query returns more than one record, a copy of the template will be included for every record found in the database search.
WARNING: It is possible to create circular references, which could have unpredictable and dangerous results.
<!--#echo var="environment variable name"-->
If the environment variable exists in the Perl environment, the tag is replaced by the value of that variable. See the section below on Environmental Variables.
<!--#echo form="submitted form parameter name"-->
If the form parameter name was submitted in the HTTP request, the tag is replaced by the value of that parameter. Form parameter names may be global -- referring to all identically named database fields in a template hierarchy, or local -- by preceding the form parameter name with the short template name the parameter is directed to, followed by a period:
template name.field name
<!--#echo field="database field name"-->
If the field name was defined in the config block, the tag is replaced by the value of that field.
<!--#exec cgi="full or relative path name to CGI executable"-->
If the external cgi executable can be executed, the tag is replaced by the output of the executable. Any substitution tags present in the results will not be processed. Any relative file paths in this call are local to the directory containing the template file.
If the executable returns a Content-type of ``text/html'', the output is included in the results unmodified. If the Content-type is anything else, the output is enclosed in <PRE> tags.
<!--#mktag tag="a_href | input | img | select" [ name="value" ...]-->
Creates certain HTML tags that may contain values filled by database queries. name/value pairs that are not relevant for tag creation are carried through into the created tag. The following tag types can be generated:
A_HREF
Creates an Anchor tag with an HREF parameter. In addition to the standard parameters to this tag, the following parameters my be included:
PATH
Indicates a URL path to be prepended to any value retrieved from variable values (see below), and returned within the HREF parameter. This parameter is consumed.
EXTENSION
Indicates a URL path to be appended to any value retrieved from variable values (see below), and returned within the HREF parameter. This parameter is consumed.
VAR | FORM | FIELD
Indicates the source of the value to be returned in the HREF parameter. Used as in the echo tags (see above). This parameter is consumed.
IFEXISTS
May be used with or without a parameter value. Checks for the existence of the local file referenced by a relative path withing the HREF parameter built for the tag. If the referenced file exists and is readable, the Anchor tag is created; otherwise it is deleted. If a value is provided for this IFEXISTS parameter, it is used as the link text, and a closing Anchor tag (</A>) is appended. This parameter is consumed.
IFRESULTS
May be used with or without a parameter value. Checks the string returned by the var|form|field parameter. If the result length is non-zero, the Anchor tag is created; otherwise it is deleted. If a value is provided for this IFRESULTS parameter, it is used as the link text, and a closing Anchor tag (</A>) is appended. This parameter is consumed.
Note that any relative URLs generated by this tag are local to the directory containing the top-level template.
INPUT
Creates an INPUT tag with it's VALUE parameter set to a query parameter or result. Causes a VAR, FORM, or FIELD parameter to be replaced by a VALUE parameter filled with the variable result as in the echo tags (see above).
IMG
Creates an IMG tag with it's VALUE parameter set to a query parameter or result. Causes a VAR, FORM, or FIELD parameter to be replaced by a SRC parameter filled with the variable result as in the echo tags (see above). The PATH and EXTENSION parameters supported by the A_HREF tag above are also support in a similar way.
SELECT
Creates a complete SELECT tag sequence complete with an option list indicating a SELECTED value. In addition to the standard parameters to this tag, the following parameters my be included:
VAR | FORM | FIELD
Indicates the source of the value to flag as the SELECTED option if matched. This parameter is consumed.
FILE
A relative path name to the file containing a newline-delimited list of option values. Any relative file paths are local to the directory containing the template file. This parameter is consumed.
TEMPLATE
A relative path name to a template intended to generate an option list. Any narrowing of the list is accomplished by query parameters addressed to the template. This parameter is consumed.
<!--#size file="full or relative path name of file-->
The tag is replaced by size in bytes of the referenced file. Any relative file paths are local to the directory containing the template file. If the file does not exist, the tag is removed.
<!--#flastmod file="full or relative path name of file"-->
The tag is replaced by the integer number of days since the file was last modified. Any relative file paths are local to the directory containing the template file. If the file does not exist, the tag is removed.
Normally, templates will only be called by the submission of HTML forms. A template that identifies a database file (through the DBfile parameter) in its config block defines the CGI parameter names expected and recognized by that template in its DBfields parameter.
Any CGI parameter name that is exclusively alphanumeric is a global parameter name. Any template in the hierarchy may use this parameter in a search or submission, if it matches a defined field name within that template.
A CGI parameter name constructed from a template name, as defined by the TemplateName config block parameter, followed by a period, followed by field name from that template, is ignored by all templates in the hierarchy except those for which the field and template names match.
Reserved parameters modify the normal processing of templates. Reserved parameter names may not be used as database field names.
_CMD="[ delete | update | insert | select]"
Specifies the action to be taken when parameters are submitted by the POST method. This parameter is ignored for the GET and HEAD request methods.
If omitted, left blank, or set to any value other than delete or update in the context of a particular template, the default action is to insert a new record into the database.
_CMD can be used as a global command, or directed to a particular template by
preceding it with a template name followed by a period. Example: template._CMD="insert"
The following values are recognized for the _CMD parameter:
select
This is the default for GET request methods. Causes the database to be searched for all records which match all of the criteria provided exclusively (logical AND). Subsidiary templates are repeated to display all matching records. Top-level templates are presented once with field values of the first record matched.
insert
This is the default for POST request methods if either of the following _CMD values are not provided, or if the _CMD parameter is not provided. Causes a new record to be created with the appropriate field parameters provided. If values for key fields are provided, they will be used if unique; an error will be returned if the key field value already exists. If a value for a key field is not provided, a unique, sequential, numeric value will be generated.
delete
Causes any record found as a result of a search of a key field to be deleted. Omitting a key field from the submitted parameter list will cause this operation to fail. Performing this operation on databases without any specified key fields will also fail.
update
The record selected using the submitted key field value is updated using the remaining fields. Omitting a key field from the submitted parameter list will cause this operation to fail. Performing this operation on databases without any specified key fields will also fail.
_SHOW="Template Name"
May only be used in a global context. If this parameter is submitted, then only the template names included in the submission are shown, the remainder are not processed.
_HIDE="Template Name"
May only be used in global context. This parameter indicates the names of templates the should not be processed. It takes precedence over any template names listed in the _SHOW parameter.
_SORT="Field_Name [ Field_Name ]"
If present, causes the result data to be sorted. Requires whitespace separated list of field names. The first field name in the list will be have the highest precedence in the sort. Sorting is performed numerically and then alphabetically, in ascending order.
_SORT can be used as a global command, or directed to a particular template by
preceding it with a template name followed by a period. Example: template._SORT="Field_1 Field_2"
_MAXRESULT="number"
If present, limits the total number of records displayed (ie. the number of times a subsidiary template is repeated) to the number indicated.
_MAXRESULT can be used as a global command, or directed to a particular template by
preceding it with a template name followed by a period. Example: template._MAXRESULT="20"
_NEXTRESULT="Number"
If present, skips the first N-1 records and then displays the Nth record and those that follow. Ignored for non-nested (top level) templates, or templates returning fewer than N results.
_NEXTRESULT can be used as a global command, or directed to a particular template by
preceding it with a template name followed by a period. Example: template._NEXTRESULT="21"
All standard SSI environmental variables are available to use in within an ECHO or MKTAG substitution tag. Several other environmental tags are available within DBT scripts:
DBT_Error
The error message returned by DBT's database when a database operation has failed. This parameter is only available to the alternate error template when the ErrorTmpl parameter has been defined in the Config block.
DBT_TOP
The name of the top template in the hierarchy. The initial template name requested by the remote browser.
DBT_TEMPLATE
The name of the current template being processed.
DBT_TOP_PATH
The file system path from the DOCUMENT_ROOT point to the DBT_TOP template location.
REQUEST_TIME
The Unix CTIME string indicating the time and date at the moment of
template processing. Example: Fri Jan 26 13:41:59 PST 2001
REQUEST_SECS
The Unix time in seconds. This is useful for providing a time stamp that can later be easily sorted.
template_name._NEXTRESULT
The sum of the submitted value for _NEXTRESULT and _MAXRESULT, yielding the value to submit as the _NEXTRESULT parameter to display the next results upon subsequent submission.
NOTE: This value is not defined until after processing begins for the specified
template. Using this parameter in a VAR="" context above the position of the include template= substitution tag will return an unsubstituted tag.
template_name._RESULT_COUNT
The number of result records returned by a select query for a particular template.
NOTE: This value is not defined until after processing begins for the specified
template. Using this parameter in a VAR="" context above the position of the include template= substitution tag will return an unsubstituted tag.
In general, most applications will include at least one top-level template which calls a number of subsidiary templates using an <!--#include template=``template file path''> tag. The subsidiary templates are used for queries resulting in multi-item reports. Any template capable of action on a database includes the config block that references a database file, and includes the <!--#echo field=``''> substitution tags which are replaced with query results.
Don't forget that the _CMD parameter can address different commands to nested templates than to the top-level templates. In most applications created by the author, many hidden INPUT tags were used to manage the behavior of a template hierarchy.
HREFs within subsidiary templates point to locations relative to the top level template (not to the location of the subsidiary template). However, file paths to the included files and templates within subsidiary templates appear relative to the directory location of the subsidiary template.
A detailed HOWTO document is also included with the package to aid less experienced users.
The Apache web server permits new types and actions to be configured into it. This can allow ``.httml'' files to be submitted to DBT to be processed without addressing the script within the URL.
To enable this capability, Add the following lines to the srm.conf file:
AddType text/template-html .httml
Action text/template-html /cgi-bin/DBT
AddType causes the Apache server daemon to recognize a file with the ``.httml'' suffix as one to require special handling. The Action directive indicates the path, relative to document root, to the handler for this data type.
Using this configuration can enhance security, making it impossible for a client to request an unprocessed template.
One requested feature is for BLOBs (Binary Large OBjects) -- binary file upload and retrieval.
It would be desirable to implement the full range of SSI tags, not the subset supported now.
It would also be desirable to allow tieing to other types of databases, not just Sprite (which is relatively slow). This would require a rewrite to support standard PERL DBI -- a desirable goal in any case.
Someday, in a galaxy far, far away, it would be nice to rewrite this into an Apache module.
This script requires Perl version 5.004 or later.
This script requires the Sprite.pm package by Shishir Gundarvaram. It's available at:
http://www.cpan.org/modules/by-module/Sprite/
This script has only been tested with the Apache web server.
DBT has been tested on the Unix variants: Solaris, OpenBSD, LinuxPPC, Linux x86, Irix, MacOS X Server, and
MachTen.
DBT is classified as a CGI script in CPAN.
Bug reports, feature requests, and other comments may be sent to the author:
stevesgt@effable.com (Steven Sergeant)
©1999 - 2001 by Steven Sergeant.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA =cut
0.5 1998/11/19 Works for select only
0.6 1999/01/26 Initial working release
0.7 1999/04/04 Added MKTAG function, _SORT, _MAXRESULT, and _NEXTRESULT commands.
0.71 1999/04/11 Fixed file pathing bugs.
0.72 1999/04/12 Added SpriteEsc and SpriteUnEsc functions to fix some SQL errors.
0.8 1999/05/27 Added support for Apache security, added other security fixes, improved docs.
0.81 1999/08/20 Documented additional environment variables, added error reporting for access-denied, fixed show/hide bug w/like template names.
0.82 1999/10/22 Fixed a SpriteEsc/SpriteUnEsc bug
0.821 2000/05/18 Added REQUEST_SECS
0.822 2001/01/24 Added _RESULT_COUNT
0.823 2001/01/26 Added IMG type for mktag
0.83 2001/05/09 Added limited support for "exec cgi" or "include cgi", IFRESULT parameter for A_HREF mktag, added _NEXTRESULT environment variable, set default template name to template file name.