Web Mill Tutorial (crash course version!)
The Web Mill is a package (rather a collection of PERL scripts) that automates as far as
possible the generation of a user interface to a back end data base. The most common use
for this application is to present a catalogue on line. To see a complete list of the files
used for this tutorial, click here. The
files can be downloaded for use as a skeleton application by right clicking on each one and
selecting "Save". To try out the application, click
here. The stages that a user
will see and interact with are the "Search Interface", the "Results List" and the
"Data Sheet". All aspects of how the pages are displayed are controlled by a single INI
file and a collection of templates. The INI file used for this tutorial is shown below. All
file paths are relative to the site root ie all sample files are in the "examples" directory
therefore all file refrences begin "examples/".
# Parameters required for ODBC_OPTION(S).PL, ODBC_SEARCH.PL
# & ODBC_DATA.PL.
# 'key' & 'data_template' are not required if DATA.PL is not used.
# No items are case sensitive.
# All modules require the below parameters
dbq=examples/videos.mdb # Database to connect to.
drv=Microsoft Access Driver (*.mdb) # Database driver to use.
data_table=stock # Database table to use.
# Parameters required for ODBC_OPTION.PL & ODBC_OPTIONS.PL
incs=category,title,media # Coloumns from "data_table"
# to use in search interface.
alt_incs= Category, Video title, Media
# Alternative column titles
# to display in search interface.
# Parameters required for ODBC_OPTION.PL
option_action=../public-bin/ODBC_search.pl
# Parameters required for ODBC_SEARCH.PL
list_template=examples/video_list.htm # Output template for
# search results.
list_table=examples/video_table.htm # Table to format each result
list_max=4 # Maximum no. of results
# before inserting page break.
alt_col=E5E5D1,E8E8E5 # Alternating background
# colours for results list.
# Parameters required for ODBC_DATA.PL
key=media,title # Primary record key (column
# header names).
data_template=examples/video_data.htm # Template to display
# product data.
# Web Mill (c) B.O'Grady 1998
The INI File
The INI file is the glue that holds the whole application together. It is used by the
interpriter to control the behaviour of the various modules. Each line of the INI file
may be a "comment", a "directive" or a "combo". Blank lines are ignored.
Comments are any line beginning with a # sign. Comments can and
should be used any where to add clarity to the INI file. An example comment is shown below.
# This is a comment.
Directives are used by the interpriter to control the action
and flow of the application. A directive consists of a key and a value or collection of values.
Keys that support multiple values should have each value separated by a comma. The key and
value(s) are serarated by an equals sign. The examples below show how a single key/value directive
and multi value directive are constructed.
list_max=4
alt_col=ff0000,00ff00,0000ff
Combos are directives with comments. An example combo is shown
below.
data_table=stock # Database table to use.
The comment must occur after the directive. Any white space between the value and comment is ignored. Spaces
or tabs may be used to seperate directives and comments.
All INI files must start with the information required to connect the data source. The basic
information required is:-
a) The name of the data base to use.
b) The table within the data base to use.
c) The ODBC data base driver to use.
An example of how to configure an existing data base is shown below.
dbq=examples/videos.mdb # Database to connect to
data_table=stock # Database table to use
drv=Microsoft Access Driver (*.mdb) # Database driver to use
The DRV directive is particularly important as it points to a specifically installed
ODBC driver. The spelling shown above must be copied exactly otherwise the data connection
will fail. If your system administrator has set you up with an ODBC System DSN, then you can replace the
DBQ and DRV refrences with a single DSN reference - see below.
dsn=MySystemDSN # Pre-defined system DSN
The Search interface
The first point of contact the user has with your catalogue is with a search interface of some description. In the
following examples I will be using a simple Access data base with only one table. The data base
is called "VIDEOS.MDB" and the table is called "STOCK". To see the data table, click here.
IMPORTANT NOTE -
The Web Mill application only supports TEXT data. Each column in your data tables
must be formatted as "TEXT" for short fields (less than 256 characters) or "MEMO" for fields
greater that 255 characters (and less than 64k characters). Fields formatted in any other way
will cause undesirable application behaviour.
The Web Mill application has two metods of presenting a search interface to the end user, They are the "List Interface"
which is similar to a table of contents and the "Option Box Interface" which allows your user to use
a more customised search mechanism. Click
here to see examples of both interfaces.
List Interface -
You nominate a column from you data table to generate the table of contents and the application
does the rest. To tell the application which column to use to generate the TOC, simply nominate
it in the INI file using the INCS directive. The format is shown below. NB The
option_action directive is a fixed value required for the list interface.
incs=category # Column to use to generate a T.O.C.
option_action=../public-bin/ODBC_search.pl
# Required for list interface
In this example, our video data base has a column called category. This categorises our
video data base titles into categories such as "Cartoons", "Earling learning" etc. If your INCS
directive contains more than one value, only the first is used and the rest are ignored.
To get your TOC to appear in a web page, it is necessary to invoke the script that generates it.
The code sample below shows how to invoke the script. You can easily modify it to suit the style of
the web page that you want to include it in.
<table border="0" bgcolor="#ddddff" cellspacing="0">
<tr bgcolor="#9999ff">
<td><b>Example of a single click interface</b></td>
</tr>
<!--#exec cgi="/public-bin/ODBC_option.pl?ini=examples/videos.ini"-->
</table>
The output of the code is shown below.
IMPORTANT NOTE - The web page containing the "#exec cgi" line must
end in the extension ".shtm" not ".htm" or ".html". This lets the server know that it has to process
the embedded CGI command before sending the rendered page to the calling browser.
Option Box Interface -
You nominate one or more columns from you data table to generate an option box and the application
does the rest. To tell the application which columns to use to generate the option box, simply nominate
them in the INI file using the INCS directive. The format is shown below.
incs=category,title,media
alt_incs=Category,Video title,Media format
The directive ALT_INCS provides a way to overide the actual column name with more user
friendly alternatives. The ALT_INCS substitutions will replace in the same order that the
INCS names appear.
In this example, our video data base has columns called category, title and media but they will
be displayed as "Category", "Video title" and "Media format". This allows the
user to make a more selective search eg search for "Sleeping Beauty" on "DVD".
To get your option box to appear in a web page, it is necessary to invoke the script that generates it.
The code sample below shows how to invoke the script. You can easily modify it to suit the style of
the web page that you want to include it in.
<form method="post" action="../public-bin/ODBC_search.pl" name="form">
<input type="hidden" name="ini" value="examples/videos.ini">
<table border="0" bgcolor="#ddddff" cellspacing="0">
<tr bgcolor="#9999ff">
<td colspan="2">
<b>Example of a more complex search interface</b>
</td>
</tr>
<!--#exec cgi="/public-bin/ODBC_options.pl?ini=examples/videos.ini"-->
<tr>
<td><input type="reset" name="reset" value="Reset">
<input type="submit" name="search" value="Search"></td>
<td> </td>
</tr>
</table>
</form>
The code required for this type of interface is somewhat more complicated as the users information
has to be gathered in a form. Note that the all important "#exec cgi" line is almost identical.
The only diffference is that it calls "ODBC_OPTIONS.PL" instead of "ODBC_OPTION.PL" (the extra
S is essential!). The output of the code is shown below.
IMPORTANT NOTE - The web page containing the "#exec cgi" line must
end in the extension ".shtm" not ".htm" or ".html". This lets the server know that it has to process
the embedded CGI command before sending the rendered page to the calling browser.
The Result List
Both of the above user interfaces call the "Search" module when the user clicks on the appropriate
link. The "Search" module takes the users query and generates a list of matching results. The
results are displayed into a pre defined template and each result is formatted into a predefined
table or table row. In order to tell the "Search" module how to display the results, the INI
file needs to have the following directives included:-
LIST_TEMPLATE - This line tells the "Search" module the path and name
of the template to use for displaying results. See the line below for an example LIST_TEMPLATE
directive. A sample list template is given later in this document.
list_template=examples/video_list.htm # Template for search results.
LIST_TABLE - This template is used to tell the "Search" module how
to format each item matching the query when displaying them in the list template. See the line
below for an example LIST_TABLE directive. A sample list table is given later in this document.
list_table=examples/video_table.htm # Table to format each result.
LIST_MAX - This directive is optional. If your users search is likely
to yield many results, then it is usually more convenient to display the results in pages rather
than all in one go. It will also alleviate long pauses and blank displays while the data is
being prepared. The value for the LIST_MAX directive is how many results are displayed before
a page break is put into the results list. If this directive is ommited, then the search module will
simply return all matching results to the browser. See the line below for an example LIST_MAX
directive.
list_max=4 # Maximum no. of results before
# inserting a page break.
ALT_COL - This directive is also optional. It is used to add a bit
of clarity to results lists. The ALT_COL directive can have one or more values. Each
value should be sparated by a comma. When displaying results, the "macro word" $ALT_COL$
(an explanation of "macro words" will come later) in the LIST_TABLE template will be
replaced with one of the ALT_COL values. The values will be incremented and cycled as many
times as necessary till the result list is complete.
alt_col=E5E5D1,E8E8E5 # Alternating colours for list.
KEY - This directive is required. It describes the primary key for the
current table in the data base. A primary key is one
or more columns that uniquely identifies a record. In our video data base, you could assume that the
primary key was the "TITLE" column. However on closer inspection of the data, "Sleeping Beauty"
appears twice; once in Video format and once in DVD format. Thus the primary key for our data base
is the "TITLE" column plus the "MEDIA" column. This information is represented by the directive
below.
key=media,title # Primary record key columns.
SORT - This directive is optional. It is used to organise search
results alphabetically. The directive suppoorts multiple values, each seperated by a comma. Each
value must be a valid column name. If more than one value is present, the data is
sorted using the earliest items in the list of values first. A sample sort directive is
shown below.
sort=title,media # Sort by title then format.
The code sample below shows how each directive is used in our video catalogue data base.
list_template=examples/video_list.htm # Template for search results.
list_table=examples/video_table.htm # Table to format each result.
list_max=4 # Maximum no. of results before
# inserting a page break.
alt_col=E5E5D1,E8E8E5 # Alternating colours for list.
key=media,title # Primary record key columns.
The List Template and Macro Words
The list template is the container page for the output of the "Search" module. It supports
two macro words which are $table$ and $more$. A macro word is a marker placed
in the template which is interprited by the module processing the template - in this case
the "Search" module. All macro words start and finish with the dollar ($) sign.
$TABLE$ - This macro word tells the "Search" module where
to insert the search results. Each result will be formatted by the list_table template.
$MORE$ - This macro word is optional and works in conjunction with
the list_max directive in the INI file. A list navigation bar comprising next/previous
page links will be inserted into the list_template at the point where the $more$
macro word appears. A sample list_template is shown below.
<table>
<tr bgcolor="#ddddff">
<td width="80%">
<b>Title</b>
</td><td width="20%">
<b>Price</b>
</td>
</tr>
$table$
<tr bgcolor="#ddddff">
<td colspan="2" align="center">
<b>$more$</b>
</td>
</tr>
</table>
The List Table Template and Macro Values
The list table template is used to format each result as it is displayed in the result list. The
template comprises standard HTML code and macro words and values. The only macro word currently
implemented in the list table template is $key$. A single formatting directive (~)
is also available.
$KEY$ - This macro word tells the "Search" module to insert the
primary key for the current record being displayed.
~ - Placing a tilda (~) in front of a macro word directs the
active module to URL encode the macro value. This is necessary where a macro value forms part of
an active link. The ~ directive will for example encode a spaces as %20.
Macro values - These are simply references to values in the data
base for the currently selected record. All macro values start and finish with a dollar ($)
sign and must reference a valid column name in the current table. For example, the sample list table
template shown below contains the macro value $price$. The active module will replace
each occurance of $price$ with the value found in the "PRICE" column in the data base for
the current record. IMPORTANT NOTE - It is not possible to have
a column in your data base called "KEY" as it will clash with the $key$ macro word. A
sample list table template is shown below.
<tr bgcolor="#$alt_col$">
<td width="80%">
<a href="ODBC_data.pl?ini=examples/videos.ini&record=$~key$">
<b>$title$</b></a>
</td><td width="20%" align="right">
<font size="+1">
<b>£$price$</b>
</font>
</td>
</tr>
If your application does not need to go to the "Data sheet", then the active link
(the green text) reference in the
above list table template can be ommitted.
The Data Sheet
The "Data sheet" provides a mechanism for displaying data about a single record in a pre defined
template. The only directive required for the "Data sheet" module is DATA_TEMPLATE. Although
it requires other directives to operate, such as the key directive, these will have
already be defined for the "Search List" and "Results List" modules to use.
$DATA_TEMPLATE$ - This directive is pretty much the same as the
list_template. It's value points to a file/path reference for the template. A sample set
of "Data sheet" directives are shown below.
key=media,title # Primary record key
data_template=examples/video_data.htm # Template to display
The "Data sheet" module does not support any macro words. Instead it is used for populating the
data_template with macro values for the currently selected record. See the previous
section for a full explanation of macro values. A sample data_table is shown below.
<table border="0" width="90%" align="center">
<tr bgcolor="#9999ff">
<td colspan="2" align="center">
<b><font size="+2">$title$ - </font>$category$</b>
</td>
</tr>
<tr bgcolor="#ddddff">
<td width="80%">
<b>$thumbnail$<br><br>($studio$)</b>
</td><td width="20%">
<b><font size="+2">£$price$</font></b><br>
($media$ format)
</td>
</tr>
</table>
And that's pretty much it! To contribute or make comments, click here.
Webmill (c) B.O'Grady 1998