\input texinfo                @c -*- Texinfo -*-
@c %**start of header
@setfilename catalog.info
@settitle @code{Catalog}
@setchapternewpage odd
@c %**end of header

@set RCSID $Id: catalog.texinfo,v 1.21 1999/04/14 11:29:44 ecila40 Exp $
@set VERSION 0.5
@set UPDATED April 1999
@set PERL perl5.005_02
@set MySQL MySQL-3.22.19a-gamma

@c Combine the variable and function indices:
@syncodeindex vr fn
@c Combine the program and concept indices:
@syncodeindex pg cp

@titlepage
@title Catalog
@subtitle A catalog system based on a SQL database
@subtitle @code{Catalog} Version @value{VERSION}
@subtitle @value{UPDATED}
@author Lo@"{@dotless{i}}c Dachary, Marc L@'eguistin, Thierry Delamare
@page
@vskip 0pt plus 1filll

 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
 are preserved on all copies.

 Permission is granted to copy and distribute modified versions of this
 manual under the conditions for verbatim copying, provided that the entire
 resulting derived work is distributed under the terms of a permission
 notice identical to this one.

 Permission is granted to copy and distribute translations of this manual
 into another language, under the above conditions for modified versions,
 except that this permission notice may be stated in a translation approved
 by the Free Software Foundation.
@end titlepage
@page

@ifinfo
@node Top, Introduction, (dir), (dir)
@top Catalog

@code{Catalog} is a perl program that allows to create, maintain and display
Yahoo! like directories. The user interface is 100% HTML. It requires a
MySQL database to run. 

@end ifinfo

@menu
* Introduction::                Introduction
* Getting Catalog::             Getting Catalog
* Setup::                       Setup
* Migration to Catalog-0.5::    Migration to Catalog-0.5
* First use::                   First use
* Catalog management guide::    Catalog management guide
* Full text search::            Full text search
* Catalog tables::              Catalog tables
* Configuration files::         Configuration Files
* External representation::     External representation
* Template files introduction::  Template files introduction
* Catalog template files::      Catalog template files
* SQL template files::          SQL template files
* CGI introduction::            CGI introduction
* Catalog CGI::                 Catalog CGI
* SQL manipulation CGI::        SQL manipulation CGI
* Relational constraints::      Relational constraints
* Messages translation::        Messages translation
* Catalog and HTTP server::     Catalog and HTTP server
* Glossary::                    Glossary
* Environment variables::       Environment variables
* Troubleshooting::             Troubleshooting
* Concept Index::               Index of Concepts

@detailmenu
 --- The Detailed Node Listing ---

First use

* Control Panel::               Control Panel
* Creation form::               Creation form
* Catalog editing::             Catalog editing
* Inserting entries::           Inserting entries
* Browsing::                    Browsing
* Conclusion::                  Conclusion

Catalog management guide

* Goal::                        Goal
* Create a table::              Create a table
* Example installed::           Example installed
* Quick tour::                  Quick tour
* Records ordering::            Records ordering
* Record layout (urlcatalog)::  Record layout (urlcatalog)
* Overriding a template (urlcatalog)::  Overriding a template (urlcatalog)
* Customizing user view (urlcatalog)::  Customizing user view (urlcatalog)
* Customizing search results (urlcatalog)::  Customizing search results (urlcatalog)
* Customizing chronological browsing (urldate)::  Customizing chronological browsing (urldate)
* Customizing alphabetical browsing (urlalpha)::  Customizing alphabetical browsing (urlalpha)
* More customization::          More customization

Full text search

* Default full text::           Default full text
* Real full text::              Real full text

Catalog tables

* Catalog tables introduction::  Catalog tables introduction
* catalog::                     Catalog tables introduction
* catalog_category_<name>::     catalog_category_<name>
* catalog_category2category_<name>::  catalog_category2category_<name>
* catalog_entry2category_<name>::  catalog_entry2category_<name>
* catalog_path_<name>::         catalog_path_<name>
* catalog_alpha_<name>::        catalog_alpha_<name>
* catalog_date_<name>::         catalog_date_<name>

Configuration files

* Catalog configuration file::  Catalog configuration file
* MySQL configuration file::    MySQL configuration file
* CGI configuration file::      CGI configuration file
* Install configuration file::  Install configuration file
* SQL editor configuration file::  SQL editor configuration file
* Template configuration file::  Template configuration file
* Hook Fulcrum configuration file::  Hook Fulcrum configuration file

External representation

* XML short example::           XML short example
* XML document encoding::       XML document encoding
* XML structure::               XML structure
* dmoz.org::                    dmoz.org

Template files introduction

* Templates switch table::      Templates switch table
* Fixed tags::                  Fixed tags
* Database table tags::         database table tags
* Record list part::            Record list part
* Multipage results template::  Multipage results template
* Actions that takes a long time::  Actions that takes a long time

Catalog template files

* ccontrol_panel.html::         ccontrol_panel.html
* calpha_root.html::            calpha_root.html
* calpha.html::                 calpha.html
* cedit.html::                  cedit.html
* cbrowse_root.html::           cbrowse_root.html
* cbrowse.html::                cbrowse.html
* csearch.html::                csearch.html
* cdate_default.html::          cdate_default.html
* cdestroy.html::               cdestroy.html
* centryremove_all.html::       centryremove_all.html
* catalog_theme_insert.html::   catalog_theme_insert.html
* catalog_theme_edit.html::     catalog_theme_edit.html
* catalog_alpha_insert.html::   catalog_alpha_insert.html
* catalog_alpha_edit.html::     catalog_alpha_edit.html
* catalog_date_insert.html::    catalog_date_insert.html
* catalog_date_edit.html::      catalog_date_edit.html
* cdump.html::                  cdump.html
* cimport.html::                cimport.html
* cexport.html::                cexport.html

SQL template files

* sqledit_search_form.html::    sqledit_search_form.html
* sqledit_sinsert_form.html::   sqledit_sinsert_form.html
* sqledit_edit.html::           sqledit_edit.html
* sqledit_search.html::         sqledit_search.html
* hook_search.html::            hook_search.html
* sqledit_remove.html::         sqledit_remove.html
* sqledit_remove_confirm.html::  sqledit_remove_confirm.html
* error.html::                  error.html
* sqledit_requests.html::       sqledit_requests.html

CGI introduction

* Diagram::                     Diagram
* Notation::                    Notation
* Style parameter::             Style parameter
* Database table parameters::   Database table parameters
* Primary parameter::           Primary parameter
* Recursive CGI call::          Recursive CGI call
* CGI called with PATH_INFO::   CGI called with PATH_INFO
* Multipage results parameters::  Multipage results parameters

Catalog CGI

* Control panel (ccontrol_panel)::  Control panel (ccontrol_panel)
* Ask for catalog destruction (cdestroy)::  Ask for catalog destruction (cdestroy)
* Catalog destruction (cdestroy_confirm)::  Catalog destruction (cdestroy_confirm)
* Reset count on alpha catalog (calpha_count)::  Reset count on alpha catalog (calpha_count)
* Reset count on theme catalog (category_count)::  Reset count on theme catalog (category_count)
* Build a new catalog (cbuild)::  Build a new catalog (cbuild)
* Modify catalog properties (ccatalog_edit)::  Modify catalog properties (ccatalog_edit)
* Browse alphabetical catalog root (calpha)::  Browse alphabetical catalog root (calpha)
* Browse alphabetical catalog (calpha)::  Browse alphabetical catalog (calpha)
* Browse theme catalog root (cbrowse_root)::  Browse theme catalog root (cbrowse_root)
* Browse theme catalog (cbrowse)::  Browse theme catalog (cbrowse)
* Intuitive navigation (pathcontext)::  Intuitive navigation (pathcontext)
* Catalog search (csearch)::    Catalog search (csearch)
* Browse chronological catalog (cdate)::  Browse chronological catalog root (cdate)
* Edit panel for a category node (cedit)::  Edit panel for a category node (cedit)
* Remove a category (categoryremove)::  Remove a category (categoryremove)
* Insert a category (categoryinsert)::  Insert a category (categoryinsert)
* Link a catalog entry (centryselect)::  Link a catalog entry (centryselect)
* Create and link a catalog entry (centryinsert)::  Create and link a catalog entry (centryinsert)
* Create a symbolic link (categorysymlink)::  Create a symbolic link (categorysymlink)
* Unlink a catalog entry (centryremove)::  Unlink a catalog entry (centryremove)
* Ask to remove a catalog entry (centryremove_all)::  Ask to remove a catalog entry (centryremove_all)
* Remove a catalog entry (centryremove_all_confirm)::  Remove a catalog entry (centryremove_all_confirm)
* Ask for confirmation before dump (cdump)::  Ask for confirmation before dump (cdump)
* Dump a thematic catalog (cdump_confirm)::  Dump a thematic catalog (cdump_confirm)
* Query parameters for load (cimport)::  Query parameters for load (cimport)
* Load a thematic catalog from file (cimport_confirm)::  Load a thematic catalog from file (cimport_confirm)
* Query parameters for unload (cexport)::  Query parameters for unload (cexport)
* Unload a thematic catalog to file (cexport_confirm)::  Unload a thematic catalog to file (cexport_confirm)

SQL manipulation CGI

* Record edit form (edit)::     Record edit form (edit)
* Record update (update)::      Record update (update)
* Search form (search_form)::   Search form (search_form)
* Record insert form (sinsert_form)::  Record insert form (sinsert_form)
* Record insert (sinsert)::     Record insert (sinsert)
* Record remove (remove)::      Record remove (remove)
* Remove confirm (remove_confirm)::  Remove confirm (remove_confirm)
* Search table (search)::       Search table (search)
* Hook search (hook_search)::   Hook search (hook_search)

Catalog and HTTP server

* Apache::                      Apache
* Cgi-bin errors::              cgi-bin errors
* Using mod_perl::              Using mod_perl

@end detailmenu
@end menu

@node Introduction, Getting Catalog, Top, Top
@chapter Introduction

@code{Catalog} is a perl program that allows to create, maintain and display
Yahoo! like directories. The user interface is 100% HTML. It requires a
MySQL database to run. 

The general idea behind the design of Catalog is that creating a catalog
is mainly a matter of organizing objects in a structured tree. For
@code{Catalog} the objects are records in a table of the SQL database. 
The structured tree is a set of tree nodes and relations between these
nodes. The maintainer of the catalog is in charge of building the tree
and placing objects in this tree.

@code{Catalog} makes no assumption about the data contained in the records.
It is not designed specifically to build a catalog of URLs, despite the fact
that we mainly use it to classify URLs. It can be used to classify companies,
bug reports and so on.

Special care has been taken to allow easy customization of a catalog, from 
the programmer point of view and from the HTML page designer point of view.
Although the program structure is not documented at present, the choice of
simple perl object orientation should ease the specialization for specific
purposes. The HTML display is completely controlled by a set of template files.
The template files structure has been kept as simple as possible so that
only minimal comprehension is necessary from the HTML page designer. In 
particular it behaves well with page composer tools like Dreamweaver or
PageMill.

Here is a list of the characteristics of @code{Catalog}:
@itemize @bullet
@item
Display structured trees of resources.
@item
Display chronologically ordered resources and associated calendar.
@item
Display alphabetical indexes of resources.
@item 
Allow full text search in the resources and the category names.
@item
Powerful HTML based administration of catalogs.
@item
On-Line editing of resource records.
@item
Handle an arbitrary number of catalogs.
@item
High performances using mod_perl and Apache.
@item 
Easy customization of the user view using HTML template files.
@item
It is possible to define more than one view of the same catalog.
@item
Load and unload a thematic catalog in XML.
@item
Create an HTML dump of a structured tree to publish a static 
version.
@item
Complete documentation including a guide and a reference manual.
@item
Ready to use example.
@item
100% Perl.
@item
Distributed under the GNU General Public License.
@item
Commercial support.
@end itemize

@node Getting Catalog, Setup, Introduction, Top
@chapter Getting Catalog

The home site of Catalog is Senga 
@uref{http://www.senga.org/, http://www.senga.org/}. It contains the software,
a working example, online documentation, 
formated documentation and related software for various
platforms.

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., 675 Mass Ave, Cambridge, MA 02139, USA.

@node Setup, Migration to Catalog-0.5, Getting Catalog, Top
@chapter Setup

@cindex setup
@cindex dependencies
@cindex MySQL
@cindex Perl

@code{Catalog} requires @value{PERL} or higher and @value{MySQL} or higher
to run. More detailed instructions may be found in the distribution.

@cindex cgi-bin directory
@cindex program location

Since the user interface to @code{Catalog} is only HTML and not command
line oriented, the installation process will install a cgi-bin on the 
local machine. Before installing @code{Catalog} you should therefore know
where are located your cgi-bin (let's say it's the @code{CGIDIR} directory).

@cindex install

To install the @code{Catalog} software follow these steps:

@itemize @bullet
@item
gtar -zxvf Catalog-@value{VERSION}.tar.gz
@item
cd Catalog-@value{VERSION}
@item
perl Makefile.PL
@item
make all
@item
make test
@item
make install
@end itemize

If something went wrong, check
@xref{Troubleshooting, , @code{Troubleshooting}}.

@cindex control panel
@cindex entry point
@cindex first use of the catalog

Now that the software is installed you should be able to display the 
HTML control panel page. Check that your 
@code{MySQL} server is running. Assuming that your machine is 
@code{www.mymachine.org} the URL for the control panel should be something
like

@center http://www.mymachine.org/cgi-bin/Catalog?context=ccontrol_panel

Copy this URL, change @strong{www.mymachine.org} with your host name.
If you are reading this documentation in HTML format with your browser, open
a new browser window and place it beside the window containing this 
documentation. Now go to the URL you've just edited.

You should now see the control panel. The following chapter is a guide that
shows you how to create your first catalog from scratch. If you
don't get the control panel, @xref{Troubleshooting, , @code{Troubleshooting}}.

The @strong{Catalog management guide} chapter will show you how to build 
a fully functional catalog, using an example installed with @strong{Catalog},
@xref{Catalog management guide,,@code{Catalog management guide}}.

@node Migration to Catalog-0.5, First use, Setup, Top
@chapter Migration to Catalog-0.5

The database structure of @strong{Catalog-0.5} is not compatible with versions of
@strong{Catalog} under version 0.3.
Migration is quite straight forward, however.

The new table @strong{catalog_path_<name>} will be created automatically, no manipulation is
necessary.

The @strong{catalog} table structure has changed and must be modified using the following 
SQL instructions:

@example
alter table catalog add dump varchar(255);
alter table catalog add dumplocation varchar(255);
@end example

@node First use, Catalog management guide, Migration to Catalog-0.5, Top
@chapter First use

We will guide you on a step by step tour of the Catalog functionalities. This
tour assumes that you've successfully completed the setup 
, @xref{Setup, , @code{Setup}}.

During all the tour the machine name taken in example will be 
@code{www.mymachine.org}, an anonymous GNU Linux box.

@menu
* Control Panel::               Control Panel
* Creation form::               Creation form
* Catalog editing::             Catalog editing
* Inserting entries::           Inserting entries
* Browsing::                    Browsing
* Conclusion::                  Conclusion
@end menu

@node Control Panel, Creation form, First use, First use
@section Control Panel

First display the control panel using the URL 

@uref{http://www.mymachine.org/cgi-bin/Catalog?context=ccontrol_panel,}.

@image{images/controlpanel,10cm,}

Click on the @strong{Yes, setup a catalog} button to create the administrative
tables needed by @code{Catalog}. The page displayed in response should be 
something like :

@image{images/controlpanel2,10cm,}

The line beginning with @code{Create ...} shows a menu that contains
the list of all the tables of the current database. In this example we've
used the @code{mysql} database, which is the default database created when
you install @code{MySQL}. 

The @strong{Create a demo table} link at the bottom of the page creates 
a sample table for the purpose of the demo. This table, named @code{urldemo}
contains two fields : an URL and a COMMENT. Click on the link to create the
table. When the table is created, the control panel is displayed again. You
can now see the @code{urldemo} table when scrolling the menu that lists all
the tables of the database.

@image{images/controlpanel3,10cm,}

Please chose the @code{urldemo} item in the menu and click on 
the @strong{Create it} button on the right of the menu. 

@node Creation form, Catalog editing, Control Panel, First use
@section Creation form

The catalog creation page
shows all the information that describe the catalog being created. In this
case we will just fill the name of the catalog with @strong{urlcatalog}
as shown below.

@image{images/catalogcreate,10cm,}

You should then click on the @strong{Create it} button and the catalog will be
created. As a result the program will display the control panel and you should
see a line for the newly created catalog.

@image{images/controlpanel4,10cm,}

@node Catalog editing, Inserting entries, Creation form, First use
@section Catalog editing

Now that the catalog @strong{urlcatalog} is ready for classifying the records
of the table @strong{urldemo}, we would like to create categories and put 
entries in them. First click on the @strong{edit} link on the control panel to
get the catalog editing screen that shows the root of the catalog.

@image{images/rootedit,10cm,}

At present the catalog does not contain anything, therefore the editing screen
does not show much. Our first step will be to create three categories, 
@code{Software}, @code{Sport} and @code{Movies}. To create the first category,
click on the @image{images/open,,} icon and type @code{Software} in
the @code{Category name} field. 

@image{images/categoryinsert,10cm,}

Then click on the @code{Create it!} button. Repeat the same procedure for the
@code{Sport} and @code{Movies} categories. When finished you should get the
following screen:

@image{images/categoryinsert2,10cm,}

You can then click on the @code{Software} link to insert sub categories of the
@code{Software} category in the same way you created the top level categories
@code{Software}, @code{Sport} and @code{Movies}. Let's insert the sub categories
@code{Language} and @code{Freeware}. Note that the path of the current category
is shown before the @code{Sub categories} label so that you know where you're
inserting categories.

@image{images/categoryinsert3,10cm,}

@node Inserting entries, Browsing, Catalog editing, First use
@section Inserting entries

Now that we've created a category tree, we can populate it with entries. Let's
assume we are editing the Software category. 

@image{images/categoryinsert3,10cm,}

Since the @code{urldemo} table is empty we should create
an new record and place it in the @code{Software} category. The
@image{images/new,,} icon does exactly this. Please click on it to get the
following screen:

@image{images/entryinsert,10cm,}

This is an insertion form for the @code{urldemo} table. Fill the @code{url}
and @code{comment} field as shown on the screen shot and click on insert.
The @code{Software} category is displayed again and the newly created entry
is shown.

@image{images/entryinsert2,10cm,}

@node Browsing, Conclusion, Inserting entries, First use
@section Browsing

Although our catalog does not contain a lot of entries, we are now able to 
browse it to see it from the user point of view instead of the administrator
point of view. You can go back to the @code{Control Panel} using the link at
the bottom of the screen and then click on @strong{browse} link.

@image{images/browse,10cm,}

@node Conclusion,  , Browsing, First use
@section Conclusion

This short demonstration demonstrates how to initialize a new catalog
from scratch. In the following chapter is a complete guide based on
a ready to use example.

@node Catalog management guide, Full text search, First use, Top
@chapter Catalog management guide

@menu
* Goal::                        Goal
* Create a table::              Create a table
* Example installed::           Example installed
* Quick tour::                  Quick tour
* Records ordering::            Records ordering
* Record layout (urlcatalog)::  Record layout (urlcatalog)
* Overriding a template (urlcatalog)::  Overriding a template (urlcatalog)
* Customizing user view (urlcatalog)::  Customizing user view (urlcatalog)
* Customizing search results (urlcatalog)::  Customizing search results (urlcatalog)
* Customizing chronological browsing (urldate)::  Customizing chronological browsing (urldate)
* Customizing alphabetical browsing (urlalpha)::  Customizing alphabetical browsing (urlalpha)
* More customization::          More customization
@end menu

@node Goal, Create a table, Catalog management guide, Catalog management guide
@section Goal

This chapter will explain the most common usage of @strong{Catalog} using an example
set of catalogs created when you installed the product. You will not have to create a catalog
by yourself. Everything is ready to use and we will only comment what have
been done. You should sequentially read this chapter since concepts are
introduced in each section and are needed to understand the following section.

Ideally the example provided with the @strong{Catalog}
distribution will allow you to build your own catalogs in a few cut and paste operations,
without the need to fully read and understand the reference documentation.

@node Create a table, Example installed, Goal, Catalog management guide
@section Create a table

In the example used in this chapter, the @strong{urldemo} table contains the data
used in all the catalogs. Since your own application is likely to require a different
kind of data you will have to create your own table. 

A few requirements must be met when creating a table that will be used by catalogs (thematic,
alphabetical or chronological).

@itemize @bullet

@item
The table @strong{must} contain a numerical field named @strong{rowid}
which is the primary key so that @strong{Catalog} can use it. Here is
a typical example:

@example
create table urldemo (
...
  rowid int autoincrement,
...
  unique urldemo1 (rowid)
);

@end example

@item
The table field names  @strong{must} only be alphanumerical. Specifically it may not
contain underscore which is a reserved character for @strong{Catalog}.

@item
It is best if you take care not to use any field names used in the catalog administrative tables.
Although this will never be a real problem, it will force you to always disambiguate the field
names by prepending the name of the table in front of it. For a complete list of the field
names used by @strong{Catalog}, @xref{Catalog tables,,@code{Catalog tables}}.

@end itemize

If you're not sure how to create a new table, please refer to the MySQL documentation.
If you want to do it quick and dirty you can guess from the table creation listed in the
@strong{Catalog tables} chapter.

At present we will use the @strong{urldemo} table, you don't have to
worry about creating a new table. 

@node Example installed, Quick tour, Create a table, Catalog management guide
@section Example installed

When @strong{Catalog} is installed, it builds an example database and copies two catalog
configuration profiles. An HTML page gives access to the example and is installed in the
same directory as the documentation (HTMLDIR when @strong{Catalog} is installed). 
If you've installed the documentation in the
@code{HTMLDIR/Catalog/} directory, 
the URL http://www.mymachine.com/Catalog/ will display the following page:

@image{images/example,10cm,}

The @strong{admin} configuration is stored in a subdirectory of the @strong{cgi-bin} directory (CGIDIR
when @strong{Catalog} is installed). It
customizes the administration interface of the catalogs.

The @strong{browse} configuration is stored in a subdirectory of the @strong{cgi-bin} directory. It
customizes the user view of the catalogs.

The resources database is a set of URLs, stored in the @strong{urldemo} table that have the following
structure:

@example
create table urldemo (
  #
  # Table management information 
  #
  rowid int auto_increment not null,
  created datetime not null,
  modified timestamp not null,

  info enum ('active', 'inactive') default 'active',
  url char(128),
  comment char(255),

  unique cdemo1 (rowid)
)
@end example

The @strong{rowid} member and the @strong{cdemo1} index are mandatory. The @strong{url} field
stores the URL of a WEB site, the @strong{comment} field stores a comment that shortly explains the 
purpose of the WEB site, the @strong{created} field is the date of the insertion of the record 
in the database.

The URLs found in the @strong{urldemo} table relate to full text indexing
and searching the WEB. Based on this table we have created three catalogs:

@table @samp
@item urlcatalog
is a thematic tree that classifies the resources found in the @strong{urldemo}
table. This catalog defines a small hierarchical tree containing @strong{/Directory}, @strong{Full text/Conferences}, @strong{Full text/Software} and so on.
The classification is done by associating each record in the @strong{urldemo}
table to a specific category in the thematic tree. This association is 
maintained in an administrative table of the @strong{urlcatalog} and is
@strong{not} contained in the @strong{urldemo} table.

@item urldate
is a chronological catalog. We have chosen to chronologically order the records
of the @strong{urldemo} table according to their creation date 
(@strong{created} field). All what is
needed when creating a chronological catalog is to specify which table to
use and which field in this table contains the date field to consider.
The chronological presentation is inferred from the dates contained in each
record.

@item urlalpha
is an alphabetical catalog. We have chosen to alphabetically order the records
of the @strong{urldemo} table according to the content of the @strong{comment}
field. All what is
needed when creating a alphabetical catalog is to specify which table to
use and which field in this table contains the character field to consider.
The alphabetical presentation is inferred from the strings contained in each
record.

@end table

It must be clearly understood that any number of catalog can be created for
a given table (@strong{urldemo} for instance) with no need to duplicate the
data of this table. The catalogs are maintained using administrative tables
that are not directly related to the table containing the records classified.

The example database created is named @strong{catalog_example} and is loaded with three catalogs
(urlcatalog, urldate and urlalpha) based on the @strong{urldemo} table. The database may be dropped
if you want to get rid of it at a later time with the following MySQL instruction:

@example
drop database catalog_example;
@end example

In short the example is installed in the following files/bases:

@table @samp

@item HTMLDIR/Catalog/index.html
The entry point.

@item CGIDIR/admin/
Catalog administration configuration.

@item CGIDIR/browse/
Catalog user view configuration.

@item catalog_example database
The example database.

@end table

@node Quick tour, Records ordering, Example installed, Catalog management guide
@section Quick tour

Using the example entry point (HTML page located in 
http://www.mymachine.com/Catalog/index.html), you can quickly browse
the example provided. The @code{Control panel} link shows that three catalogs exist, as displayed
in the following figure:

@image{images/examplecontrolpanel,10cm,}

The @strong{urldate} catalog shows the urldemo records in the order in which they have been created 
(created field). The 
@strong{urlalpha} catalog display an alphabetical index of the records in the urldemo table, based on
the comment field. 
The @strong{urlcatalog} catalog classifies the URLs in a thematic tree. If you click on the
@strong{browse} link next to the name of each catalog, you will be able to see what it looks like. When using these links, no interface customization is
active : you see the display using all the default values and templates.
The following figure shows the display of the @strong{/Directory} category
of the @strong{urlcatalog} catalog.

@image{images/examplecbrowse1,10cm,}

You can also click on the @strong{edit} button for the @strong{urlcatalog} catalog to see the
administration interface that allows you to create categories, 
insert records etc.

@image{images/examplecedit1,10cm,}

Going back to the example entry point (HTML page located in 
http://www.mymachine.com/Catalog/index.html), 
you will have access to a customized version of the
@strong{urlcatalog} catalog administration interface thru the link @strong{Edit URL catalog}.
You can compare the display with the non customized version for the @strong{/Directory} category,
as shown in the following figure:

@image{images/examplecedit2,10cm,}

The example entry point (HTML page located in 
http://www.mymachine.com/Catalog/index.html)
then shows links to access the customized user view for the three catalogs
(the @strong{Browse URL catalog (urlcatalog)}, @strong{Chronological history of the URL catalog (urldate)} and @strong{Alphabetical URL catalog (urlalpha)} links).
You can compare them with what you saw when clicking on the @strong{browse} links in the control panel.

The following sections will explain how to configure @strong{Catalog} to achieve these effects. This
is mostly a simple process that requires to modify some template HTML files.

@node Records ordering, Record layout (urlcatalog), Quick tour, Catalog management guide
@section Records ordering

When the @strong{urlcatalog} was created it was bound to the @strong{urldemo} table. In addition,
the order of the @strong{urldemo} records displayed in a given category was set to ascending lexicographic
order on the @strong{comment} field. The following figure shows the complete configuration of the
catalog (you can access it by clicking on the catalog name in the the control panel):

@image{images/exampleurlcatalog,10cm,}

The @strong{urldate} and @strong{urlalpha} catalogs were configured in the same way. 

@node Record layout (urlcatalog), Overriding a template (urlcatalog), Records ordering, Catalog management guide
@section Record layout (urlcatalog)

Our purpose is to understand how the template for the administration
of @strong{urlcatalog} was modified to display the @strong{urldemo}
records in a user friendly way. This is the only customization performed for the administration
but it is a crucial one. Without customization, the records are displayed in this fashion:

@image{images/examplelayout1,12cm,}

We want them to be displayed in this fashion instead:

@image{images/examplelayout,6cm,}

The @strong{cedit.html} template is used to display the current category in the administration interface.
The template files are simple HTML files used by the cgi-bin to display their results. Special markers
are detected and allow the cgi-bin to:

@itemize @bullet

@item display a value 

@item conditionally show a part of the template

@item repeat a part of the template to display lists of values

@end itemize

The @strong{_NAME_} tags (always in uppercase, surrounded by underscores) are replaced by values.
The HTML comments that look like @strong{<!-- start entry -->} and @strong{<!-- end entry -->} define
parts of the template that may be included conditionally or repeated to display a list.

For instance, in the following @strong{cedit.html} template, the part enclosed between 
@strong{<!-- start categories -->} and @strong{<!-- end categories -->} will only be included if
the displayed category has at least one sub category. Otherwise it will be completely omitted.

It is therefore very important to take great care not to remove the HTML comments, unless you
know exactly what your are doing : they are used to display the results of the cgi-bin.

Here is a commented version of the default @strong{cedit.html} template:

@example
<title>Edit category _CATEGORY_</title>

<center><h3><font color=red>_COMMENT_</font></h3></center>

@strong{This is a form to search the catalog}
<center>
<form action=_SCRIPT_ method=POST>
<input type=hidden name=name value=_NAME_>
<input type=hidden name=context value=csearch>
<input type=hidden name=mode value=_CONTEXT_>
<input type=text size=40 name=text value='_TEXT-QUOTED_'>
<input type=submit value='search'><br>
</form>
</center>

@strong{These are buttons to perform actions on the category}
<h3>Edit category _CATEGORY_</h3> 
<a href='_CENTRYINSERT_'><img src=_HTMLPATH_/images/new.gif alt='Insert a new record and link it to this category' border=0></a>
<a href='_CENTRYSELECT_'><img src=_HTMLPATH_/images/link.gif alt='Link an existing record to this category' border=0></a>
<a href='_CATEGORYINSERT_'><img src=_HTMLPATH_/images/open.gif alt='Create a sub category' border=0></a>
<a href='_CATEGORYSYMLINK_'><img src=_HTMLPATH_/images/plus.gif alt='Create a symbolic link to another category' border=0></a>
<a href='_CONTROLPANEL_'><img src=_HTMLPATH_/images/control.gif alt='Control panel' border=0></a>
<p>
<p>
_PATH_
<p>

@strong{This part is only shown if there are sub categories}
<!-- start categories -->
<h3>Sub categories</h3>
<table>
<!-- params 'style' => 'table', 'columns' => 2 -->
<!-- start row --> 
<tr>
<!-- start entry -->
<td> _LINKS_ <a href='_URL_'>_NAME_</a> (_COUNT_) </td>
<!-- end entry -->
</tr>
<!-- end row --> 
</table>
<!-- end categories -->
<p>

@strong{Display the records in this category}
<h3>Records in this category</h3>
<!-- start entry -->
<table border=1><tr><td>_LINKS_</td> _DEFAULTROW_</tr></table>
<p>
<!-- end entry -->

@strong{This part is only shown if there is more than one page of records (page length is 10 records)}
<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

Since we want to change the display of the records, we only have to modify the relevant portion of
the template, that is:

@example
<h3>Records in this category</h3>
<!-- start entry -->
<table border=1><tr><td>_LINKS_</td> _DEFAULTROW_</tr></table>
<p>
<!-- end entry -->
@end example

The @strong{entry} part (delimited by the @strong{<!-- start entry -->} and 
@strong{<!-- end entry -->} HTML comments) will be repeated for each record in the category. 
We want to preserve the @strong{_LINKS_} tag that displays the buttons to perform actions on the record
(remove, unlink and edit). But we want to change @strong{_DEFAULTROW_} to display only the fields
of interest. 
The values of the fields of the @strong{urldemo} table for the displayed record are available with
the following tags : @strong{_URL_}, @strong{_COMMENT_} and @strong{_CREATED_}.
The rationale of the tag substitution when a record is displayed is quite 
simple: each field name of the record is translated to uppercase and 
surrounded by underscores. This substitution is done automatically: there is
no need to explicitly map the field names to tag names. This is very convenient
when you add a new field to the records: the new fields can be displayed
by including a new tag matching the field name in the template file.

In addition, a variation of the value is
available by appending the @strong{-QUOTED} string to the field name. This variation replaces
HTML reserved characters such as quote (@strong{'}) or double quote (@strong{"}) by the appropriate
HTML elements. This is useful to include a value in quotes, for instance.
Here is the modified template part:

@example
<!-- start entry -->
<table><tr><td>_LINKS_</td> 
<td>
<dt><a href='_URL-QUOTED_'>_COMMENT_</a>
<dd>
<a href='_URL-QUOTED_'>_URL_</a>
<dd>
<i><font size=-1>Created _CREATED_</font></i><br>
</td></tr></table>
<p>
<!-- end entry -->
@end example

Note that we have used _URL-QUOTED_ instead of _URL_ in the @strong{href}
instruction.
The record layout is now exactly what we expect.

@node Overriding a template (urlcatalog), Customizing user view (urlcatalog), Record layout (urlcatalog), Catalog management guide
@section Overriding a template (urlcatalog)

We have modified the @strong{cedit.html} template and now we would like @strong{Catalog}
to use it instead of
the default template. The simplest method would be to create a file named @strong{cedit.html} in 
the cgi-bin/admin directory. The default templates used by @strong{Catalog} are included in the code
of the application, therefore you will not find a @strong{cedit.html} file anywhere. You will have
to create it, copying it from the example or from this documentation. When the @strong{Catalog} 
cgi-bin executes, it looks for templates in it's current working directory which is the cgi-bin
directory, at least if you're using Apache.

This method is not suitable for us because we want (for the sake of the demonstration) to keep
the default @strong{cedit.html} and add a new one that would be activated only if we ask for it. This is
achieved very simply by the use of the @strong{style} cgi-bin parameter and the @strong{templates.conf}
configuration file.

What happens if you call the cgi-bin with an additional argument @strong{style=urlcatalog} (you
will see that the link @strong{Edit URL catalog} in the example HTML entry point has this parameter) ? 
When the cgi-bin looks for a specific template (@strong{cedit.html} in our case), it first searches the
@strong{templates.conf} file for a renaming instruction. For instance, in the @strong{template.conf}
file of the example (CGIDIR/admin/templates.conf) you can see these lines:

@example
	#
	# Catalog customization
	#
        urlcatalog
                #       
                # Catalog editing 
                #
                cedit.html = urlcatalog_cedit.html
                #       
                # Search results
                #
                csearch.html = urlcatalog_csearch.html
        end
@end example

This must be understood as : if the @strong{style} is @strong{urlcatalog} then use 
@strong{urlcatalog_cedit.html} template instead of the default @strong{cedit.html}. 
We should therefore create a @strong{urlcatalog_cedit.html} file and copy the modified 
template HTML code in it. 

In short, the modified @strong{cedit.html} template is put in the @strong{urlcatalog_cedit.html}
file and @strong{cedit.html} is mapped to @strong{urlcatalog_cedit.html} for the @strong{urlcatalog}
style in the @strong{templates.conf} file.

We have covered all the actions necessary to customize the administration interface of urlcatalog as
shown in the example. We will now explain how to customize the user view
of the catalog.

@node Customizing user view (urlcatalog), Customizing search results (urlcatalog), Overriding a template (urlcatalog), Catalog management guide
@section Customizing user view (urlcatalog)

The basic concepts of template customization have been covered in the previous sections, while 
explaining how the administration interface was modified to show a better display of the records.
We will now explain how the user view of the catalog @strong{urlcatalog} was modified to display as
shown in the following figures:

@itemize @bullet
@item
The root of the catalog.

@image{images/examplecbrowse2,10cm,}

@item 
The display of a category containing records.

@image{images/examplecbrowse3,10cm,}

@end itemize

There are two differences between the administration interface for at thematic catalog and its
user view:

@itemize @bullet
@item
The top level category (root category) is displayed using a separate template.
@item
The editing buttons are not available.
@end itemize

The display of the top level category uses the @strong{cbrowse_root.html} template and all
other categories are displayed using the @strong{cbrowse.html} template. This was done to allow
a different display for the top level category because it is often needed. The default
@strong{cbrowse_root.html} and @strong{cbrowse.html} are almost identical.

Here is the default @strong{cbrowse_root.html}:

@example
<title>Root</title>

<center>
<form action=_SCRIPT_ method=POST>
<input type=hidden name=name value=_NAME_>
<input type=hidden name=context value=csearch>
<input type=hidden name=mode value=_CONTEXT_>
<input type=text size=40 name=text value='_TEXT-QUOTED_'>
<input type=submit value='search'><br>
</form>
</center>

<h3>Root</h3>

<!-- start categories -->
<h3>Sub categories</h3>
<ul>
<!-- start entry -->
<li> <a href='_URL_'>_NAME_</a> (_COUNT_)
<!-- end entry -->
</ul>
<!-- end categories -->
<p>
<!-- start entry -->
<p> <table border=1><tr>_DEFAULTROW_<tr></table>
<!-- end entry -->

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

In the example database we know that no records will be displayed at the top level because we will never insert
a record in the top level category. Therefore we can remove the part of the template used to 
display records (starting from the @strong{<!-- end categories -->} comment
up to the end of the template). 

Instead of displaying the categories using a bullet list, we want to display them as a two columns
table. We want

@image{images/examplelayout2,5cm,}

instead of

@image{images/examplelayout3,4cm,}

We will have to modify the part of the template that is between @strong{<!-- start categories -->}
and @strong{<!-- end categories -->}. Within this part there is a nested part delimited by 
@strong{<!-- start entry -->} and @strong{<!-- end entry -->} that is repeated for each sub category
of the top level category (in the same way the records are displayed). 

Obviously this does not allow us to display a two columns table. We have to substitute the 
@strong{entry} part with something else. Fortunately, the @strong{row} part is precisely designed
for this purpose. Here is the final result:

@example
<body bgcolor=#ffffff>
<title>The Senga Resources Catalog</title>

<center><h3>The Senga Resources Catalog</h3></center>
<hr>
<center>
<form action=_SCRIPT_ method=POST>
<input type=hidden name=name value=_NAME_>
<input type=hidden name=context value=csearch>
<input type=hidden name=mode value=_CONTEXT_>
<input type=text size=40 name=text value='_TEXT-QUOTED_'>
<input type=submit value='search'><br>
</form>
<hr>

<!-- start categories -->
<table>
<!-- params 'style' => 'table', 'columns' => 2 -->
<!-- start row --> 
<tr>
<!-- start entry -->
<td> <b><a href='_URL_'>_NAME_</a></b> (_COUNT_) </td>
<!-- end entry -->
</tr>
<!-- end row --> 
</table>
<!-- end categories -->
</center>
@end example

We have substituted the @strong{<ul>} with a @strong{<table>} to start the table. The comment
@strong{<!-- params 'style' => 'table', 'columns' => 2 -->} instructs the display mechanism that
we will use a table instead of a list (@strong{'style' => 'table'}) and that this table will have
two columns (@strong{'columns' => 2}). When this declaration is present we can wrap the 
@strong{entry} part with a @strong{row} part that will only be repeated every two columns. We are finished with the @strong{cbrowse_root.html} template.

Now we want to customize the @strong{cbrowse.html} template to display the categories in the
same fashion and to display the records as defined when customizing the administration interface
in the previous sections. The only noticeable detail is that the records are not displayed in a 
table but in a @strong{<dl>}. The table was needed to correctly display the actions buttons in the administration interface but
is not needed here because we do not show them. Here is the modified 
@strong{cbrowse.html} template:

@example
<body bgcolor=#ffffff>
<title>_CATEGORY_</title>

<center>
<b>Category</b> _PATH_
<p>
<form action=_SCRIPT_ method=POST>
<input type=hidden name=name value=_NAME_>
<input type=hidden name=context value=csearch>
<input type=hidden name=mode value=_CONTEXT_>
<input type=text size=40 name=text value='_TEXT-QUOTED_'>
<input type=submit value='search'><br>
</form>
</center>


<!-- start categories -->
<center>
<table>
<!-- params 'style' => 'table', 'columns' => 2 -->
<!-- start row --> 
<tr>
<!-- start entry -->
<td> <b><a href='_URL_'>_NAME_</a></b> (_COUNT_) </td>
<!-- end entry -->
</tr>
<!-- end row --> 
</table>
</center>
<!-- end categories -->

<dl>
<!-- start entry -->
<dt><a href='_URL-QUOTED_'>_COMMENT_</a>
<dd>
<a href='_URL-QUOTED_'>_URL_</a>
<dd>
<i><font size=-1>Created _CREATED_</font></i><br>
<p>
<!-- end entry -->
</dl>

<center>
<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
</center>
@end example

Since we want to preserve the default display we will use the @strong{templates.conf} file to
re-map the @strong{cbrowse_root.html} and @strong{cbrowse.html} default templates when the 
style @strong{urlcatalog} is activated. We will modify the @strong{templates.conf} file located
in CGIDIR/browse/templates.conf (instead of CGIDIR/admin/templates.conf for the administration
interface) as follows:

@example
#
# Templates system configuration
#
style
        #
        # Catalog customization
        #
        urlcatalog
                #       
                # Search results
                #
                csearch.html = urlcatalog_csearch.html
                #       
                # Root of Catalog browsing
                #
                cbrowse_root.html = urlcatalog_cbrowse_root.html
                #       
                # Pages of Catalog browsing
                #
                cbrowse.html = urlcatalog_cbrowse.html
        end
end
@end example

@node Customizing search results (urlcatalog), Customizing chronological browsing (urldate), Customizing user view (urlcatalog), Catalog management guide
@section Customizing search results (urlcatalog)

Now that the browsing interface for @strong{urlcatalog} is customized, we still have to customize the
search result display so that the records are displayed in the same way. The default template 
used to display the search results is @strong{csearch.html} and contains:

@example
<title>Search results for _TEXT_</title>

<center>
<form action=_SCRIPT_ method=POST>
_HIDDEN_
<input type=text size=40 name=text value='_TEXT-QUOTED_'>
<input type=submit value='search'><br>
_WHAT-MENU_
</form>
</center>
<!-- start categories -->
<center>Categories matching <b>_TEXT_</b> (_COUNT_)</center>
<ul>
<!-- start entry -->
<li> <a href=_URL_>_PATHNAME_</a>
<!-- end entry -->
</ul>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
<!-- end categories -->
<!-- start nocategories -->
<center>No category matches the search criterion</center>
<!-- end nocategories -->

<!-- start records -->

<center>Records matching <b>_TEXT_</b> (_COUNT_)</center>

<table border=1>
<!-- start entry -->

<!-- start category -->
<tr><td colspan=20><a href=_URL_>_PATHNAME_</a></td></tr>
<!-- end category -->

<tr>_DEFAULTROW_</tr>
<!-- end entry --> 
</table>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
<!-- end records -->
<!-- start norecords -->
<center>No record matches the search criterion</center>
<!-- end norecords -->
@end example

This template is hairy because it contains many alternatives that
define the HTML code to display:

@itemize @bullet
@item 
if categories match the search criterion (categories part)
@item
if we only want categories and no categories match the search criterion (nocategories part)
@item
if records match the search criterion (records part)
@item 
if no categories and no records match the search criterion (norecords part)
@end itemize

Assuming that we search for records in the example database, the default
display looks like this:

@image{images/examplecsearch1,10cm,}

To customize the records display we only have to change the @strong{records} part to
duplicate what was done in the @strong{cbrowse.html} template. You will notice that the
@strong{entry} part have a sub part named @strong{category}:

@example
<!-- start records -->

<center>Records matching <b>_TEXT_</b> (_COUNT_)</center>

<dl>
<!-- start entry -->

@strong{Sub part of entry that only shows once for a given category}
<!-- start category -->
<p>
<dt><b>Category</b> <a href=_URL_>_PATHNAME_</a>
<!-- end category -->
<p>
<dt><a href='_URL-QUOTED_'>_COMMENT_</a>
<dd>
<a href='_URL-QUOTED_'>_URL_</a>
<dd>
<i><font size=-1>Created _CREATED_</font></i><br>
<!-- end entry --> 
</dl>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
<!-- end records -->
@end example

This subpart must @strong{always} be in the @strong{entry} part. It will be displayed to show
the category of the displayed record each time the category changes. Since the search results
are sorted to group the records in the same category together, this will prevent showing the category
name multiple times.

To continue with the renaming scheme used in the previous section we re-map @strong{csearch.html}
into @strong{urlcatalog_csearch.html} in the @strong{templates.conf} file.

@example
#
# Templates system configuration
#
style
        #
        # Catalog customization
        #
        urlcatalog
                #       
                # Search results
                #
                csearch.html = urlcatalog_csearch.html
                #       
                # Root of Catalog browsing
                #
                cbrowse_root.html = urlcatalog_cbrowse_root.html
                #       
                # Pages of Catalog browsing
                #
                cbrowse.html = urlcatalog_cbrowse.html
        end
end
@end example

The search results when searching for @strong{www} is now:

@image{images/examplecsearch2,10cm,}

At this point we have covered all the operations needed to customize the user view of the 
@strong{urlcatalog} thematic catalog as shown when clicking on the 
@strong{Browse URL catalog (urlcatalog)} link in the example HTML entry point. By defining a new
@strong{style} you could create a new display. All we needed to implement this customization are
four files : templates.conf, urlcatalog_csearch.html, urlcatalog_cbrowse_root.html and 
urlcatalog_cbrowse.html.

@node Customizing chronological browsing (urldate), Customizing alphabetical browsing (urlalpha), Customizing search results (urlcatalog), Catalog management guide
@section Customizing chronological browsing (urldate)

The @strong{urldate} catalog displays the entries of the table @strong{urldemo}
in chronological order. Using the @strong{browse} link in the control panel,
you will see the following screen:

@image{images/examplecdate1,10cm,}

The default display of a chronologically ordered catalog contains a calendar.
Only the days for which at least a record exists are shown. The records 
themselves are shown in the last part of the display. The years, months and
days of the calendar are hypertext links that will only display the 
corresponding year, month or day.

The template used is @strong{cdate_default.html}. It contains two logical 
parts : the display of the calendar and the display of the records. 

@example
<html>
<body bgcolor=#ffffff>
<title>Date catalog</title>
@strong{Display the calendar}
<!-- start years -->
  <a href=_YEARLINK_>_YEARFORMATED_</a> (_COUNT_)

  <blockquote>
  <!-- start months -->
    <!-- params format => '%M' -->
    <a href=_MONTHLINK_>_MONTHFORMATED_</a> (_COUNT_)

    <ul>
    <!-- start days -->
      <!-- params format => '%W, %d' -->
      <li> <a href=_DAYLINK_>_DAYFORMATED_</a> (_COUNT_)
    <!-- end days -->
    </ul>

  <!-- end months -->
  </blockquote>

<!-- end years -->

@strong{Display the records}
<!-- start records -->
Records
<!-- start entry -->
<p> <table border=1><tr>_DEFAULTROW_<tr></table>
<!-- end entry -->

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->

<!-- end records -->
</html>
@end example

The part of the template that displays the records is identical to 
the @strong{cbrowse.html} or @strong{csearch.html} templates. It is 
wrapped in the @strong{records} part. If the @strong{records} part is
omitted, only the calendar will be displayed. 

The part of the template that displays the calendar contains three
nested parts : @strong{days} is included in @strong{months}, itself 
included in @strong{years}. If the chronological display is required
without specifying a specific time interval, all the records are taken
in account. Thru the use of the @strong{date} cgi-bin parameter, however, it is
possible to require that the cgi-bin only displays a given time interval.
For instance, if @strong{date} is set to @code{1999}, it will only 
consider the records of year 1999. If the @strong{date} is set to @code{199902}
it will only consider the records of February 1999. 
If the @strong{date} is set to @code{19990219}
it will only consider the records of February, 19 1999. Here is a display
for this specific day:

@image{images/examplecdate2,10cm,}

We could customize the record part and keep the calendar in this format. 
This is the simple solution if you're in a hurry. To further demonstrate
the customization of the chronological display we will show how to 
configure a different display according to the time interval. We want 
a different display when the time interval is:

@itemize @bullet
@item
unbounded (cdate_default.html).

@image{images/examplecdate3,10cm,}

@item
a specific year (cdate_year.html).

@image{images/examplecdate4,10cm,}

@item
a specific month (cdate_month.html).

@image{images/examplecdate5,10cm,}

@item
a specific day (cdate_day.html).

@image{images/examplecdate6,10cm,}

@end itemize

As you can see on the figures above, the records are only displayed when
the time interval is limited to a specific day. In all other cases only
the calendar is shown. 
If the time interval is not bounded, only the years are displayed.
If the time interval is limited to a specific year, only the
months of the year are displayed.
If the time interval is limited to a specific month, only the
days of this month are displayed.
On top of the display, hypertext links allow to widen the time interval.

The first thing to understand is how we differentiate the templates used.
By default only @strong{cdate_default.html} is used but we want to use
four different templates for unbounded, year, month and day. This is 
achieve by using the @strong{template} cgi-bin parameter. For instance,
if the chronological display is called with

@example
template=year
@end example

then it will use the template @strong{cdate_year.html} instead of 
@strong{cdate_default.html}.

Let's start with the customization of @strong{cdate_default.html}.
Here is the customized template:

@example
<html>
<body bgcolor=#ffffff>
<title>Chronological history of the URL catalog</title>
<center><h3>Chronological history of the URL catalog</h3></center>
<ul>
<!-- start years -->
<li>  <a href=_YEARLINK_&template=year>_YEARFORMATED_</a> (_COUNT_)
<!-- end years -->
</ul>
</html>
@end example

The @strong{records} part has been removed because we don't want to 
display them. The @strong{months} and @strong{days} parts of the @strong{years}
part have been removed because we don't want to go into details in this 
calendar. At this point the customization is really simple since we only
had to remove parts to get a list of years. Each year is associated
with a hypertext link (@strong{_YEARLINK_}) that leads to the chronological
display limited to the current year. We have appended the 
@strong{&template=year} parameter to this tag so that the 
@strong{cdate_year.html} is used instead of @strong{cdate_default.html}. 

Let's now configure the @strong{cdate_year.html} template. Here is the
customized template:

@example
<html>
<body bgcolor=#ffffff>

<!-- start years -->
<title>URL catalog in _YEARFORMATED_</title>
<center>
[ <a href=_SCRIPT_?name=urldate&context=cbrowse>Show all years</a> ] 
<h3>URL catalog in _YEARFORMATED_</h3>
</center>

  <ul>
  <!-- start months -->
    <!-- params format => '%M' -->
    <li> <a href=_MONTHLINK_&template=month>_MONTHFORMATED_</a> (_COUNT_)

  <!-- end months -->
  </ul>

<!-- end years -->
</html>
@end example

As for @strong{cdate_default.html}, we have removed the parts that are
not wanted : @strong{records} and @strong{days} since we only want to
show the months of the year. 
In order to show the current year in the title we had to move the
title (@strong{<title>}) inside the @strong{years} part. This is necessary
because the @strong{_YEARFORMATED_} is only substituted in the 
@strong{years} part. Since we know that this template will only be used
for a specific year, there is not risk that the title be repeated more
than once. 

In the @strong{months} part we use the same method as in 
@strong{cdate_default.html} to force the usage of the 
@strong{cdate_month.html} template when following the hypertext link to
a specific month : we append @strong{&template=month}. 

One more trick is used to control the format of the 
@strong{_MONTHFORMATED_} tag.
By default @strong{_MONTHFORMATED_} 
is substituted with the English name of the month
followed by the year in four digit format (February 1999, for instance). 
However, since we clearly show the year in the title there is no need to
repeat it for every month. The @strong{<!-- params format => '%M' -->} comment
in the @strong{months} part 
controls the format of the @strong{_MONTHFORMATED_} tag. The string 
in single quotes is a MySQL date format specification (more 
information may be found in the MySQL @strong{date_format} function 
documentation). The @strong{%M} says that we only want the name of the
month. The same format control method applies to the @strong{_YEARFORMATED_} 
and @strong{_DAYFORMATED_} tags.

Let's now configure the @strong{cdate_month.html} template. Here is the
customized template:

@example
<html>
<body bgcolor=#ffffff>
<!-- start years -->
<center>
  [ <a href=_SCRIPT_?name=urldate&context=cbrowse>Show all years</a> | 
  <a href=_YEARLINK_&template=year>Months of _YEARFORMATED_</a> ]

  <!-- start months -->
    <!-- params format => '%M %Y' -->

<h3>URL catalog in _MONTHFORMATED_</h3>
<title>URL catalog in _MONTHFORMATED_</title>
</center>
    <ul>
    <!-- start days -->
      <!-- params format => '%W, %d' -->
      <li> <a href=_DAYLINK_&template=day>_DAYFORMATED_</a> (_COUNT_)
    <!-- end days -->
    </ul>

  <!-- end months -->

<!-- end years -->

</html>
@end example

There is no new concept in this template. The title (@strong{<title>}) has
been moved to the @strong{months} part to show the current month using
@strong{_MONTHFORMATED_} because this tag is only substituted in the 
@strong{months} part. It's a bit strange to put the title so far in the
HTML code but that's the only way to do it.

The list of links on top of the page now contain a link to display all the
months of the year.

Lastly, the @strong{cdate_day.html} template is built as follows:

@example
<html>
<body bgcolor=#ffffff>
<!-- start years -->
<center>
  [ <a href=_SCRIPT_?name=urldate&context=cbrowse>Show all years</a> | 
  <a href=_YEARLINK_&template=year>Months of _YEARFORMATED_</a> |

  <!-- start months -->
    <!-- params format => '%M %Y' -->
  <a href=_MONTHLINK_&template=month>Days of _MONTHFORMATED_</a> ]

    <!-- start days -->
      <!-- params format => '%W, %d %M %Y' -->
<h3>URL catalog _DAYFORMATED_</h3>
<title>URL catalog _DAYFORMATED_</title>
</center>
    <!-- end days -->

  <!-- end months -->

<!-- end years -->

<!-- start records -->
<dl>
<!-- start entry -->
<dt><a href='_URL-QUOTED_'>_COMMENT_</a>
<dd>
<a href='_URL-QUOTED_'>_URL_</a>
<dd>
<i><font size=-1>Created _CREATED_</font></i><br>
<p>
<!-- end entry -->
</dl>

<!-- start pager -->
<center>
Number of pages _MAXPAGES_
<p>
_PAGES_
</center>
<!-- end pager -->

<!-- end records -->

</html>
@end example

We now see the @strong{records} part which looks exactly the same as in
the @strong{cbrowse.html} template.

We are finished with the customization of the chronological catalog. This
method allows you to exactly controls the display while retaining a very
simple default method.

@node Customizing alphabetical browsing (urlalpha), More customization, Customizing chronological browsing (urldate), Catalog management guide
@section Customizing alphabetical browsing (urlalpha)

The @strong{urlalpha} catalog displays the entries
of the table @strong{urldemo}
in alphabetical order, based on the @strong{comment} field. Using the @strong{browse} link in the control panel,
you will see the following screen:

@image{images/examplecalpha1,10cm,}

Each letter and digit is shown. If there is at least one record for which
the comment field starts with a specific letter (case insensitive), the
letter becomes an hypertext link and the number of records is appended. 
If there is no record for which the comment field starts with a specific
letter, the letter alone is shown.

When you click on a letter, the following screen is shown:

@image{images/examplecalpha2,10cm,}

Two templates are used : @strong{calpha_root.html} for the first
page and @strong{calpha.html} to display a specific letter.

The default @strong{calpha_root.html} template is as follows:

@example
<title>Alphabetical Navigation</title>

<h3>Alphabetical Navigation</h3>

_A_ _B_ _C_ _D_ _E_ _F_ _G_ _H_ _I_ _J_ _K_ _L_ <p>
_M_ _N_ _O_ _P_ _Q_ _R_ _S_ _T_ _U_ _V_ _W_ _X_ <p>
_Y_ _Z_ _0_ _1_ _2_ _3_ _4_ _5_ _6_ _7_ _8_ _9_ <p>
@end example

What we want is a nice GIF for each letter instead of the ugly text
and that the GIF files used be different (grayed) if there are no
records for a specific letter. In short we want this:

@image{images/examplecalpha3,10cm,}

The modified template (@strong{calpha_root.html}) is quite long and we only
show a few relevant lines:

@example
<body bgcolor=#ffffff>
<title>Alphabetical URL catalog</title>

<h3>Alphabetical URL catalog</h3>

<table border=1>
<tr>
 <td>
  <a href=_AURL_>
   <img src=_HTMLPATH_/images/letter_ALETTER_.gif border=0>
  </a>
  <font size=-1>_ACOUNT_</font>
 </td>
 <td>
  <a href=_BURL_>
   <img src=_HTMLPATH_/images/letter_BLETTER_.gif border=0>
  </a>
  <font size=-1>_BCOUNT_</font>
 </td>
                 @strong{.}
                 @strong{.}
                 @strong{.}
</tr>
</table>
@end example

We have done two things : put the letters in a table and expand the
default @strong{_A_} style tags. By default these tags are replaced by an
hypertext link if appropriate. Since we want to show images, we have
to control the expansion of the hypertext link. For this purpose we have
three tags:

@table @samp
@item _AURL_
is the URL that shows the records for letter A.

@item _ACOUNT_ 
is the number of records for the letter A.

@item _ALETTER_
is either the letter A in lower case (@strong{a}), if there is at least
one record for which the @strong{comment} field starts with an A, or the
string @strong{a0} if there are no records. This tag allows us to dynamically
build a different GIF file name according to the population associated with
the letter.
The GIF file named @strong{lettera.gif} @image{images/lettera,,} is shown if
there are records and the GIF file named @strong{lettera0.gif} @image{images/lettera0,,} is shown if there are no records.
@end table

The lines specifying the display for one letter must be duplicated for each
letter. Note that we use the @strong{_HTMLPATH_} tag to locate the 
images installed by @strong{Catalog}. If you are using your own GIF file you
will not need this tag.

The customization of the page displaying the records for a specific letter
(@strong{calpha.html}) is much simpler. The default template is as follows:

@example
<title>Alphabetical Navigation _LETTER_</title>

<h3>Alphabetical Navigation _LETTER_</h3>

<table border=1>
<!-- start entry -->
<tr>_DEFAULTROW_</tr>
<!-- end entry --> 
</table>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

It contains a part that should now be familiar (@strong{entry}) to display
the records. We modify it to be compliant with the templates created so far:

@example
<body bgcolor=#ffffff>
<title>URL catalog letter _LETTER_</title>

<h3>URL catalog letter _LETTER_</h3>

<dl>
<!-- start entry -->
<dt><a href='_URL-QUOTED_'>_COMMENT_</a>
<dd>
<a href='_URL-QUOTED_'>_URL_</a>
<dd>
<i><font size=-1>Created _CREATED_</font></i><br>
<p>
<!-- end entry -->
</dl>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@image{images/examplecalpha4,10cm,}

Note that the @strong{_LETTER_} tag is substituted with the letter being displayed,
in uppercase. It may be used to display a GIF file, for instance.

@node More customization,  , Customizing alphabetical browsing (urlalpha), Catalog management guide
@section More customization

In this chapter we have focused on the definition of the catalogs and the
customization of the user interface. We have only shown how to customize
the record layout for the administration of a thematic catalog. You will
find that the reference chapters list all the templates used in by
the administration interface of @strong{Catalog}. You can modify all of them
to fit your needs.

@node Full text search, Catalog tables, Catalog management guide, Top
@chapter Full text search

@menu
* Default full text::           Default full text
* Real full text::              Real full text
@end menu

@node Default full text, Real full text, Full text search, Full text search
@section Default full text

The search mechanism of @strong{Catalog} is implemented using the @strong{regexp} operator
of MySQL. For instance, when searching for the word @code{foobar}, the regexp used will be:

@example
REGEXP '[[:<:]][fF][oO][oO][bB][aA][rR][[:>:]]'
@end example

This basically means that only the isolated @code{foobar} word will be found and not the
word @code{foobarnitz}, @xref{Catalog search (csearch),,@code{Catalog search (csearch)}}. 

This method can be really slow if the catalog contains a lot of data. We are working on this.

If the encoding of the catalog is not ISO-8859-* a the query is taken to
be only one word and is searched using the SQL truncation operators, 
@xref{Catalog configuration file, ,@code{Catalog configuration file}}. 

@example
like '%word1 word2%'
@end example

@node Real full text,  , Default full text, Full text search
@section Real full text

An automatic mechanism builds a full text index for every record in the
SQL database. The full text index contains enough information to find
which record of which table contains a specific word, @xref{Hook Fulcrum configuration file, ,@code{Hook Fulcrum configuration file}}.

This mechanism currently specific to the Fulcrum full text engine and quite complex
to tune.

@node Catalog tables, Configuration files, Full text search, Top
@chapter Catalog tables

@menu
* Catalog tables introduction::  Catalog tables introduction
* catalog::                     Catalog tables introduction
* catalog_category_<name>::     catalog_category_<name>
* catalog_category2category_<name>::  catalog_category2category_<name>
* catalog_entry2category_<name>::  catalog_entry2category_<name>
* catalog_path_<name>::         catalog_path_<name>
* catalog_alpha_<name>::        catalog_alpha_<name>
* catalog_date_<name>::         catalog_date_<name>
@end menu

@node Catalog tables introduction, catalog, Catalog tables, Catalog tables
@section Catalog tables introduction

The @strong{catalog} table has a record for every existing catalog. The
other tables have names that end with the name of the catalog 
(@strong{<name>}).

None of these tables have to be created explicitly. They are described here
to facilitate the understanding of the mechanism behind @strong{Catalog}.

The @strong{externalid} that appear in each table is designed to ease
the importation/exportation of the catalog structure. This field can
contain a unique identifier used in another catalog system.

@node catalog, catalog_category_<name>, Catalog tables introduction, Catalog tables
@section catalog

@cindex catalog table
@cindex table catalog

Describe all the existing catalogs.

@example
create table catalog (
  #
  # Table management information 
  #
  rowid int autoincrement,
  created datetime not null,
  modified timestamp not null,

  #
  # Name of the catalog
  #
  name varchar(32) not null,
  #
  # Name of the table whose records are cataloged
  #
  tablename varchar(60) not null,
  #
  # Navigation scheme
  #
  navigation enum ('alpha', 'theme', 'date') default 'theme',
  #
  # State information
  #
  info set ('hideempty'),
  #
  # (alpha, date only) last update time
  #
  updated datetime,
  #
  # Order clause
  #
  corder varchar(128),
  #
  # Where clause
  #
  cwhere varchar(128),
  #
  # (alpha, date only) name of the field for sorting
  #
  fieldname varchar(60),
  #
  # (theme only) rowid of the root in catalog_category_<name>
  #
  root int not null,
  #
  # (theme only) full path name of the location to dump pages
  #
  dump varchar(255),
  #
  # (theme only) the location from which the dumped pages will be accessed
  #
  dumplocation varchar(255),

  unique catalog1 (rowid),
  unique catalog2 (name)
)
@end example

@node catalog_category_<name>, catalog_category2category_<name>, catalog, Catalog tables
@section catalog_category_<name>

@cindex catalog_category_<name> table
@cindex table catalog_category_<name>

Describe a category (theme only).

@example
create table catalog_category_<name> (
  #
  # Table management information 
  #
  rowid int autoincrement
  created datetime not null,
  modified timestamp not null,

  #
  # State information
  #
  info set ('root'),
  #
  # Full name of the category
  #
  name varchar(255) not null,
  #
  # Total number of records in this category and bellow
  #
  count int default 0,
  #
  # External identifier to synchronize with alien catalogs
  #
  externalid varchar(32) not null default '',
)
@end example

@node catalog_category2category_<name>, catalog_entry2category_<name>, catalog_category_<name>, Catalog tables
@section catalog_category2category_<name>

@cindex catalog_category2category_<name> table
@cindex table catalog_category2category_<name>

Link two categories (theme only).

@example
create table catalog_category2category_<name> (
  #
  # Table management information 
  #
  rowid int autoincrement,
  created datetime not null,
  modified timestamp not null,

  #
  # State information
  #
  info set ('hidden', 'symlink'),
  #
  # Rowid of father
  #
  up int not null,
  #
  # Rowid of child
  #
  down int not null,
  #
  # External identifier to synchronize with alien catalogs
  #
  externalid varchar(32) not null default '',
)
@end example

@node catalog_entry2category_<name>, catalog_path_<name>, catalog_category2category_<name>, Catalog tables
@section catalog_entry2category_<name>

@cindex catalog_entry2category_<name> table
@cindex table catalog_entry2category_<name>

Link a record from the cataloged table with a category (theme only).

@example
create table catalog_entry2category_<name> (
  #
  # Table management information 
  #
  created datetime not null,
  modified timestamp not null,

  #
  # State information
  #
  info set ('hidden'),
  #
  # Rowid of the record from cataloged table
  #
  row int not null,
  #
  # Rowid of the category
  #
  category int not null,
  #
  # External identifier to synchronize with alien catalogs
  #
  externalid varchar(32) not null default '',
)
@end example

@node catalog_path_<name>, catalog_alpha_<name>, catalog_entry2category_<name>, Catalog tables
@section catalog_path_<name>

@cindex catalog_path_<name> table
@cindex table catalog_path_<name>

Maps category id to category path (theme only).

@example
create table catalog_path_<name> (
  #
  # Full path name of the category
  #
  pathname text not null,
  #
  # MD5 key of the path name
  #
  md5 char(32) not null,
  #
  # Full path name translated to ids
  #
  path varchar(128) not null,
  #
  # Id of the last component
  #
  id int not null,

  unique catalog_path_NAME1 (md5),
  unique catalog_path_NAME2 (path),
  unique catalog_path_NAME3 (id)
)
@end example

@node catalog_alpha_<name>, catalog_date_<name>, catalog_path_<name>, Catalog tables
@section catalog_alpha_<name>

@cindex catalog_alpha_<name> table
@cindex table catalog_alpha_<name>

Count information for each letter (alpha only).

@example
create table catalog_alpha_NAME (
  #
  # Table management information 
  #
  rowid int autoincrement,
  created datetime not null,
  modified timestamp not null,

  #
  # The letter
  #
  letter char(1) not null,
  #
  # Count of records of the cataloged table have
  # a field starting with this letter.
  #
  count int default 0,
)
@end example

@node catalog_date_<name>,  , catalog_alpha_<name>, Catalog tables
@section catalog_date_<name>

@cindex catalog_date_<name> table
@cindex table catalog_date_<name>

Count information for each period (date only).

@example
create table catalog_date_NAME (
  #
  # Table management information 
  #
  rowid int autoincrement,

  #
  # The date interval
  #
  tag char(8) not null,
  #
  # Count of records of the cataloged table have
  # a field starting with this letter.
  #
  count int default 0,

  unique catalog_date_NAME1 (rowid),
  unique catalog_date_NAME2 (tag)
)
@end example

@node Configuration files, External representation, Catalog tables, Top
@chapter Configuration files

The @strong{Catalog} software is made of separate Perl packages. 
All these packages have a configuration 
file that is read at startup time. They are found
in the current working directory if no @code{CONFIG_DIR} environment
variable is set,
@xref{Environment variables, , @code{Environment variables}}.

The instructions found in the configuration files alter the behavior
of @strong{Catalog}. For instance, they can be used to change the display
of an HTML page.
The general structure of a configuration file is an ASCII file where
lines beginning with a dash (@strong{#}) are ignored as well as empty 
lines. 

A configuration instruction has the following form

@example
keyword = value
@end example

The keyword can contain alpha-numerical characters, underscore (@strong{_}) and
dash (@strong{-}). The value can contain any character except newline or 
carriage return. There is no way to specify a multi-line value for a given 
keyword. 

Here is a simple example of a configuration file:

@example
#
# Name of the database to connect. 
#
base = test
@end example

Configurations instructions may be nested. If a keyword is not followed by
an equal sign, it is considered to be the start of a sub section of the
configuration file. The end of a sub section is marked by the keyword
@strong{end}, alone on a line. Here is a simple example:

@example
#
# Parameters for set and enum built from tables instead of builtin types
#
dictionaries
        name = mydict
end
@end example

Nesting can be recursive. Note that the leading white spaces are cosmetic
only and are ignored by the configuration file parser. Here is an example
of recursively nested instructions:

@example
#
# Parameters for set and enum built from tables instead of builtin types
#
dictionaries
        name = mydict
        mydict
                where = valid = 'yes'
        end
end
@end example

The white space characters surrounding the keyword and the value are 
always ignored. This means that there is no way to specify a value that
would contain leading or trailing white space.

In the following chapters you will find a complete description of the 
configuration files available in @strong{Catalog}. 

@menu
* Catalog configuration file::  Catalog configuration file
* MySQL configuration file::    MySQL configuration file
* CGI configuration file::      CGI configuration file
* Install configuration file::  Install configuration file
* SQL editor configuration file::  SQL editor configuration file
* Template configuration file::  Template configuration file
* Hook Fulcrum configuration file::  Hook Fulcrum configuration file
@end menu

@node Catalog configuration file, MySQL configuration file, Configuration files, Configuration files
@section Catalog configuration file

@cindex Catalog configuration file
@cindex configuration file, Catalog
@cindex package Catalog
@cindex Catalog package

Used by the Catalog package (Catalog.pm). It influences the global behavior
of @strong{Catalog}.

@table @samp

@item path_separator (optional, default @strong{/})
The string that separates path components of the @strong{_PATH_}
tag in the navigation pages of the catalog, 
@xref{cedit.html,,@code{cedit.html}}.

@item path_root_label (optional, default @strong{Root})
Label shown for the root of the path shown as the @strong{_PATH_}
tag in the navigation pages of the catalog, 
@xref{cedit.html,,@code{cedit.html}}.

@item pathcontext_params (optional)
Parameters that must be used in the @strong{pathcontext} context, 
@xref{Intuitive navigation (pathcontext),,@code{Intuitive navigation (pathcontext)}}.
If set it must contain the @strong{name} parameter that specifies the name of the
catalog to display. 

@item search (optional, nested)
Specifies fields searched and extracted when searching records and the order in which they are 
displayed, 
@xref{Catalog search (csearch),,@code{Catalog search (csearch)}}.

  @table @samp

  @item <catalog name> (optional, nested)

    The following instructions only apply to the thematic catalog whose name is @strong{catalog name}.
    All the field names must belong to the table associated with the named catalog.

    @table @samp

    @cindex searched instruction
    @item searched (optional)

    A comma separated list of fields to be searched. These fields must be of type @strong{char}, 
    @strong{varchar} or @strong{text}. If not specified, all the fields of the listed types are 
    used. All the fields @strong{must} be fully qualified by
    prepending the name of the table in the following way: @strong{table.field}.

    @cindex extracted instruction
    @item extracted (optional)

    A comma separated list of fields to be extracted. If not specified, all the fields of the table
    are extracted and available for display, @xref{csearch.html,,@code{csearch.html}}. This instruction
    is used to limit the number of fields extracted from the database, if the records are made of many
    fields and only a few are needed for display. All the fields @strong{must} be fully qualified by
    prepending the name of the table in the following way: @strong{table.field}.
    
    @cindex order instruction
    @item order (optional)
    
    An @strong{ORDER BY} clause to sort the records found. The fields mentioned in this clause @strong{must}
    be fully qualified by
    prepending the name of the table in the following way: @strong{table.field}.

    @end table

  @end table

@item encoding (optional, default ISO-8859-1)
The encoding of the catalog data. It is used to convert
data from XML files, 
@xref{XML document encoding, ,@code{XML document encoding}}. T
If the encoding is not the default it influences the search mechanism,
@xref{Full text search, ,@code{Full text search}}.

@end table

Here is an example configuration file:

@example
#
# Catalog.pm configuration file
#
#
# HTML code that separates two component of the path
#
path_separator = &nbsp;/&nbsp;
#
# Label for the root of the hierarchy tree
#
path_root_label = <b>Ze root</b>
#
# When cgi-bin is invoked with path_info instead of regular arguments,
# pretend that these parameters were used. It must at least contain
# the name of the catalog (name=<name>) and may also contain a style, for instance.
# The id and path parameters are automaticaly calculated from the path_info.
#
pathcontext_params = name=urlcatalog
#
# Search specifications
#
search
        #
        # Specifications for urlcatalog thematic catalog
        #
        urlcatalog
                #
                # Search these fields
                #
                searched = urldemo.url,urldemo.comment
                #
                # Only extract these fields for display
                #
                extracted = urldemo.url,urldemo.comment,urldemo.created
                #
                # ORDER BY clause to sort the records found
                #
                order = urldemo.url asc
        end
end
#
# Encoding of the catalog data (default is ISO-8859-1)
#
#encoding = ISO-8859-1
@end example

@node MySQL configuration file, CGI configuration file, Catalog configuration file, Configuration files
@section MySQL configuration file

@cindex MySQL configuration file
@cindex configuration file, MySQL
@cindex package mysql
@cindex mysql package

Used by the mysql package (mysql.pm). It defines which base must be used and 
parameters for the connection.

@table @samp

@cindex connection to MySQL
@cindex name of MySQL database
@cindex base, MySQL configuration
@item base (mandatory)
Name of the MySQL database to connect. Equivalent of base parameter in
mysql command.

@cindex host, MySQL configuration
@item host (optional, default localhost)
Hostname of the machine where the database is located. May be omitted if
the database is on the same machine as the application. Equivalent of the
--host option of the mysql command.

@cindex port, MySQL configuration
@item port (optional, default 3306)
Port number of the MySQL server. May be omitted if the port number is the
standard MySQL port number. Equivalent of the --port option of the mysql
command.

@cindex unixport, MySQL configuration
@item unixport (optional, default /var/lib/mysql/mysql.sock)
Socket file used for communications between the server and the client when
they reside on the same machine. Equivalent of the --socket option of the
mysql command.

@cindex authentification with MySQL
@cindex user, MySQL configuration
@item user (optional)
Name of the user used to connect to the MySQL database, if the authentication
system is active. If it is deactivated (--skip-grant-tables) this instruction
may be omitted. Equivalent of the --user option of the mysql command.

@cindex passwd, MySQL configuration
@item passwd (optional)
Password of the user used to connect to the MySQL database, 
if the authentication
system is active. If it is deactivated (--skip-grant-tables) this instruction
may be omitted. Equivalent of the --password option of the mysql command.

@cindex created table field
@cindex auto_created, MySQL configuration
@item auto_created (optional)
If this instruction exists and its value is set to @strong{yes}, the field
named @strong{created} is treated in a special way in every table. It must
be of type @code{datetime not null}. Each time a record is inserted using
the @code{mysql} package, if the @strong{created} field does not contain
any value, it is set with the current date.

@cindex full text engine load
@cindex load full text engine
@cindex specify full text engine
@cindex full text engine configuration
@cindex full text engine load
@item hook (optional)
The fully qualified name of the package that implements the integration
of a full text search engine. At present these values are available:

@table @samp
@item Catalog::tools::hook_fulcrum
@xref{Hook Fulcrum configuration file, ,@code{Hook Fulcrum configuration file}}.
@end table

@end table

Here is an example configuration file:

@example
#
# MySQL client configuration file
#
#
# Name of the database to connect. Mandatory.
#
base = interbat
#
# Host name. Comment if using localhost.
#
#host = enkidu
#
# Port number. Comment if using default.
#
port = 8301
#
# File name of the socket for local communications. Comment if
# using a remote host or if mysql does not support non-TCP/IP 
# communications on local host.
#
unix_port = /usr/local/lib/interbat/db/8401.sock
#
# User name. Comment if authentification is off.
#
#user = myname
#
# Password. Comment if authentification is off.
#
#passwd = mypass
#
# Uncomment to trigger special handling of the created field.
# If active, field whose name is 'created' will be filled with the 
# current date during insert.
# 
auto_created = yes
#
# Every update/delete/insert is passed to this hook
#
hook = Catalog::tools::hook_fulcrum
@end example

@node CGI configuration file, Install configuration file, MySQL configuration file, Configuration files
@section CGI configuration file

@cindex CGI derivation
@cindex cgi package 
@cindex package cgi

Used by the cgi package (cgi.pm).

@code{Catalog} depends on a modified CGI.pm package.
This configuration file deals with the additions specific to @code{Catalog}.

@table @samp

@cindex fct_dir, CGI configuration
@item fct_dir
The absolute pathname of the directory that will be used. When CGI is 
called recursively it creates a file in this directory that contains the
stack frame of the call. The file will be deleted when the CGI returns. 

@end table

Here is an example configuration file:

@example
#
# Derived cgi class (Catalog::cgi) configuration file
#
#
# Directory that will contain the saved execution contexts.
#
fct_dir = /usr/local/lib/interbat/cache
@end example

@node Install configuration file, SQL editor configuration file, CGI configuration file, Configuration files
@section Install configuration file

@cindex Install configuration
@cindex configuration parameters

Used by the sqledit package (sqledit.pm).

This configuration file is created during the installation. It is
used by @strong{sqledit} to find the location of the @code{Catalog}
components.

@table @samp

@cindex cgidir, installation parameter
@item cgidir (optional)
The absolute path of the cgi-bin directory.

@cindex cgipath, installation parameter
@item cgipath (optional)
The absolute location of the cgi-bin directory.

@cindex config_dir, installation parameter
@item config_dir (optional)
The absolute path of the directory containing configuration files.

@cindex htmldir, installation parameter
@item htmldir (optional)
The absolute location of the cgi-bin directory.

@cindex htmlpath, installation parameter
@item htmlpath (mandatory)
Absolute location of the @strong{Catalog} HTML material (/Catalog for 
instance). It contains the documentation, examples and an images
subdirectory (/Catalog/images for instance). This parameter will 
be available with the _HTMLPATH_ tag in every template.

@cindex infodir, installation parameter
@item infodir (optional)
The absolute path of the Emacs info directory where the
documentation was installed.

@end table

Here is an example configuration file:

@example
#
# Emacs info format documentat directory
#
infodir = 
#
# cgi-bin directory
#
cgidir = /home/httpd/cgi-bin
#
# cgi-bin directory HTML path
#
cgipath = /cgi-bin
#
# configuration files (*.conf) installation directory
#
config_dir = /home/httpd/cgi-bin
#
# Catalog material directory
#
htmldir = /home/httpd/html/Catalog
#
# Catalog material HTML path
#
htmlpath = /Catalog
@end example

@node SQL editor configuration file, Template configuration file, Install configuration file, Configuration files
@section SQL editor configuration file

@cindex SQL editor package 
@cindex sqledit package 
@cindex package sqledit
@cindex sqledit.conf

Used by the sqledit package (sqledit.pm). This module implements an HTML
interface to an SQL database. The instructions of this configuration file
modifies the behavior of the interface. 

@table @samp

@cindex read only access
@cindex limited access 
@cindex permissions

@item context_allow (optional, default *)
The list of allowed values for the @strong{context} cgi-bin parameter. 
The complete list of available context values is listed in the table
of content. Each value is described in a section and the name of the
section ends with the value of the context parameter, 
@xref{Catalog CGI, ,@code{Catalog CGI}}.

Alternatively, context_allow may be set to star (*, the default) to
allow every operations.

If the user is denied a specific operation, the following error message
will be displayed:

@cindex error messages
@cindex message string
@example
"%s context is not allowed"
@end example
@xref{Messages translation, ,@code{Messages translation}}.

Assuming that you want to give read-only access to your catalog, use
the following:

@example
context_allow = cbrowse
@end example

@cindex functions, SQL editor configuration
@cindex user defined functions
@cindex match and normalize functions

@item functions (optional, nested)
Defines functions that may be used as values for the @code{normalize} and
@code{match} instructions in the @strong{check} nested instruction.

@cindex anonymous perl functions
@cindex lambda

The keyword is the name of the function and the value is the body of the
function. The body of the function must be a piece of @strong{Perl} code
that returns a function pointer when evaluated. Most of the time it is
a simple lambda (sub @{ ... @}). No parameters are passed to the function, 
however the @code{$_} variable contains the current value
of the field for which the function was called. See the description of
the @code{match} and @strong{check} instructions for a description of the
return values expected from these functions.

Since the available libraries are not documented you can only rely on
the standard @strong{Perl} libraries here. 

@cindex function example
@example
functions
        normalize_lc = sub @{ $_ = lc; return 1; @}
        check_alnum = sub @{ /[a-z0-9]+/ || "alphanumerical" @}
end
@end example

@cindex check, SQL editor configuration
@item check (optional, nested)
Defines the checking that must be done on each field of each table of the
current database (the current database is defined in the mysql.conf file).
The structure of this instruction is as follow:

@example
check
        table1
                field1
                        normalize = <function>
                        match = <function>
                        mandatory = yes
                end
                field2
                        ...
                end
                ...
        end
        ...
end
@end example

We will define bellow the instructions that may be associated with each field.

        @table @samp

@cindex normalize, SQL editor
@cindex normalize value in editor
@cindex update normalization of values
@cindex insert normalization of values

@item normalize (optional, default returns 1)
The @strong{<function>} may be either a valid @strong{Perl} function or
a function defined in the @code{function} section of this configuration file.
The @strong{$_} variable contains the value of the field for the current
record.

The @code{normalize} function is called when the value of the field is
updated or a new value is inserted.

The return value of the function must be 

@cindex normalize return values
@itemize @bullet
@item 
1 if the normalization of the value was a success.
@item
0 if the value cannot be normalized.
@end itemize

If the return value is 1, the @strong{$_} variable is expected to contain
the normalized value when the function returns.

If the return value is 0, the following error message will be issued
to the end user:

@cindex error messages
@cindex message string
@example
table %s : field %s : value %s normalize failed %s
@end example
@xref{Messages translation, ,@code{Messages translation}}.

@cindex check, SQL editor
@cindex check value in editor
@cindex update checking of values
@cindex insert checking of values
@cindex match used for checking values

@item match (optional, default returns 1)
The @strong{<function>} may be either a valid @strong{Perl} function or
a function defined in the @code{function} section of this configuration file.
The @strong{$_} variable contains the value of the field for the current
record.

The @code{match} function is called when the value of the field is
updated or a new value is inserted.

The return value of the function must be 

@cindex match return values
@itemize @bullet
@item 
1 if the value matches the constraint.
@item
a string if the value does not match the constraint.
@end itemize

If the return value is a string, the following error message will be issued
to the end user:

@cindex error messages
@cindex message string
@example
table %s : field %s : value %s match failed %s
@end example
@xref{Messages translation, ,@code{Messages translation}}.

where the last @code{%s} is replaced by the string returned by the function,
thus providing precise error messages.

@cindex mandatory, SQL editor
@cindex mandatory fields in editor

@item mandatory (optional)
If present, the associated field must always contain a value that is
not empty. 

The mandatory check is done when the value of the field is
updated or a new value is inserted.

If the new value is null (only contains white space), the 
following error message will be issued
to the end user:

@cindex error messages
@cindex message string
@example
table %s : field %s must be set
@end example
@xref{Messages translation, ,@code{Messages translation}}.
        @end table



@item dictionaries (optional, nested)
@cindex dictionaries, SQL editor
@cindex dictionaries values display
@cindex display control for dictionaries

Parameters that apply to the dictionaries as defined by the relational
specifications, 
@xref{Relational constraints, ,@code{Relational constraints}}. 
Keep in mind that dictionaries are handled as if they were native
@code{enum} or @code{set} types of MySQL. This instruction allows to 
control the display of such dictionaries. 

@cindex where clause and dictionaries
@cindex order clause and dictionaries
@example
dictionary
        tablename1
                where = <where clause1>
                order = <order clause1>
        end
        tablename2
                where = <where clause2>
                order = <order clause2>
        end
        ...
end
@end example

        @table @samp

@item where (optional)
The @strong{<where clause>} 
may be any expression valid in a SQL where clause. The beginning of the
SQL order is something like @code{select * from tablename}. 
The values displayed to the user will only be those matching the 
where clause, for more information on how to display a dictionary
@xref{Template files introduction, ,@code{Template files introduction}}.

@item order (optional)
The @strong{<where clause>} 
may be any expression valid in a SQL order clause. The beginning of the
SQL order is something like @code{select * from tablename}. The menu
generated for this dictionary will show the values listed according to
this clause. If not provided, no specific order can be expected.

        @end table

@cindex display, SQL editor
@cindex dictionaries values display
@cindex display control for dictionaries

@item display (optional, nested)
Controls the generation of HTML code for menus and lists of checkboxes
associated to dictionaries. Basically it is a matter of choosing how
many columns you want, what kind of separator should be displayed etc.

The structure of this instruction is as follow:

@example
display
        select
                general
                        multiple = <number of lines>
                        labelnull = <HTML text>
                end
                tablename1
                        field1
                                multiple = <number of lines>
                                labelnull = <HTML text>
                        end
                        ...
                end
                ...
        end
        table
                general
                        columns = <number of columns>
                        font = <font ...>
                end
                tablename1
                        field1
                                columns = <number of columns>
                                font = <font ...>
                        end
                        ...
                end
                ...
        end
end
@end example

In both @code{select} and @code{table}, there is a special table name, 
@strong{general}, that provides the default for all the table names not
specifically listed.

        @table @samp

@cindex select, SQL editor
                @item select
Provides instructions for customizing a @strong{select} HTML tag. 

                @table @samp
@cindex multiple, SQL editor
                        @item multiple (optional, default 4)
The value of the @strong{multiple} parameter in the @strong{select} tag.
@cindex labelnull, SQL editor
                        @item labelnull (optional, default @strong{---------})
When the list of values of the dictionaries is generated, the empty value
is prepended and the text visible to the user is the value of this
attribute.
                @end table

@cindex table, SQL editor
                @item table
Provides instructions for customizing the display of a set of radio buttons
or checkboxes within a table.

                @table @samp
@cindex columns, SQL editor
                        @item columns (optional, default 4)
The number of columns used for the table containing the radio buttons or
the checkboxes.
@cindex font, SQL editor
                        @item font (optional)
An HTML font change specification that will be duplicated in every cell
of the table.
                @end table

        @end table

@item nph (optional, default @strong{no})
Set it to @strong{yes} if your script is nph (non parsed header). This
changes the header sent by @strong{Catalog}. For more information on nph cgi-bin
see the @code{Apache} documentation and the @code{CGI.pm} documentation.

@end table

@node Template configuration file, Hook Fulcrum configuration file, SQL editor configuration file, Configuration files
@section Template configuration file

@cindex templates configuration file
@cindex configuration file for templates

@table @samp
@item style (optional, nested)

Maps template file names according to style names. 

The structure of this nested instruction is as follows:

@example
style
        stylename
                templatepath = othertemplatepath
                ...
        end
        ...
@end example

The @strong{templatepath} must be a template path name as defined for the
current application, @xref{Template files introduction, ,@code{Template files introduction}}.

@end table

@example
#
# Templates system configuration
#
#
style
        liensacteur
                cbrowse_root.html = liensacteurtop.html
                cbrowse.html = liensacteur.html
        end
        lienstheme
                cbrowse_root.html = liensthemetop.html
                cbrowse.html = lienstheme.html
        end
        liensalpha
                calpha_root.html = liensalphatop.html
                calpha.html = liensalpha.html
        end
end
@end example

@node Hook Fulcrum configuration file,  , Template configuration file, Configuration files
@section Hook Fulcrum configuration file

@cindex hook_fulcrum.conf

@c top level start
@table @samp
	@item serial (mandatory)
The unique identifier used for fulcrum fields. We advise to use 230. 
Each fulcrum field generated from the database/tables specification
will be associated with an identifier in the range <serial> and up.

	@item chunksize (mandatory)
The maximum number of updates or deletions that can be done with 
fulcrum. We advise to use 1000. This is mainly to prevent SQL query
buffer overflow for tables that contain a lot of records.

	@item <sql database> (nested)
All other keywords at the top level of the configuration file are
interpreted as SQL database names. The nested configuration instructions
describe the coupling between this database and the fulcrum search
engine.

	@c database start
        @table @samp
        	@item params (mandatory, nested)
Database wide parameters.

		@c database/params start
		@table @samp
			@item table (mandatory)
The name of the fulcrum table that will contain the indexed data.
		@end table
		@c database/params end

		@item tables (mandatory, nested)
All the keywords are SQL tablenames.

		@c database/tables start
		@table @samp
			@item <sql tablename> (mandatory, nested)

			@c database/tables/<sql tablename> start
			@table @samp
				@item params (optional, nested)

				@c database/tables/<sql tablename>/params start
				@table @samp
					@item where (optional)
A where clause applied on the SQL table that will limit the scope of
records taken in account during indexing.

					@item merge (optional, nested)
Import fields values from the designated table for every 
indexed record of the current table. The designated table
must have an entry in database/table and the listed fields
must be mapped to fulcrum fields.
					@c database/tables/<sql tablename>/params/merge start
					@table @samp
						@item table (mandatory)
An SQL table linked to the current table, 
@xref{Relational constraints, ,@code{Relational constraints}}. 
						@item fields (mandatory)
The list of fields from the table that must be imported. 
					@end table
					@c database/tables/<sql tablename>/params/merge end
				@end table
				@c database/tables/<sql tablename>/params end

                                @item fields (mandatory, nested)
All the keywords must be valid fieldnames of the SQL table.
				@c database/tables/<sql tablename>/fields start
                                @table @samp
					@item <sql fieldname>
					@c database/tables/<sql tablename>/fields/<sql fieldname> start
					@table @samp
                                        	@item field
The name of the fulcrum field that will contain a copy of the value from the
SQL field.
					@end table
					@c database/tables/<sql tablename>/fields/<sql fieldname> end
				@end table
				@c database/tables/<sql tablename>/fields end
			@end table
			@c database/tables/<sql tablename> end
		@end table
		@c database/tables end
                
                @item query (mandatory, nested)
Specifications to build the full text query.

		@c database/query start
                @table @samp
                	@item table (mandatory)
The name of the fulcrum table to use for the query.
                        @item divide_or (optional)
The division factor applied to @strong{or} query in each group.
			@item extract (mandatory)
The list of fields that contains the rowid of the records that are to
be retrieved from the SQL database. Those fields all begin with @strong{r_}.
If an order clause is present must also contain all the fields mentioned
in the order clause (due to fulcrum limitations).
			@item relevance (mandatory)
The relevance method used. 
If an order clause is present must also contain all the fields mentioned
in the order clause (due to fulcrum limitations).
			@item order (optional)
Order by clause.
			@item constraint_weight (optional)
If a constraint matches in a given group, give it the weight mentioned in
here.
			@item templates (optional, nested)
Re-map each automatically generated sub template name.
                @end table
		@c database/query end
                
                @item groups (mandatory, nested)
                

		@c database/groups start
                @table @samp
                	@item <group number> (mandatory nested)
Each group number is taken in numerical order to build the query.
			@c database/groups start
	                @table @samp
                        	@item where (optional)
The record must match the where condition in addition to the generated
full text query.
				@item weight (mandatory)
Records matching the literal or all the words from the query will have
this weight. Records matching at least one word from the question will
have this weight divided by the @strong{divide_or} parameter.
				@item constraint (optional)
If specified list the fields on which a constraint may be applied. 
				@item fields (mandatory)
The list of fulcrum table fields that will be searched during the full
text search process.
	                @end table
			@c database/groups end
                @end table
		@c database/groups end
        @end table
	@c database end
@end table 
@c top level end

The general structure of the file is as follows:

@example
#
# Link fulcrum with SQL database
#
#
# Fulcrum field numbering start from serial and up (suggested 230)
#
serial = <number> 
#
# How many fulcrum deletions/update can be done in one
# request (suggested 1000)
#
chunksize = <number>
#
# SQL base name
#
<sql database>
    #
    # General parameters for base
    #
    params
        #
        # Name of the fulcrum table 
        #
        table = <fulcrum tablename>
    end
    #
    # SQL tables mapping
    #
    tables
        <sql tablename>
            params
                #
                # Only records matching this where
                # clause will be inserted
                #
                where = <sql where clause>
                #
                # Merge part of a linked row into
                # each entry. Link must be defined in
                # relations.spec.
                #
                merge   
                    table = <sql tablename>
                    fields = <sql fieldname,sql fieldname,...>
                end
            end
            fields
                <sql fieldname>
                    field = <fulcrum fieldname>
                end
                ...
            end
        end
        ...
    query
        params
            #
            # Name of the fulcrum table 
            #
            table = <fulcrum tablename>
            #
            # Reduce factor for or'ed terms (suggested 100)
            #
            divide_or = <number>
            #
            # When a row is found, retrieve only these fields
            #
            extract = <fulcrum fieldname>,<fulcrum fieldname>,...
            #
            # Relevance method
            #
            relevance = relevance(<fulcrum relevance>) as rel,
                        <fulcrum orderby fields>
            #
            # When querying the order by clause is order
            #
            order = <fulcrum orderby>
            #
            # If a constraint is matched, apply this weight 
            # (suggested 1000)
            #
            constraint_weight = <number>
            #
            # Map table names to template names
            #
            templates
                <sql table,sql table,...> = <template basename>
                ...
            end
        end
        groups
            <group number>
                where = <fulcrum where clause>
                weight = <number>
                constraint = <constraint re>
                fields = <fulcrum fields>
            end
            ...
        end
    end
end
@end example

Here is a complete example:

@example
#
# Link fulcrum with SQL database
#
#
# Fulcrum field numbering start from serial and up
#
serial = 230
#
# How many deletions/update can be done in one request
#
chunksize = 1000
#
# Mysql base name
#
interbat
    #
    # General parameters for base
    #
    params
        #
        # Name of the fulcrum table 
        #
        table = intersmall
    end
    #
    # Mysql tables mapping
    #
    tables
        societe
            params
                #
                # Only records matching this where
                # clause will be inserted
                #
                where = find_in_set('interbat', typesociete) 
            end
            fields
                typesociete
                    field = so_typesociete
                end
                nomaffiche
                    field = so_nomaffiche
                end
                raisonsociale
                    field = so_raisonsociale
                end
                raisonsocialecomplementaire
                    field = so_raisonsocialec
                end
                sigle
                    field = so_sigle
                end
                motscles
                    field = so_motscles
                end
                descriptif
                    field = so_descriptif
                end
                descriptiflong
                    field = so_descriptiflong
                end
                activite
                    field = so_activite
                end
                url
                    field = so_url
                end
                mail
                    field = so_mail
                end
                adresse
                    field = so_adresse
                end
                codepostal
                    field = so_codepostal
                end
                ville
                    field = so_ville
                end
                pays
                    field = so_pays
                end
                tel
                    field = so_tel
                end
            end
        end
        start
            params
                #
                # Only records matching this where
                # clause will be inserted
                #
                where = disabled = 'no'
            end
            fields
                descriptif
                    field = st_descriptif
                end
                url
                    field = st_url
                end
                debut
                    field = st_debut
                end
                fin
                    field = st_fin
                end
            end
        end
        personne
            params
                #
                # Only records matching this where
                # clause will be inserted
                #
                where = publiable = 'yes'
                #
                # Merge part of a linked row into
                # each entry. Link must be defined in
                # relations.spec
                #
                merge   
                    table = societe
                    fields = typesociete
                end
            end
            fields
                nom
                    field = pe_nom
                end
                url
                    field = pe_url
                end
                mail
                    field = pe_mail
                end
                fonction
                    field = pe_fonction
                end
                adresse
                    field = pe_adresse
                end
                codepostal
                    field = pe_codepostal
                end
                ville
                    field = pe_ville
                end
                pays
                    field = pe_pays
                end
                tel
                    field = pe_tel
                end
            end
        end
        produitsnouveaux
            params
                #
                # Only records matching this where
                # clause will be inserted
                #
                # where = 
            end
            fields
                texte
                    field = pn_texte
                end
                nom
                    field = pn_nom
                end
                url
                    field = pn_url
                end
                debut
                    field = pn_debut
                end
                fin
                    field = pn_fin
                end
            end
        end
        marque
            params
                #
                # Only records matching this where
                # clause will be inserted
                #
                # where = 
                #
                # Merge part of a linked row into
                # each entry. Link must be defined in
                # relations.spec
                #
                merge   
                    table = societe
                    fields = typesociete
                end
            end
            fields
                marque
                    field = ma_marque
                end
                descriptif
                    field = ma_descriptif
                end
            end
        end
    end
    query
        params
            #
            # Name of the fulcrum table 
            #
            table = interall
            #
            # Reduce factor for or'ed terms
            #
            #divide_or = 100
            #
            # When a row is found, retrieve only these fields
            #
            extract = r_societe,r_marque
            #
            # Relevance method
            #
            relevance = relevance('2:2') as rel,ma_marque
            #
            # When querying the order by clause is order
            #
            order = rel desc,ma_marque
            #
            # If a constraint is matched, apply this weight
            #
            constraint_weight = 1000
            #
            # Map table names to template names
            #
            templates
                societe,start = start
                marque,societe = marquebatibase
                personne,societe = personnebatibase
                produitsnouveaux,societe = produitsnouveaux
                societe = societebatibase
            end
        end
        groups
            1
                where = so_typesociete contains 'interbat' weight 0
                weight = 900
                constraint = so_.*
                fields = so_raisonsociale,so_sigle,so_motscles
            end
            2
                where = so_typesociete contains 'interbat' weight 0
                weight = 900
                constraint = ma_.*
                fields = ma_marque,ma_descriptif
            end
            3
                where = (pn_debut < now() and pn_fin > now())
                weight = 800
                constraint = pn_.*
                fields = pn_nom,pn_texte,pn_url
            end
            4
#               where = (st_debut < now() and st_fin > now())
                weight = 700
                constraint = st_.*
                fields = st_url,st_descriptif
            end
            5
                weight = 700
                # st_url,ho,pa,tx
                constraint = (ho|pa|tx|e_text)
                fields = e_text
            end
            6
                where = so_typesociete contains 'batibase' weight 0
                weight = 130
                constraint = so_.*
                fields = so_raisonsociale,so_sigle,so_motscles
            end
            7
                where = so_typesociete contains 'batibase' weight 0
                weight = 130
                constraint = ma_.*
                fields = ma_marque,ma_descriptif
            end
            8
                weight = 50
                constraint = so_.*
                fields = so_url,so_mail,so_adresse,so_codepostal
            end
            9
                weight = 50
                constraint = pe_.*
                fields = pe_nom,pe_url,pe_mail,pe_fonction,pe_adresse
            end
        end
    end
end
@end example

@node External representation, Template files introduction, Configuration files, Top
@chapter External representation

@cindex External representation
@cindex XML format

The thematic catalogs have an external representation that allow easy
transportation of their content. The format used is XML. The file
containing the XML representation of a catalog is named with the @code{.rdf}
extension. When the XML/RDF conventions will be better supported the 
catalogs will eventually use these conventions, hence the extension. 
You should @code{not} invest too much on the current XML format because
it is likely to change drastically in the next few monthes. Nevertheless,
we've found very convinient to have a text representation of the catalogs,
specially for importing data from various sources.

@menu
* XML short example::           XML short example
* XML document encoding::       XML document encoding
* XML structure::               XML structure
* dmoz.org::                    dmoz.org
@end menu

@node XML short example, XML document encoding, External representation, External representation
@section XML short example

Here is a short example of an XML file

@example
<?xml version="1.0" encoding="ISO-8859-1" ?>
<RDF xmlns:rdf="http://www.w3.org/TR/1999/REC-rdf-syntax-19990222#"
     xmlns="http://www.senga.org/">

 <Table>
  <![CDATA[
CREATE TABLE urldemo (
  rowid int(11) DEFAULT '0' NOT NULL auto_increment,
  created datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
  modified timestamp(14),
  info enum('active','inactive') DEFAULT 'active',
  url char(128),
  comment char(255),
  UNIQUE cdemo1 (rowid)
)
  ]]>
 </Table>

 <Catalog>
  <navigation>theme</navigation>
  <tablename>urldemo</tablename>
  <name>urltheme</name>
 </Catalog>

 <Category>
  <name>News</name>
  <rowid>12</rowid>
  <parent>1</parent>
 </Category>

 <Link>
  <row>135</row>
  <category>12</category>
 </Link>

 <Record table="urldemo">
  <url>http://www.mediaslink.com/</url>
  <comment>Medias Link</comment>
  <rowid>135</rowid>
 </Record>

 <Sync/>
</RDF>
@end example

@node XML document encoding, XML structure, XML short example, External representation
@section XML document encoding

@cindex XML document encoding
@cindex encoding of XML document

The encoding of an XML document is specified in the @code{<?xml ... ?>} line
at the beginning. Accepted encodings are:

@itemize @bullet

@cindex ISO-8859-1
@item 
ISO-8859-1

@cindex ISO-8859-2
@item 
ISO-8859-2

@cindex ISO-8859-3
@item 
ISO-8859-3

@cindex ISO-8859-4
@item 
ISO-8859-4

@cindex ISO-8859-5
@item 
ISO-8859-5

@cindex ISO-8859-6
@item 
ISO-8859-6

@cindex ISO-8859-7
@item 
ISO-8859-7

@cindex ISO-8859-8
@item 
ISO-8859-8

@cindex ISO-8859-9
@item 
ISO-8859-9

@end itemize

More encodings should be available as the XML manipulation library evolve.

@node XML structure, dmoz.org, XML document encoding, External representation
@section XML structure

When an element is said to describe a record it means that it contains
elements whose name are record field names and contains the value of the
field. For instance:

@example
<Record table=urldemo>
 <url>http://www.senga.org/</url>
 <comment>Senga</comment>
</Record>
@end example

defines a record of the @strong{urldemo} table with two fields (@code{url}
and @code{comment}) whose values are, respectively @code{http://www.senga.org/}
and @code{Senga}.

@table @samp

@cindex Table XML element
@cindex XML element : Table
@item Table
Contains a unique SQL order that will create a table.

@cindex Catalog XML element
@cindex XML element : Catalog
@item Catalog
Describes a record of the @code{catalog} table, @xref{catalog,,@code{catalog}}.
The remaining of the file will relate to the catalog described in this element.
There must be only one @code{Catalog} element in a given file.

@cindex Category XML element
@cindex XML element : Category
@item Category
Describes a record of the @code{catalog_category} table, @xref{catalog_category_<name>,,@code{catalog_category_<name>}}.
The pseudo field @code{parent} will build a record in the
@code{catalog_category2category} table linking the category to its parent, 
@xref{catalog_category2category_<name>,,@code{catalog_category2category_<name>}}.

@cindex Link XML element
@cindex XML element : Link
@item Link
Describes a record of the @code{catalog_entry2category} table, @xref{catalog_entry2category_<name>,,@code{catalog_entry2category_<name>}}.

@cindex Record XML element
@cindex XML element : Record
@item Record
Describes a record of the table named by the @strong{table} attribute.

@cindex Symlink XML element
@cindex XML element : Symlink
@item Symlink
Describes a record of the @code{catalog_category2category} table, @xref{catalog_category2category_<name>,,@code{catalog_category2category_<name>}}. The
info field of the record is automaticaly set to @strong{symbolic}.


@cindex Sync XML element
@cindex XML element : Sync
@item Sync
When this element is seen during the parsing of the file, administrative
information is recomputed for the catalog. This should only occur once,
at the end of the file.

@end table

@node dmoz.org,  , XML structure, External representation
@section dmoz.org

@cindex dmoz.org

The site @uref{http://www.dmoz.org/,} provides a dump of their catalog data.
A conversion routine between their XML format and the Catalog XML format
is provided (convert_dmoz). The @strong{Catalog} class was derived to 
implement specific features and may be accessed using the @strong{dmoz}
cgi-bin script instead of the @strong{Catalog} cgi-bin script.

We have loaded a version of dmoz.org that contains approximately 400 000
records and around 65 000 categories on a Pentium 350. It leads to a
400Mb MySQL database and the response time when navigating the
categories is excellent.

@node Template files introduction, Catalog template files, External representation, Top
@chapter Template files introduction

@cindex template files 
@cindex template files definitions
The template files are the HTML files used by the cgi-bin to interact
with the user. Every interaction step is associated with the file name
of a template, the content of this file is read and analyzed by the 
cgi-bin and portions of it are replaced according to the action taken. 

@cindex simple template file

The simplest of all templates is the error template. It looks like this:

@cindex _MESSAGE_

@example
<title>Error</title>
<center><h3>
Error<p>
_MESSAGE_
</center></h3>
@end example

When an error occurs in a cgi-bin the error template is used. The
@strong{_MESSAGE_} tag is replaced by the actual error message and the
result is sent to the user.

@cindex location of template files
@cindex template files location
@cindex TEMPLATESDIR

The templates file names are located in the current directory if the
@code{TEMPLATESDIR} environment variable is not set. If it is set it
must contain a list of colon separated directories. The directories are
explored in order to find the template file. If no file is found a default
in-core version is used.

A template is often divided is parts, sometimes recursively. The general
syntax of this subdivision is as follows:

@cindex template files parts
@cindex template files subparts

@example
bla bla...
<!-- start part -->
bla bla...
<!-- start subpart -->
bla bla...
<!-- end subpart -->
bla bla...
<!-- end part -->
bla bla...
@end example

The template contains a part named @code{part}. This part contains a
subpart named @code{subpart}. This kind of subdivision is used when
a component of the template must be repeated or conditionally included.
Note that the specifications for parts are included in HTML comments
to prevent interferences when editing the template with a wysiwyg editor.

Within a part, it is possible to specify arbitrary parameters to the cgi-bin
using the @code{params} specification.

@example
<!-- params 'var1' => 'value1', 'var2' => 'value2'... -->
@end example

The exact variables allowed in such an instruction and the interpretation of
their values depend on the cgi-bin.

The tags of a template are strings that will be replaced by actual values
by the cgi-bin. The tags are always surrounded by underscores and the strings
are in upper case. If two strings appear in the same tag they are separated
by a dash (@strong{-}). These are valid tags:

@itemize @bullet
@item _MESSAGE_
@item _URL-COMMENT_
@end itemize

These are not valid tags:

@itemize @bullet
@item _mycomment_
@item _URL_COMMENT_
@end itemize

The tags found in a part or subpart of a template may be the same, this
does not mean that they will be replaced by the same string. All the parts
and subparts have a separate name space. Always refer to the template 
documentation to find out which tags are defined.

The exact semantic associated to these subdivisions completely depends
on the action associated to the template. 

@menu
* Templates switch table::      Templates switch table
* Fixed tags::                  Fixed tags
* Database table tags::         database table tags
* Record list part::            Record list part
* Multipage results template::  Multipage results template
* Actions that takes a long time::  Actions that takes a long time
@end menu

@node Templates switch table, Fixed tags, Template files introduction, Template files introduction
@section Templates switch table

@cindex template style
@cindex style template mapping
@cindex style cgi-bin parameter
@cindex cgi-bin style parameter

In order to allow multiple template files to coexist, the template package
configuration file allows arbitrary mapping of the template file names
listed in this chapter to other file names, @xref{Template configuration file, ,@code{Template configuration file}}. 
The choice of a specific name map depend on the @strong{style} 
parameter, @xref{Style parameter, ,@code{Style parameter}}.

@node Fixed tags, Database table tags, Templates switch table, Template files introduction
@section Fixed tags

@cindex tags always available
@cindex fixed tags

The following tags are always available in any template or a template part.

@table @samp

@cindex _SCRIPT_
@item _SCRIPT_
Absolute path of the cgi-bin script (/cgi-bin/Catalog for instance).
It may be used to set the @strong{action} part of a @strong{FORM} HTML
tag.

@cindex _HTMLPATH_
@item _HTMLPATH_
Absolute location of the @strong{Catalog} HTML material (/Catalog for 
instance). It contains the documentation, examples and an images
subdirectory (/Catalog/images for instance).

@end table

@node Database table tags, Record list part, Fixed tags, Template files introduction
@section Database table tags

Most templates display fields from tables and they all follow the same
conventions. If the template documentation states that a record from 
table @code{table} is available in a specific part of the template, a set
of tags is automatically available. 

@table @samp

@cindex _FIELDNAME_
@item _FIELDNAME_
The value of the field, verbatim. As a special case, if the field is
of type blob, and @strong{img} tag is generated to display the content
of the field. It must be a @strong{GIF} file.

@cindex _FIELDNAME-QUOTED_
@item _FIELDNAME-QUOTED_
The value of the field, with all characters that would cause problems in
HTML (quote, double quote, lower than and greater than) replaced by their
symbolic form. This is suitable for insertion in the value part of an 
@strong{input}
tag, for instance.

@cindex _FIELDNAME-CODED_
@item _FIELDNAME-CODED_
The value of the field, with all characters that would cause problems in
an URL (space, ampersand and all so called @code{unsafe} characters) replaced
by their hexadecimal form. This is suitable for insertion in the URL part
of an @strong{a} tag, for instance.

@cindex _FIELDNAME-MENU_
@item _FIELDNAME-MENU_
Only suitable for fields of type @strong{set} or @strong{enum}.
Display the current value of the field within a @strong{select} style 
menu listing all the allowable values of the field. 
If the type of the field is @strong{set}, the menu generated allows 
multiple selection.
The exact display
generated depends on the definitions found in the @strong{sqledit.conf}
file, @xref{SQL editor configuration file, ,@code{SQL editor configuration file}}.

@cindex _FIELDNAME-RADIO_
@item _FIELDNAME-RADIO_
Only suitable for fields of type @strong{enum}.
Display the current value of the field within a table of radio buttons.
The radio button associated with the current value is checked. 
The exact display
generated depends on the definitions found in the @strong{sqledit.conf}
file, @xref{SQL editor configuration file, ,@code{SQL editor configuration file}}.

@cindex _FIELDNAME-CHECKBOX_
@item _FIELDNAME-CHECKBOX_
Only suitable for fields of type @strong{set}.
Display the current values of the field within a table of checkboxes.
The check boxes associated with the current values is checked. 
The exact display
generated depends on the definitions found in the @strong{sqledit.conf}
file, @xref{SQL editor configuration file, ,@code{SQL editor configuration file}}.

@end table

The tags listed above may be prefixed by the name of the table to 
disambiguate. 

@itemize @bullet
@cindex _TABLE-FIELDNAME_
@item _TABLE-FIELDNAME_
@cindex _TABLE-FIELDNAME-QUOTED_
@item _TABLE-FIELDNAME-QUOTED_
@cindex _TABLE-FIELDNAME-CODED_
@item _TABLE-FIELDNAME-CODED_
@cindex _TABLE-FIELDNAME-MENU_
@item _TABLE-FIELDNAME-MENU_
@cindex _TABLE-FIELDNAME-RADIO_
@item _TABLE-FIELDNAME-RADIO_
@cindex _TABLE-FIELDNAME-CHECKBOX_
@item _TABLE-FIELDNAME-CHECKBOX_
@end itemize

This form is only necessary if to tables have the same field name and
a part of the template provide a record from both of them.

Each datatype has a default display form that is used when nothing is
specified in the template. Here is an association between the @code{MySQL}
datatypes and the default display associated with them.

@table @samp
@item char of size 1
Input text of size two.
@item char of size > 30 and < 1000
Input text of size thirty.
@item char of size > 1000
Text area of six rows and thirty columns.
@item integer
Input text of size ten.
@item date or time
Input text of size twenty.
@item blob
File upload.
@item set
Table of checkboxes, @xref{SQL editor configuration file, , @code{SQL editor configuration file}}.
@item enum
Single choice menu, @xref{SQL editor configuration file, , @code{SQL editor configuration file}}.
@end table

@node Record list part, Multipage results template, Database table tags, Template files introduction
@section Record list part

In many templates there are template parts (see the introduction at the
beginning of this chapter) used to display a list of records from the 
database. All of them (with the notable exception of the query by example
search result, @xref{sqledit_search.html, ,@code{sqledit_search.html}}.) use
the same library and comply to the following part description for their 
display.

@table @samp

@item Params and Parts

If there is a @strong{style} parameter in the enclosing part
and that the value associated with this parameter is @code{table}, 
then the part used to display the search results will be @strong{row}.
Otherwise the part used will be @strong{entry}.

@table @samp
@item style = table
Use @strong{row} part. The @strong{columns} parameter is the number of
columns generated. For each record, the @strong{entry} part is repeated.
If the @strong{entry} part has been repeated @strong{columns} times, the
@strong{row} part is displayed with the generated entries.

@example
...
<table>
<!-- params 'style' => 'table', 'columns' => 2 -->
<!-- start row --> 
<tr>
<!-- start entry -->
<td> <a href='_URL_'>_NAME_</a> (_COUNT_) </td>
<!-- end entry -->
</tr>
<!-- end row --> 
</table>
...
@end example

@item style = *
Use @strong{entry} part, repeated as many times as there are records. 

@example
...
<ul>
<!-- start entry -->
<li> <a href='_URL_'>_NAME_</a> (_COUNT_)
<!-- end entry -->
</ul>
...
@end example

@end table

If no records are found, the @strong{row} or @strong{entry} parts are
not displayed.

In some cases, the @strong{entry} part (within a @strong{row} part
or stand alone) may be subdivided as shown below:

@example
...
<ul>
<!-- start entry -->

<!-- start company -->
<li> _COMPANY-NAME_ _COMPANY_URL_
<!-- end company -->

<!-- start customer -->
<li> _CUSTOMER-NAME_ _CUSTOMER-ACTIVITY_
<!-- end customer -->

<!-- end entry -->
</ul>
...
@end example

This subdivision is @strong{always} an alternative, that is, either the
@strong{company} part or the @strong{customer} part will be displayed, never
both. This is mainly used to specify a part that many contain records from
different tables so that they are displayed in a specific way.
The exact semantic associated with these subparts is defined by the cgi-bin.

@item Tags

Within the @strong{entry} part, the following tags are defined.

@table @samp

@item table tags
@cindex _DEFAULTROW_
All the automatically generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@end table


@node Multipage results template, Actions that takes a long time, Record list part, Template files introduction
@section Multipage results template

All the cgi-bin that want to display their result using more than one HTML
page use the same module to implement this functionality. For instance, when
searching the database, the first page displayed only contains the first
ten results. A footer is added to the page with links to the next pages.
The default footer looks like this:

@image{images/pager,10cm,}

The footer is called the @code{pager} section. In the example it shows
the total number of pages on one line. The next line shows the current page
as a page number not associated with a link. All other page numbers are 
associated with a link that gives direct access to the page. 

If no @code{pager} template part is found, the display is automatically 
switched to a one page display. Here is an example @code{pager} part :

@cindex _MAXPAGES_
@cindex _PAGES_

@example
<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@table @samp
@item _MAXPAGES_
Is the total number of pages available.

@item _PAGES_
Is a fixed format list of links that give direct access to the first
twenty pages and indirect access to the others, as shown in the example
output above.
@end table

List of hidden fields necessary to perform the search. Must
be included in each @code{form}.

@node Actions that takes a long time,  , Multipage results template, Template files introduction
@section Actions that takes a long time

Some cgi-bin actions may take a very long time, such as catalog loading or
dumping. When an action is likely to take a long time, the cgi-bin emits
white space characters from time to time to provide a user feedback. When
the action begins a blank page is shown to the user and the status bar of
the navigator shows that some characters are received. 

This feedback serves two purposes : it shows that the action is doing something
and keeps the connection alive so that the HTTP server does not timeout.

@node Catalog template files, SQL template files, Template files introduction, Top
@chapter Catalog template files

@menu
* ccontrol_panel.html::         ccontrol_panel.html
* calpha_root.html::            calpha_root.html
* calpha.html::                 calpha.html
* cedit.html::                  cedit.html
* cbrowse_root.html::           cbrowse_root.html
* cbrowse.html::                cbrowse.html
* csearch.html::                csearch.html
* cdate_default.html::          cdate_default.html
* cdestroy.html::               cdestroy.html
* centryremove_all.html::       centryremove_all.html
* catalog_theme_insert.html::   catalog_theme_insert.html
* catalog_theme_edit.html::     catalog_theme_edit.html
* catalog_alpha_insert.html::   catalog_alpha_insert.html
* catalog_alpha_edit.html::     catalog_alpha_edit.html
* catalog_date_insert.html::    catalog_date_insert.html
* catalog_date_edit.html::      catalog_date_edit.html
* cdump.html::                  cdump.html
* cimport.html::                cimport.html
* cexport.html::                cexport.html
@end menu

@node ccontrol_panel.html, calpha_root.html, Catalog template files, Catalog template files
@section ccontrol_panel.html

@cindex ccontrol_panel.html
@cindex Catalog Control Panel
@cindex Control Panel, Catalog

Top level entry point for catalog management.

Here is an example template:

@example
<title>Catalog control panel</title>

<center><h3>Catalog control panel</h3></center>

<center><h3><font color=red>_COMMENT_</font></h3></center>
<table border=1>
<tr><td colspan=2 align=middle><b>Configuration files</b></td></tr>
<tr><td>MySQL</td><td><a href=_SCRIPT_?context=confedit&file=mysql.conf>edit</a></td></tr>
<tr><td>CGI</td><td><a href=_SCRIPT_?context=confedit&file=cgi.conf>edit</a></td></tr>
<tr><td>Catalog</td><td><a href=_SCRIPT_?context=confedit&file=catalog.conf>edit</a></td></tr>
<tr><td>sqledit</td><td><a href=_SCRIPT_?context=confedit&file=sqledit.conf>edit</a></td></tr>
</table>
<p>
<table border=1>
<tr><td colspan=5 align=middle><b>Existing catalogs</b></td></tr>
<!-- start catalogs -->
<tr>
 <td><b><a href=_SCRIPT_?context=ccatalog_edit&name=_NAME_>_NAME_</a></b></td>
 <td><a href=_SCRIPT_?context=cbrowse&name=_NAME__ID_>browse</a></td>
 <td><a href=_SCRIPT_?context=_COUNT_&name=_NAME_>count</a></td>
 <td><a href=_SCRIPT_?context=cdestroy&name=_NAME_>destroy</a></td>
 <!-- start theme -->
 <td><a href=_SCRIPT_?context=cedit&name=_NAME__ID_>edit</a></td>
 <td><a href=_SCRIPT_?context=cdump&name=_NAME_>dump</a></td>
 <td><a href=_SCRIPT_?context=cimport&name=_NAME_>load</a></td>
 <td><a href=_SCRIPT_?context=cexport&name=_NAME_>unload</a></td>
 <!-- end theme -->
</tr>
<!-- end catalogs -->
</table>
<p>
<form action=_SCRIPT_ method=POST>
<input type=hidden name=context value=cbuild>
Create _NAVIGATION_ catalog on table _TABLES_
<input type=submit value='Create it!'>
</form>
<p>
<table><tr><td>
<a href=_SCRIPT_?context=cimport>Load from file</a><br>
<a href=_SCRIPT_/>Simplified browsing</a><br>
<a href=_SCRIPT_?context=ccontrol_panel>Redisplay control panel</a><br>
<a href=_SCRIPT_?context=cdemo>Create a demo table (urldemo)</a><br>
</td><td>
<a href=_HTMLPATH_/catalog_toc.html><img src=_HTMLPATH_/images/help.gif alt=Help border=0 align=middle></a>
</td></tr></table>
<pre></b><i>
@end example

@table @samp

@item Parts

@table @samp

@cindex catalogs part
@item catalogs
This part is repeated for each existing catalog in 
the current database.

@cindex theme part
@item theme
This part @strong{must} be included in the @code{catalogs} part. It is
only included if the catalog is a theme catalog.

@end table

@item Tags

@table @samp
@cindex _COMMENT_
@item _COMMENT_
Warning and messages from the last action.

@cindex _NAME_
@item _NAME_
Name of the catalog.

@cindex _ID_
@item _ID_
Parameter containing the identifier of the root category (only available for
@strong{theme} catalogs). It has the form @strong{&id=<number>}.

@cindex _COUNT_
@item _COUNT_
Context value depending on the navigation type of the catalog. It will 
trigger an action that resets the count associated to each level of the
catalog tree (category_count, cdate_count or calpha_count).

@cindex _NAVIGATION_
@item _NAVIGATION_
Select box of all navigation type for the catalog (theme, alpha, date). 
The name of the value is @strong{navigation}.

@cindex _TABLES_
@item _TABLES_
Select box of all tables in the database. 
The name of the value is @strong{table}.

@end table

@end table

@node calpha_root.html, calpha.html, ccontrol_panel.html, Catalog template files
@section calpha_root.html

Root node of alphabetical navigation.

@cindex calpha_root.html
@cindex Root node of alphabetical navigation
@cindex Alphabetical navigation root node

@cindex _A_
@cindex _B_
@cindex _C_
@cindex _D_
@cindex _E_
@cindex _F_
@cindex _G_
@cindex _H_
@cindex _I_
@cindex _J_
@cindex _K_
@cindex _L_
@cindex _M_
@cindex _N_
@cindex _O_
@cindex _P_
@cindex _Q_
@cindex _R_
@cindex _S_
@cindex _T_
@cindex _U_
@cindex _V_
@cindex _W_
@cindex _X_
@cindex _Y_
@cindex _Z_
@cindex _0_
@cindex _1_
@cindex _2_
@cindex _3_
@cindex _4_
@cindex _5_
@cindex _6_
@cindex _7_
@cindex _8_
@cindex _9_

@cindex _ALETTER_
@cindex _BLETTER_
@cindex _CLETTER_
@cindex _DLETTER_
@cindex _ELETTER_
@cindex _FLETTER_
@cindex _GLETTER_
@cindex _HLETTER_
@cindex _ILETTER_
@cindex _JLETTER_
@cindex _KLETTER_
@cindex _LLETTER_
@cindex _MLETTER_
@cindex _NLETTER_
@cindex _OLETTER_
@cindex _PLETTER_
@cindex _QLETTER_
@cindex _RLETTER_
@cindex _SLETTER_
@cindex _TLETTER_
@cindex _ULETTER_
@cindex _VLETTER_
@cindex _WLETTER_
@cindex _XLETTER_
@cindex _YLETTER_
@cindex _ZLETTER_
@cindex _0LETTER_
@cindex _1LETTER_
@cindex _2LETTER_
@cindex _3LETTER_
@cindex _4LETTER_
@cindex _5LETTER_
@cindex _6LETTER_
@cindex _7LETTER_
@cindex _8LETTER_
@cindex _9LETTER_

@cindex _AURL_
@cindex _BURL_
@cindex _CURL_
@cindex _DURL_
@cindex _EURL_
@cindex _FURL_
@cindex _GURL_
@cindex _HURL_
@cindex _IURL_
@cindex _JURL_
@cindex _KURL_
@cindex _LURL_
@cindex _MURL_
@cindex _NURL_
@cindex _OURL_
@cindex _PURL_
@cindex _QURL_
@cindex _RURL_
@cindex _SURL_
@cindex _TURL_
@cindex _UURL_
@cindex _VURL_
@cindex _WURL_
@cindex _XURL_
@cindex _YURL_
@cindex _ZURL_
@cindex _0URL_
@cindex _1URL_
@cindex _2URL_
@cindex _3URL_
@cindex _4URL_
@cindex _5URL_
@cindex _6URL_
@cindex _7URL_
@cindex _8URL_
@cindex _9URL_

@cindex _ACOUNT_
@cindex _BCOUNT_
@cindex _CCOUNT_
@cindex _DCOUNT_
@cindex _ECOUNT_
@cindex _FCOUNT_
@cindex _GCOUNT_
@cindex _HCOUNT_
@cindex _ICOUNT_
@cindex _JCOUNT_
@cindex _KCOUNT_
@cindex _LCOUNT_
@cindex _MCOUNT_
@cindex _NCOUNT_
@cindex _OCOUNT_
@cindex _PCOUNT_
@cindex _QCOUNT_
@cindex _RCOUNT_
@cindex _SCOUNT_
@cindex _TCOUNT_
@cindex _UCOUNT_
@cindex _VCOUNT_
@cindex _WCOUNT_
@cindex _XCOUNT_
@cindex _YCOUNT_
@cindex _ZCOUNT_
@cindex _0COUNT_
@cindex _1COUNT_
@cindex _2COUNT_
@cindex _3COUNT_
@cindex _4COUNT_
@cindex _5COUNT_
@cindex _6COUNT_
@cindex _7COUNT_
@cindex _8COUNT_
@cindex _9COUNT_

Here is an example template:

@example
<title>Alphabetical Navigation</title>

<h3>Alphabetical Navigation</h3>

_A_ _B_ _C_ _D_ _E_ _F_ _G_ _H_ _I_ _J_ _K_ _L_ <p>
_M_ _N_ _O_ _P_ _Q_ _R_ _S_ _T_ _U_ _V_ _W_ _X_ <p>
_Y_ _Z_ _0_ _1_ _2_ _3_ _4_ _5_ _6_ _7_ _8_ _9_ <p>
@end example

@table @samp
@item Tags

In the following tags description, @strong{[A-Z0-9]} stands for 
all the tags generated by replacing the expression in brackets with
any letter in the specified interval.

@table @samp
@item _[A-Z0-9]_
The letter in uppercase, wrapped in an hypertext link giving access to
the list of records starting with this letter in the catalog.
If there are not records starting with this letter in the catalog, the
letter is not associated with an hypertext link.

@item _[A-Z0-9]LETTER_
The letter in uppercase if there are records starting with this letter
in the catalog (A, B, ...). 
The letter in uppercase followed by @strong{0} (A0, B0, ...)
if there are no records starting with this letter in the catalog.

@item _[A-Z0-9]COUNT_
The number of records starting with the letter in the catalog.

@item _[A-Z0-9]URL_
The URL to display all the records of the catalog starting with this letter.
If there are no entries in the catalog for this letter, the special letter
@strong{none} is used and triggers an appriopriate warning message when hit.

@end table

@end table

@node calpha.html, cedit.html, calpha_root.html, Catalog template files
@section calpha.html

Leaf node of alphabetical navigation.

@cindex Leaf node of alphabetical navigation
@cindex Alphabetical navigation leaf node
@cindex calpha.html

Here is an example template:

@example
<title>Alphabetical Navigation _LETTER_</title>

<h3>Alphabetical Navigation _LETTER_</h3>

<table border=1>
<!-- start entry -->
<tr>_DEFAULTROW_</tr>
<!-- end entry --> 
</table>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@table @samp

@item Parts
Each record found is displayed using the standard method,
@xref{Record list part,,@code{Record list part}}.

The result is paginated, @xref{Multipage results template,,@code{Multipage results template}}.

@item Tags

@table @samp
@item _LETTER_
The initial letter of the record being displayed.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@end table

@node cedit.html, cbrowse_root.html, calpha.html, Catalog template files
@section cedit.html

Catalog edition.

@cindex Catalog edition
@cindex cedit.html

Here is an example template:

@example
<title>Edit category _CATEGORY_</title>

<center><h3><font color=red>_COMMENT_</font></h3></center>
<h3>Edit category _CATEGORY_</h3> 
<a href='_CENTRYINSERT_'><img src=_HTMLPATH_/images/new.gif alt='Insert a new record and link it to this category' border=0></a>
<a href='_CENTRYSELECT_'><img src=_HTMLPATH_/images/link.gif alt='Link an existing record to this category' border=0></a>
<a href='_CATEGORYINSERT_'><img src=_HTMLPATH_/images/open.gif alt='Create a sub category' border=0></a>
<a href='_CATEGORYSYMLINK_'><img src=_HTMLPATH_/images/plus.gif alt='Create a symbolic link to another category' border=0></a>
<a href='_CONTROLPANEL_'><img src=_HTMLPATH_/images/control.gif alt='Control panel' border=0></a>
<p>
<p>
_PATH_
<p>

<!-- start categories -->
<h3>Sub categories</h3>
<table>
<!-- params 'style' => 'table', 'columns' => 2 -->
<!-- start row --> 
<tr>
<!-- start entry -->
<td> _LINKS_ <a href='_URL_'>_NAME_</a> (_COUNT_) </td>
<!-- end entry -->
</tr>
<!-- end row --> 
</table>
<!-- end categories -->
<p>

<h3>Records in this category</h3>
<!-- start entry -->
<table border=1><tr><td>_LINKS_</td> _DEFAULTROW_<tr></table>
<p>
<!-- end entry -->

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@table @samp

@item Parts

The general structure of the parts is as follows:

@example
...
<!-- start categories -->
Sub categories as @strong{Record list part}.
<!-- end categories -->
...
Catalog entries as @strong{Record list part}.

<!-- start symlink -->
...
<!-- end symlink -->

@end example

The @strong{symlink} part is only shown in symbolic link selection context.

Each record found is displayed using the standard method,
@xref{Record list part,,@code{Record list part}}.

The result is paginated, @xref{Multipage results template,,@code{Multipage results template}}.

@item Tags 

@table @samp
@cindex _COMMENT_
@item _COMMENT_
A report from the action that displayed the template.

@cindex _PATH_
@item _PATH_
Full path of the current category, as built by the navigation of the user,
@xref{Catalog configuration file, ,@code{Catalog configuration file}}.
May not be the shortest path.

@cindex _CATEGORY_
@item _CATEGORY_
The name of the current category.

@cindex _CENTRYINSERT_
@item _CENTRYINSERT_
URL to create a new record in the catalogued table and link it to the
current category.

@cindex _CENTRYSELECT_
@item _CENTRYSELECT_
URL to select an existing record in the catalogued table and link it to the
current category.

@cindex _CATEGORYINSERT_
@item _CATEGORYINSERT_
URL to create a new category that will appear as a sub category of the
current category. 

@cindex _CATEGORYSYMLINK_
@item _CATEGORYSYMLINK_
URL to select an existing category and link it as a sub category of the
current category.

@cindex _ROOT_
@item _ROOT_
URL to display the root of the catalog.

@cindex _CONTROLPANEL_
@item _CONTROLPANEL_
URL to display the control panel of the @strong{Catalog} software, 
@xref{ccontrol_panel.html, ,@code{ccontrol_panel.html}}.

@end table

@item Tags in categories part

The tags are in the @strong{Record list} subpart.
The table used is @strong{catalog_category_<name>}, @xref{catalog_category_<name>, ,@code{catalog_category_<name>}}.

@table @samp

@item _LINKS_
Replaced by a link to remove the corresponding sub category from the catalog.

@item _URL_
Replaced by a link to navigate the corresponding sub category.

@item _NAME_
Name of the sub category.

@item _COUNT_
Total number of records stored in this category and all its descendants.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@item Tags in record list part

@table @samp

@item _LINKS_
Replaced by the following links:
@table @samp

@item Unlink entry
Destroy the link between the corresponding record and the current category.
The record is not destroyed, other links are preserved.

@item Remove entry
Destroy all the links in all categories of the catalog and remove the
corresponding record from the catalogued table.

@end table

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@item Tags in symlink part

@table @samp

@item _CATEGORYSYMLINK_
URL to select the current category and return to the caller.

@end table


@end table

@node cbrowse_root.html, cbrowse.html, cedit.html, Catalog template files
@section cbrowse_root.html

Display the root of the theme catalog. The handling of this template is
strictly identical to cedit.html, @xref{cedit.html, ,@code{cedit.html}}.

@cindex Catalog root node
@cindex Root node of catalog
@cindex Display root node of catalog
@cindex cbrowse_root.html

Here is an example template:

@example
<title>Root</title>

<h3>Root</h3>

<!-- start categories -->
<h3>Sub categories</h3>
<ul>
<!-- start entry -->
<li> <a href='_URL_'>_NAME_</a> (_COUNT_)
<!-- end entry -->
</ul>
<!-- end categories -->
<p>
<!-- start entry -->
<p> <table border=1><tr>_DEFAULTROW_<tr></table>
<!-- end entry -->

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@node cbrowse.html, csearch.html, cbrowse_root.html, Catalog template files
@section cbrowse.html

Display an internal node of the theme catalog. The handling of this template is
strictly identical to cedit.html, @xref{cedit.html, ,@code{cedit.html}}.

@cindex Catalog node
@cindex Node of catalog
@cindex Display node of catalog
@cindex cbrowse.html

Here is an example template:

@example
<title>_CATEGORY_</title>

<h3>_CATEGORY_</h3>
<p>
_PATH_
<p>

<!-- start categories -->
<h3>Sub categories</h3>
<ul>
<!-- start entry -->
<li> <a href='_URL_'>_NAME_</a> (_COUNT_)
<!-- end entry -->
</ul>
<!-- end categories -->
<p>
<!-- start entry -->
<p> <table border=1><tr>_DEFAULTROW_<tr></table>
<!-- end entry -->

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@table @samp

@end table

@node csearch.html, cdate_default.html, cbrowse.html, Catalog template files
@section csearch.html

Display the result of a full text search on a thematic catalog.

@cindex Catalog full text search
@cindex Full text search template
@cindex csearch.html

Here is an example template:

@example
<title>Search results for _TEXT_</title>

<center>
<form action=_SCRIPT_ method=POST>
_HIDDEN_
<input type=text size=40 name=text value='_TEXT-QUOTED_'>
<input type=submit value='search'><br>
_WHAT-MENU_
</form>
</center>
<!-- start categories -->
<center>Categories matching <b>_TEXT_</b> (_COUNT_)</center>
<ul>
<!-- start entry -->
<li> <a href=_URL_>_PATHNAME_</a>
<!-- end entry -->
</ul>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
<!-- end categories -->
<!-- start nocategories -->
<center>No category matches the search criterion</center>
<!-- end nocategories -->

<!-- start records -->

<center>Records matching <b>_TEXT_</b> (_COUNT_)</center>

<table border=1>
<!-- start entry -->

<!-- start category -->
<tr><td colspan=20><a href=_URL_>_PATHNAME_</a></td></tr>
<!-- end category -->

<tr>_DEFAULTROW_</tr>
<!-- end entry --> 
</table>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
<!-- end records -->
<!-- start norecords -->
<center>No record matches the search criterion</center>
<!-- end norecords -->
@end example

@table @samp

@item Parts

  @table @samp
  @cindex categories part
  @item categories
Shown if a match is found in the categories and the @strong{what} parameter is not set or set to
@strong{categories}. The list of categories found is displayed according to the rules described in
Record list part, @xref{Record list part,,@code{Record list part}}. 
A pager may also be included, @xref{Multipage results template,,@code{Multipage results template}}.

    @table @samp
    
    @cindex _URL_
    @item _URL_
    The URL to display the category found.

    @cindex _PATHNAME_
    @item _PATHNAME_
    The full path name of the category found

    @cindex _COUNT_
    @item _COUNT_
    The total number of categories found.

    @cindex _TEXT_
    @item _TEXT_
    The original query.

    @cindex _TEXT-QUOTED_
    @item _TEXT-QUOTED_
    The original query with HTML reserved characters quoted.
    
    @end table

  @cindex nocategories part
  @item nocategories
Shown if no category is found and the @strong{what} parameter is set to @strong{categories}.

  @cindex records part
  @item records
If the @strong{what} parameter is set to @strong{records}, this part is shown if a match is found
in the records. If the @strong{what} parameter is no set, this part is shown if no match is found
in the categories and a match is found in the records.
The list of categories found is displayed according to the rules described in
Record list part, @xref{Record list part,,@code{Record list part}}. The fields shown are all the
fields of the table associated with the catalog, unless specified otherwise in the @strong{catalog.conf}
configuration file, @xref{Catalog configuration file,,@code{Catalog configuration file}}. 
A pager may also be included, @xref{Multipage results template,,@code{Multipage results template}}.

    @table @samp
    
    @cindex _COUNT_
    @item _COUNT_
    The total number of records found.

    @cindex _TEXT_
    @item _TEXT_
    The original query.

    @cindex _TEXT-QUOTED_
    @item _TEXT-QUOTED_
    The original query with HTML reserved characters quoted.
    
    @end table

  @cindex category part
  @item category
This part is a mandatory sub part of the part that displays an individual record in the @strong{records}
part. The exact location of this part depends on the Record list part display used, 
@xref{Record list part,,@code{Record list part}}. It is displayed once for the first record. It is then
displayed only when the category of the record differ from the previous record shown.

    @table @samp
    
    @cindex _URL_
    @item _URL_
    The URL to display the category of the record.

    @cindex _PATHNAME_
    @item _PATHNAME_
    The full path name of the category of the record.

    @end table

  @cindex norecords part
  @item norecords
If the @strong{what} parameter is set to @strong{records}, this part is shown if no record is found.
If the @strong{what} parameter is not set, this part is shown if no category is found and no record is found.

  @end table

@item Tags

  @table @samp

  @cindex _COUNT_
  @item _COUNT_
  The total number of records or categories found.

  @cindex _TEXT_
  @item _TEXT_
  The original query.

  @cindex _TEXT-QUOTED_
  @item _TEXT-QUOTED_
  The original query with HTML reserved characters quoted.

  @cindex _HIDDEN_
  @item _HIDDEN_
List of hidden fields necessary to perform a new search. Must
be included in a @code{form}. It includes the @strong{mode}, @strong{boolean}, @strong{context} and
@strong{name} parameters.

  @cindex _WHAT-MENU_
  @item _WHAT-MENU_
A popup menu to select the @strong{what} parameter.

  @end table

@end table

@node cdate_default.html, cdestroy.html, csearch.html, Catalog template files
@section cdate_default.html

Default template for display of date catalog nodes.

@cindex Catalog date node
@cindex Node of date catalog
@cindex Display node of date catalog
@cindex cdate_default.html

Here is an example template:

@example
<html>
<body bgcolor=#ffffff>
<title>Date catalog</title>
<!-- start years -->
  <a href=_YEARLINK_>_YEARFORMATED_</a> (_COUNT_)

  <blockquote>
  <!-- start months -->
    <!-- params format => '%M' -->
    <a href=_MONTHLINK_>_MONTHFORMATED_</a> (_COUNT_)

    <ul>
    <!-- start days -->
      <!-- params format => '%W, %d' -->
      <li> <a href=_DAYLINK_>_DAYFORMATED_</a> (_COUNT_)
    <!-- end days -->
    </ul>

  <!-- end months -->
  </blockquote>

<!-- end years -->

<!-- start records -->
Records
<!-- start entry -->
<p> <table border=1><tr>_DEFAULTROW_</tr></table>
<!-- end entry -->

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->

<!-- end records -->
</html>
@end example

@table @samp

@item Parts

The @strong{months}, @strong{days}, @strong{records} and @strong{pager}
can be omitted, if appropriate.

  @table @samp
@cindex years
  @item years
Repeated for each year for which there is at least one record
in the period involved.

@cindex months
  @item months
Repeated for each month for which there is at least one record
within the current year.

@cindex days
  @item days
Repeated for each day for which there is at least one record
within the current month of the current year.

@cindex records
  @item records
This part is included only if there is at least one record to display.
It can be omitted if you only want to display dates and not records.
The records displayed are extracted from the table associated with the
current catalog.
The inner parts of the @strong{records} part follows the rules described
in Record list part, @xref{Record list part,,@code{Record list part}}.
A pager may also be included, @xref{Multipage results template,,@code{Multipage results template}}.

  @end table

@item Date format
@cindex Date format
@cindex Format date in date catalog

The @strong{years}, @strong{months} and @strong{days} parts can contain
a date format parameter. The form of the date format parameter is :

@example
<!-- params format => '<MySQL date format>' -->
@end example

The @strong{MySQL date format} string can be any format acceptable for the
@strong{date_format} function of MySQL. See the MySQL documentation for more
information.

@item Tags

  @table @samp

@cindex _COUNT_
  @item _COUNT_
The total number of records for the year (in @strong{years} part), the
month (in @strong{months} part) or the day (in @strong{days} part).

@cindex _YEARLINK_
  @item _YEARLINK_
A link to display only the period from January 1st 00:00 to December 31 23:59
of the current year.

@cindex _YEARFORMATED_
  @item _YEARFORMATED_
The current year formated according to the date format specified (see above).
If no date format is specified the year is formated with the string @strong{%Y}.

@cindex _MONTHLINK_
  @item _MONTHLINK_
A link to display only the period from the first day current month 00:00h
to last day of the month 23:59h.

@cindex _MONTHFORMATED_
  @item _MONTHFORMATED_
The current month formated according to the date format specified (see above).
If no date format is specified the month is formated with the string 
@strong{%M %Y}.

@cindex _DAYLINK_
  @item _DAYLINK_
A link to display only the period from the current day 00:00h
to 23:59h.

@cindex _DAYFORMATED_
  @item _DAYFORMATED_
The current day formated according to the date format specified (see above).
If no date format is specified the day is formated with the string 
@strong{%d %M %Y}.

  @end table

@end table

@node cdestroy.html, centryremove_all.html, cdate_default.html, Catalog template files
@section cdestroy.html

First step of complete catalog destruction.

@cindex Catalog destroy
@cindex Destroy a catalog
@cindex cdestroy.html

Here is an example template:

@example
<body bgcolor=#ffffff>

<center>

<h3>Confirm removal of catalog _NAME_</h3>

<form action=_SCRIPT_ method=POST>
<input type=submit name=remove value=remove>
_HIDDEN_
</form>

</center>
@end example

@table @samp

@item Tags
@table @samp
@item _NAME_
Name of the catalog.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@end table

@end table

@node centryremove_all.html, catalog_theme_insert.html, cdestroy.html, Catalog template files
@section centryremove_all.html

First step of complete removal of catalogued record.

@cindex Catalog entry removal
@cindex Destroy a catalog entry
@cindex centryremove_all.html

Here is an example template:

@example
<body bgcolor=#ffffff>

<center>

<h3>Confirm removal of record from  _TABLE_</h3>

<form action=_SCRIPT_ method=POST>
<input type=submit name=remove value=remove>
_HIDDEN_
</form>

</center>
@end example

@table @samp

@item Tags
@table @samp
@item _NAME_
Name of the catalog.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@end table

@end table

@node catalog_theme_insert.html, catalog_theme_edit.html, centryremove_all.html, Catalog template files
@section catalog_theme_insert.html

Create a thematic catalog. When the user click on the submit button
the parameters @strong{tablename}, @strong{navigation} and @strong{name}
must be filled.

@cindex Thematic catalog creation template
@cindex Catalog creation (thematic)
@cindex catalog_theme_insert.html

Here is an example template:

@example
<title>Create _NAVIGATION_ catalog on table _TABLENAME_</title>

<h3>Create _NAVIGATION_ catalog on table _TABLENAME_</h3>

<form action=_SCRIPT_ method=POST>
_HIDDEN_
<input type=hidden name=tablename value=_TABLENAME_>
<input type=hidden name=navigation value=_NAVIGATION_>
<table>
<tr><td><b>Catalog name*</b></td><td><input type=text name=name></td></tr>
<tr><td><b>ORDER BY</b></td><td><input type=text name=corder size=60></td></tr>
<tr><td><b>WHERE</b></td><td><input type=text name=cwhere size=60></td></tr>
<tr><td><b>Dump path</b></td><td><input type=text name=dump size=60></td></tr>
<tr><td><b>Dump location</b></td><td><input type=text name=dumplocation size=60></td></tr>
<tr><td><b>Options</b></td><td>_INFO-CHECKBOX_</td></tr>
</table>
<input type=submit value='Create it!'>

</form>
@end example

@table @samp

@item Tags
@table @samp

@cindex _NAVIGATION_
@item _NAVIGATION_
Always set to @strong{theme}.

@cindex _TABLENAME_
Set the the value of the @strong{tablename} cgi-bin parameter.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.
The table used is @strong{catalog}, for a list of the fields
available in this table, @xref{catalog,,@code{catalog}}.

@end table

@end table

@node catalog_theme_edit.html, catalog_alpha_insert.html, catalog_theme_insert.html, Catalog template files
@section catalog_theme_edit.html

Edit the properties of a thematic catalog. 

@cindex Thematic catalog properties template
@cindex Catalog edit properties (thematic)
@cindex catalog_theme_edit.html

Here is an example template:

@example
<title>Edit _NAVIGATION_ catalog _NAME_</title>
<h3>Edit _NAVIGATION_ catalog _NAME_</h3>

_EDITCOMMENT_
<form action=_SCRIPT_ method=POST>
<input type=submit name=update value=update>
_HIDDEN_
<table>
<tr><td><b>Table name</b></td><td>_TABLENAME_</td></tr>
<tr><td><b>ORDER BY</b></td><td><input type=text name=corder size=60 value='_CORDER-QUOTED_'></td></tr>
<tr><td><b>WHERE</b></td><td><input type=text name=cwhere size=60 value='_CWHERE-QUOTED_'></td></tr>
<tr><td><b>Dump path</b></td><td><input type=text name=dump size=60 value='_DUMP-QUOTED_'></td></tr>
<tr><td><b>Dump location</b></td><td><input type=text name=dumplocation size=60 value='_DUMPLOCATION-QUOTED_'></td></tr>
<tr><td><b>Options</b></td><td>_INFO-CHECKBOX_</td></tr>
<tr><td><b>Created</b></td><td>_CREATED_</td></tr>
<tr><td><b>Last modified</b></td><td>_MODIFIED_</td></tr>
</table>
</form>
@end example

@table @samp

@item Tags
@table @samp
@item _EDITCOMMENT_
The content of the @strong{comment} cgi-bin parameter.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.
The table used is @strong{catalog}, for a list of the fields
available in this table, @xref{catalog,,@code{catalog}}.

@end table

@end table

@node catalog_alpha_insert.html, catalog_alpha_edit.html, catalog_theme_edit.html, Catalog template files
@section catalog_alpha_insert.html

Create a alphabetical catalog. When the user click on the submit button
the parameters @strong{tablename}, @strong{navigation}, @strong{fieldname}
and @strong{name} must be filled.

@cindex Alphabetical catalog creation template
@cindex Catalog creation (alphabetical)
@cindex catalog_alpha_insert.html

Here is an example template:

@example
<title>Create _NAVIGATION_ catalog on table _TABLENAME_</title>

<h3>Create _NAVIGATION_ catalog on table _TABLENAME_</h3>

<form action=_SCRIPT_ method=POST>
_HIDDEN_
<input type=hidden name=tablename value=_TABLENAME_>
<input type=hidden name=navigation value=_NAVIGATION_>
<table>
<tr><td><b>Catalog name*</b></td><td><input type=text name=name></td></tr>
<tr><td><b>Field name*</b></td><td><input type=text name=fieldname></td></tr>
<tr><td><b>ORDER BY</b></td><td><input type=text name=corder size=60></td></tr>
<tr><td><b>WHERE</b></td><td><input type=text name=cwhere size=60></td></tr>
<tr><td><b>Options</b></td><td>_INFO-CHECKBOX_</td></tr>
</table>
<input type=submit value='Create it!'>

</form>
@end example

@table @samp

@item Tags
@table @samp

@cindex _NAVIGATION_
@item _NAVIGATION_
Always set to @strong{alpha}.

@cindex _TABLENAME_
Set the the value of the @strong{tablename} cgi-bin parameter.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.
The table used is @strong{catalog}, for a list of the fields
available in this table, @xref{catalog,,@code{catalog}}.

@end table

@end table

@node catalog_alpha_edit.html, catalog_date_insert.html, catalog_alpha_insert.html, Catalog template files
@section catalog_alpha_edit.html

Edit the properties of an alphabetical catalog. 

@cindex Alphabetical catalog properties template
@cindex Catalog edit properties (alphabetical)
@cindex catalog_alpha_edit.html

Here is an example template:

@example
<title>Edit _NAVIGATION_ catalog _NAME_</title>
<h3>Edit _NAVIGATION_ catalog _NAME_</h3>

_EDITCOMMENT_
<form action=_SCRIPT_ method=POST>
<input type=submit name=update value=update>
_HIDDEN_
<table>
<tr><td><b>Table name</b></td><td>_TABLENAME_</td></tr>
<tr><td><b>Field name</b></td><td><input type=text name=fieldname value='_FIELDNAME_'></td></tr>
<tr><td><b>ORDER BY</b></td><td><input type=text name=corder size=60 value='_CORDER-QUOTED_'></td></tr>
<tr><td><b>WHERE</b></td><td><input type=text name=cwhere size=60 value='_CWHERE-QUOTED_'></td></tr>
<tr><td><b>Options</b></td><td>_INFO-CHECKBOX_</td></tr>
<tr><td><b>Last cache update</b></td><td><input type=text name=updated value='_UPDATED_'</td></tr>
<tr><td><b>Created</b></td><td>_CREATED_</td></tr>
<tr><td><b>Last modified</b></td><td>_MODIFIED_</td></tr>
</table>
</form>
@end example

@table @samp

@item Tags
@table @samp
@item _EDITCOMMENT_
The content of the @strong{comment} cgi-bin parameter.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.
The table used is @strong{catalog}, for a list of the fields
available in this table, @xref{catalog,,@code{catalog}}.

@end table

@end table

@node catalog_date_insert.html, catalog_date_edit.html, catalog_alpha_edit.html, Catalog template files
@section catalog_date_insert.html

Create a chronological catalog. When the user click on the submit button
the parameters @strong{tablename}, @strong{navigation}, @strong{fieldname}
and @strong{name} must be filled.

@cindex Chronological catalog creation template
@cindex Catalog creation (chronological)
@cindex catalog_date_insert.html

Here is an example template:

@example
<title>Create _NAVIGATION_ catalog on table _TABLENAME_</title>

<h3>Create _NAVIGATION_ catalog on table _TABLENAME_</h3>

<form action=_SCRIPT_ method=POST>
_HIDDEN_
<input type=hidden name=tablename value=_TABLENAME_>
<input type=hidden name=navigation value=_NAVIGATION_>
<table>
<tr><td><b>Catalog name*</b></td><td><input type=text name=name></td></tr>
<tr><td><b>Field name*</b></td><td><input type=text name=fieldname></td></tr>
<tr><td><b>ORDER BY</b></td><td><input type=text name=corder size=60></td></tr>
<tr><td><b>WHERE</b></td><td><input type=text name=cwhere size=60></td></tr>
<tr><td><b>Options</b></td><td>_INFO-CHECKBOX_</td></tr>
</table>
<input type=submit value='Create it!'>

</form>
@end example

@table @samp

@item Tags
@table @samp

@cindex _NAVIGATION_
@item _NAVIGATION_
Always set to @strong{date}.

@cindex _TABLENAME_
Set the the value of the @strong{tablename} cgi-bin parameter.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.
The table used is @strong{catalog}, for a list of the fields
available in this table, @xref{catalog,,@code{catalog}}.

@end table

@end table

@node catalog_date_edit.html, cdump.html, catalog_date_insert.html, Catalog template files
@section catalog_date_edit.html

Edit the properties of a chronological catalog. 

@cindex Chronological catalog properties template
@cindex Catalog edit properties (chronological)
@cindex catalog_date_edit.html

Here is an example template:

@example
<title>Edit _NAVIGATION_ catalog _NAME_</title>
<h3>Edit _NAVIGATION_ catalog _NAME_</h3>

_EDITCOMMENT_
<form action=_SCRIPT_ method=POST>
<input type=submit name=update value=update>
_HIDDEN_
<table>
<tr><td><b>Table name</b></td><td>_TABLENAME_</td></tr>
<tr><td><b>Field name</b></td><td><input type=text name=fieldname value='_FIELDNAME_'></td></tr>
<tr><td><b>ORDER BY</b></td><td><input type=text name=corder size=60 value='_CORDER-QUOTED_'></td></tr>
<tr><td><b>WHERE</b></td><td><input type=text name=cwhere size=60 value='_CWHERE-QUOTED_'></td></tr>
<tr><td><b>Options</b></td><td>_INFO-CHECKBOX_</td></tr>
<tr><td><b>Last cache update</b></td><td><input type=text name=updated value='_UPDATED_'</td></tr>
<tr><td><b>Created</b></td><td>_CREATED_</td></tr>
<tr><td><b>Last modified</b></td><td>_MODIFIED_</td></tr>
</table>
</form>
@end example

@table @samp

@item Tags
@table @samp
@item _EDITCOMMENT_
The content of the @strong{comment} cgi-bin parameter.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.
The table used is @strong{catalog}, for a list of the fields
available in this table, @xref{catalog,,@code{catalog}}.

@end table

@end table

@node cdump.html, cimport.html, catalog_date_edit.html, Catalog template files
@section cdump.html

Ask for confirmation before dumping the content of a thematic catalog

@cindex Thematic catalog dump template
@cindex Catalog dump (thematic)
@cindex cdump.html

Here is an example template:

@example
<title>Dump _NAME_ catalog in HTML</title>

<h3>Dump _NAME_ catalog in HTML</h3>

<center><h3><font color=red>Warning! All files and subdirectories of the specified path will first be removed.</font></h3></center>
<form action=_SCRIPT_ method=POST>
_HIDDEN_
<table>
<tr><td><b>Full path name*</b></td><td><input type=text name=path size=50 value='_PATH_'></td></tr>
<tr><td><b>Location*</b></td><td><input type=text name=location size=50 value='_LOCATION_'></td></tr>
</table>
<input type=submit value='Dump it!'>

</form>
@end example

@table @samp

@item Tags
@table @samp

@cindex _HIDDEN_
@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@cindex _NAME_
@item _NAME_
Name of the catalog.

@cindex _PATH_
@item _PATH_
Full path name of the directory where the catalog will be dumped.

@cindex _LOCATION_
@item _LOCATION_
HTML base location used to navigate the dumped catalog. If _PATH_ is
something like /home/http/htdocs/directory, the location is likely to be
/directory.

@end table

@end table

@node cimport.html, cexport.html, cdump.html, Catalog template files
@section cimport.html

Query parameters for loading a thematic catalog from a file.

@cindex Thematic catalog load template
@cindex Catalog load (thematic)
@cindex cimport.html

Here is an example template:

@example
<title>Load a thematic catalog</title>
<form action=_SCRIPT_ method=POST>
<input type=hidden name=context value=cimport_confirm>
<table>
<tr><td><b>Catalog name</b></td><td><input type=text name=name value=_NAME_></td></tr>
<tr><td><b>File path</b></td><td><input type=text name=file></td></tr>
</table>
<input type=submit value='Load it!'>
</form>
@end example

@table @samp

@item Tags
@table @samp

@cindex _NAME_
@item _NAME_
Name of the catalog.

@end table

@end table

@node cexport.html,  , cimport.html, Catalog template files
@section cexport.html

Query parameters for unloading a thematic catalog to a file.

@cindex Thematic catalog unload template
@cindex Catalog unload (thematic)
@cindex cexport.html

Here is an example template:

@example
<title>Unload a thematic catalog</title>
<form action=_SCRIPT_ method=POST>
<input type=hidden name=context value=cexport_confirm>
<input type=hidden name=name value=_NAME_>
<table>
<tr><td><b>Catalog name</b></td><td>_NAME_</td></tr>
<tr><td><b>File path</b></td><td><input type=text name=file></td></tr>
</table>
<input type=submit value='Unload it!'>
</form>
@end example

@table @samp

@item Tags
@table @samp

@cindex _NAME_
@item _NAME_
Name of the catalog.

@end table

@end table

@node SQL template files, CGI introduction, Catalog template files, Top
@chapter SQL template files

@menu
* sqledit_search_form.html::    sqledit_search_form.html
* sqledit_sinsert_form.html::   sqledit_sinsert_form.html
* sqledit_edit.html::           sqledit_edit.html
* sqledit_search.html::         sqledit_search.html
* hook_search.html::            hook_search.html
* sqledit_remove.html::         sqledit_remove.html
* sqledit_remove_confirm.html::  sqledit_remove_confirm.html
* error.html::                  error.html
* sqledit_requests.html::       sqledit_requests.html
@end menu

@node sqledit_search_form.html, sqledit_sinsert_form.html, SQL template files, SQL template files
@section sqledit_search_form.html

@cindex sqledit_search_form.html
@cindex search form template
@cindex template for search form

@cindex _TABLE_
@cindex _HIDDEN_
@cindex _DEFAULT_

@table @samp
@item Example
@example
<title>Search form for _TABLE_</title>

<h3>Search form for _TABLE_</h3>

<form action=_SCRIPT_ method=POST>
<input type=submit value=search>
_HIDDEN_
<table>
_DEFAULT_
</table>

</form>
@end example

@item Tags

@table @samp
@item _TABLE_
The name of the database table.

@item _HIDDEN_
List of hidden fields necessary to perform the search. Must
be included in each @code{form}.

@item _DEFAULT_
A two column table showing the name of the field and an input area, 
@xref{Database table tags, ,@code{Database table tags}}. The input area
is filled with the values from the cgi-bin parameters, if any. If no
value is specified the input area is left undefined, the default value
of the field, if any, is not used.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULT_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@end table

@node sqledit_sinsert_form.html, sqledit_edit.html, sqledit_search_form.html, SQL template files
@section sqledit_sinsert_form.html

@cindex sqledit_sinsert_form.html
@cindex insert form template
@cindex template for insert form

@cindex _TABLE_
@cindex _HIDDEN_
@cindex _DEFAULT_

@table @samp
@item Example
@example
<title>Insert form for _TABLE_</title>

<h3>Insert form for _TABLE_</h3>

<form action=_SCRIPT_ method=POST  enctype=multipart/form-data>
<input type=submit value=insert>
_HIDDEN_
<table>
_DEFAULT_
</table>

</form>
@end example

Note the @code{enctype=multipart/form-data}, necessary if the table contains
blobs, optional otherwise.

@item Tags

@table @samp
@item _TABLE_
The name of the database table.

@item _HIDDEN_
List of hidden fields necessary to perform the insertion. Must
be included in each @code{form}.

@item _DEFAULT_
A two column table showing the name of the field and an input area, 
@xref{Database table tags, ,@code{Database table tags}}. The input area
is filled with the values from the cgi-bin parameters, if any. If no
value is specified the input area is set with the default value as defined
in the database.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULT_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@end table

@node sqledit_edit.html, sqledit_search.html, sqledit_sinsert_form.html, SQL template files
@section sqledit_edit.html

@cindex sqledit_edit.html
@cindex record edit template
@cindex template for record edit

@cindex _TABLE_
@cindex _HIDDEN_
@cindex _DEFAULT_
@cindex _EDITCOMMENT_

@table @samp
@item Example
@example
<title>Edit form for _TABLE_</title>

_EDITCOMMENT_
<form action=_SCRIPT_ method=POST enctype=multipart/form-data>
<input type=submit name=update value=update>
_HIDDEN_
<table>
_DEFAULT_
</table>
</form>
@end example

Note the @code{enctype=multipart/form-data}, necessary if the table contains
blobs, optional otherwise.

@item Tags

@table @samp
@item _TABLE_
The name of the database table.

@item _EDITCOMMENT_
A small comment from the action taken before the display of the template.

@item _HIDDEN_
List of hidden fields necessary to perform the update. Must
be included in each @code{form}.

@item _DEFAULT_
A two column table showing the name of the field and an input area, 
@xref{Database table tags, ,@code{Database table tags}}. The input area
is filled with the values from the cgi-bin parameters, if any. If no
value is specified the input area is set with the default value as defined
in the database.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULT_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@end table

@node sqledit_search.html, hook_search.html, sqledit_edit.html, SQL template files
@section sqledit_search.html

@cindex sqledit_search.html
@cindex search results template
@cindex template for search results

@cindex _TABLE_
@cindex _DEFAULTROW_
@cindex _DEFAULTTITLE_
@cindex _LINKS_
@cindex _MAXPAGES_
@cindex _PAGES_

@table @samp
@item Example
@example
<title>Search _TABLE_</title>

<h3>_TABLE_</h3>

<table border=1>
<!-- start entry -->
<tr>_MARGINTABLE_ _DEFAULTTITLE_</tr>
<tr>_MARGIN_ _LINKS_</tr>
<tr>_MARGIN_ _DEFAULTROW_</tr>
<!-- end entry -->
</table>
<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@item Parts

@table @samp

@item entry
This part is repeated for each record found. For more information about
which records from which tables are displayed,
@xref{Search table (search), ,@code{Search table (search)}}.

@item pager
@xref{Multipage results template, ,@code{Multipage results template}}.

@end table

@item Tags

@table @samp
@item _TABLE_
The name of the database table.

@item _MARGINTABLE_
Indentation including the name of the table.

@item _MARGIN_
Indentation.

@item _DEFAULTTITLE_
Cells listing the name of all the columns of the database. The
order of the labels is the same as the order of the values from
@code{_DEFAULTROW_}. The background of the cells is gray to 
improve readability.

@item _LINKS_
Hypertext links leading to actions on the displayed rows. 

@table @samp
@item Remove
@xref{Remove confirm (remove_confirm), ,@code{Remove confirm (remove_confirm)}}.
@item Edit
@xref{Record edit form (edit), ,@code{Record edit form (edit)}}.
@end table

@item _DEFAULTROW_
Cells listing the values of all the fields of the current row. 
The
order of the labels is the same as the order of the values from
@code{_DEFAULTTITLE_}.

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@end table

@node hook_search.html, sqledit_remove.html, sqledit_search.html, SQL template files
@section hook_search.html

@cindex hook_search.html
@cindex full text search results template
@cindex full text template for search results

@cindex _TABLE_
@cindex _DEFAULTROW_
@cindex _MAXPAGES_
@cindex _PAGES_

@table @samp
@item Example
@example
<title>Search _TABLE_</title>

<h3>_TABLE_</h3>

<table border=1>
<!-- start entry -->

<!-- start table1,table2 -->
<tr>_DEFAULTROW_</tr>
<!-- end table1,table2 -->

<!-- start table2,table3 -->
<tr>_DEFAULTROW_</tr>
<!-- end table2,table3 -->
...

<!-- end entry -->
</table>
<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@item Parts

@table @samp

@item entry
This part is repeated for each record found. For more information about
which records from which tables are displayed,
@xref{Search table (search), ,@code{Search table (search)}}.

The sub parts of @strong{entry} have a name built from the list of tables
for which a match was found. Most of the time the list only contains
one table name,
@xref{Hook Fulcrum configuration file, ,@code{Hook Fulcrum configuration file}}.

@item pager
@xref{Multipage results template, ,@code{Multipage results template}}.

@end table

@item Tags

@table @samp
@item _TABLE_
The name of the database table.

@item _DEFAULTROW_
Cells listing the values of all the fields of the current row. 

@item table tags
All the automaticaly generated tags for the database table are
available, provided that @code{_DEFAULTROW_} was not found in the
template, @xref{Database table tags, ,@code{Database table tags}}.

@end table

@end table

@node sqledit_remove.html, sqledit_remove_confirm.html, hook_search.html, SQL template files
@section sqledit_remove.html

@cindex sqledit_remove.html
@cindex record removal template
@cindex template for record removal

@cindex _TABLE_
@cindex _HIDDEN_

@table @samp
@item Example
@example
<body bgcolor=#ffffff>

<center>

<h3>Confirm removal of record from  _TABLE_</h3>

<form action=_SCRIPT_ method=POST>
<input type=submit name=remove value=remove>
<input type=hidden name=context value=remove_confirm>
_HIDDEN_
</form>

</center>
@end example

@item Tags

@table @samp
@item _TABLE_
The name of the database table.

@item _HIDDEN_
List of hidden fields necessary to perform the removal. Must
be included in each @code{form}.

@end table

@end table

@node sqledit_remove_confirm.html, error.html, sqledit_remove.html, SQL template files
@section sqledit_remove_confirm.html

@cindex sqledit_remove_confirm.html
@cindex record removal confirmation template
@cindex template for record removal confirmation

@cindex _TABLE_

@table @samp
@item Example
@example
<body bgcolor=#ffffff>

<center>

<h3>Record removed from  _TABLE_</h3>

</center>
@end example

@item Tags

@table @samp
@item _TABLE_
The name of the database table.

@end table

@end table

@node error.html, sqledit_requests.html, sqledit_remove_confirm.html, SQL template files
@section error.html

@cindex error.html
@cindex error message template
@cindex template for error message

@cindex _MESSAGE_

@table @samp
@item Example
@example
<body bgcolor=#ffffff>
<title>Error</title>
<center><h3>
Error<p>
_MESSAGE_
</center></h3>
@end example

@item Tags

@table @samp
@item _MESSAGE_
The text of the error message.

@end table

@end table

@node sqledit_requests.html,  , error.html, SQL template files
@section sqledit_requests.html

@cindex sqledit_requests.html
@cindex request editor template
@cindex template for request editor

@cindex _SCRIPT_
@cindex _RTABLE_
@cindex _RWHERE-CODED_
@cindex _RLINKS_
@cindex _RORDER-CODED_
@cindex _LABEL_
@cindex _ROWID_
@cindex _SCRIPT_
@cindex _MAXPAGES_
@cindex _PAGES_

@table @samp
@item Example
@example
<title>Requests</title>

<h3>Requests</h3>

<table border=1>
<!-- start entry -->
<tr>
<td bgcolor=#c9c9c9>Search <a href='_SCRIPT_?context=search_form
    &table=_RTABLE_
    &limit=_RWHERE-CODED_
    &links_set=_RLINKS_
    &order=_RORDER-CODED_'>_LABEL_<a/></td>
<td><a href='_SCRIPT_?context=edit
    &table=sqledit_requests
    &primary=_ROWID_'>Edit<a/></td>
<td><a href='_SCRIPT_?context=remove
    &table=sqledit_requests
    &primary=_ROWID_'>Remove<a/></td>
</tr>
<!-- end entry -->
</table>
<p>
<a href='_SCRIPT_?context=insert_form
    &table=sqledit_requests'>Insert a request</a>
<br>
<a href='_SCRIPT_?context=search_form
    &table=sqledit_requests'>Search a request</a>
<br>

<!-- start pager -->
Number of pages _MAXPAGES_
<p>
_PAGES_
<!-- end pager -->
@end example

@item Parts

@table @samp

@item entry
This part is repeated for each request. 
@xref{Search table (search), ,@code{Search table (search)}}.

@item pager
@xref{Multipage results template, ,@code{Multipage results template}}.

@end table

@item Tags

Note that most of the following tags are indeed
fields of the @strong{sqledit_requests} table and may be 
substituted with all legal variations, 
@xref{Database table tags, ,@code{Database table tags}}.

@table @samp
@item _RTABLE_
Name of the table of the request.

@item _RWHERE_
Where clause of the request.

@item _RLINKS_
Relational scheme specification used to display records, pushed in the
@strong{links_set} parameter, @xref{Search table (search), ,@code{Search table (search)}}.

@item _RORDER_
Order by clause of the request.

@item _LABEL_
Textual label describing the purpose of the request.

@item _SCRIPT_
Absolute location of the cgi-bin script.

@end table

@end table

@node CGI introduction, Catalog CGI, SQL template files, Top
@chapter CGI introduction

The invocation style of cgi-bin programs is to specify the kind of action
to be taken using the @strong{context} parameter. This parameter may
be seen as the name of the function to call, the functionality to be
activated. It is therefore a mandatory parameter of all the cgi-bin
invocations.

Should you use the @strong{POST} or @strong{GET} method ? The library
works with both methods. Using only @strong{POST} or only @strong{GET} 
is recommended, however, because mixing the two may have surprising results
when navigator caches are used.

@menu
* Diagram::                     Diagram
* Notation::                    Notation
* Style parameter::             Style parameter
* Database table parameters::   Database table parameters
* Primary parameter::           Primary parameter
* Recursive CGI call::          Recursive CGI call
* CGI called with PATH_INFO::   CGI called with PATH_INFO
* Multipage results parameters::  Multipage results parameters
@end menu

@node Diagram, Notation, CGI introduction, CGI introduction
@section Diagram

At the beginning of each chapter describing a set of cgi-bin actions, a
diagram shows a box for each action. 
It describes the dependencies between the different actions
of the cgi-bin. After each textual description of the action a list of
string is shown in parenthesis. The first string is the value of the
@strong{context} parameter, the unique identifier of the action, 
@xref{CGI introduction, ,@code{CGI introduction}}. Next, if appropriate,
the word @strong{recursive} may appear, @xref{Recursive CGI call, 
,@code{Recursive CGI call}}. Finally, the name of the template used to
display the end result is shown. 

In some cases, the template file match the template file name used by 
another action. It means that when this action completes, the action
logically attached to this template is called to display the result page.

@node Notation, Style parameter, Diagram, CGI introduction
@section Notation

Each cgi-bin action is described in a separate section. The name of the
section is followed by the unique string that identifies the action (the
@strong{context} parameter value).

In the description of the parameters associated with an action,
the name of the parameter is followed by two strings
in parenthesis. The first indicates if the parameter is mandatory or not,
the second shows the default value, if optional, of the imposed value if any.

In each parameter list, the parameter name (for instance @code{context}) may
be used in a URL in this fashion:

@example
http://www.mymachine.com/cgi-bin/Catalog?param=1&context=value&foo=2
@end example

@node Style parameter, Database table parameters, Notation, CGI introduction
@section Style parameter

@cindex style parameter definition

All the cgi-bin accept the @strong{style} parameter. It is used by the
template handling library to locate the appropriate template for a given
application. The template configuration file is searched for a template
file map whose name equals the value of the @strong{style} parameter. 
If no map is found, the template file name is the default file name. If a
map is found but no entry exist for the default file name, the default
file name is used. If an entry exists for the default file name, the file
name associated with it is used in place of the default file name.

Here a portion of the @strong{template.conf} file that illustrate this
behavior.
@example
style
        custom
                sqledit_search.html = custom_search.html
        end
end
@end example

If the value of @strong{style} is @strong{custom}, the results of a search
will be displayed using the @strong{custom_search.html} template instead
of the @strong{sqledit_search.html} template.
For a definition of the @strong{template.conf} file, @xref{Template configuration file, ,@code{Template configuration file}}.

@node Database table parameters, Primary parameter, Style parameter, CGI introduction
@section Database table parameters

@cindex cgi database field parameters
@cindex parameter names for fields
@cindex fields names in cgi

When a database record is modified or inserted, the HTML form must name
the cgi-bin parameters in a consistent way so that the cgi-bin knows what
was changed and modified. 

@cindex name of the field

The basic rule is that the parameter is named after the field name. Thus
for a table containing a field named @strong{comment}, when setting the
value of the field to @strong{the comment}, the parameter will have to 
be @strong{comment=the%20comment}.

This convention is simple but ambiguous, if two fields of two different
tables have the same name, for instance. To cope with this situation, the
name of the parameter may be prefixed by the name of the table. This is
always optional. 

@cindex alt as a suffix for field name
@cindex alternative values for lists
@cindex list and alternative values

When a list of values is proposed to the user, using a menu or a set of
checkboxes, it is sometimes possible to accept a new value. For instance
if the user is prompted to select the Internet provide he uses, an additional
input box may be added to allow him to type the name of his provider, if it
is not listed. This can be achieved using a special tag, only available for
dictionaries based on tables and not on the native @code{set} or @code{enum}
type of MySQL, @xref{Relational constraints, ,@code{Relational constraints}}.
The name of this tag is the name of the field suffixed with @strong{_alt}.

Here is an artificial example regrouping all the database parameters.

@example
<form>
@code{Simple case}
<input type=text name=@strong{url} size=20>
@code{Table name specified}
<input type=text name=@strong{company_name} size=20>
<input type=text name=@strong{customer_name} size=20>
@code{Alternate value within a list}
<select name=provider>
<option value=hrnet>HRNet
<option value=eunet>EUNET
</form>
<input type=text name=@strong{provider_alt} size=20>
@end example

Here is the generic form of parameter names for database records.
@table @samp
@item fieldname
@item table_fieldname
@item fieldname_alt
@item table_fieldname_alt
@end table

@node Primary parameter, Recursive CGI call, Database table parameters, CGI introduction
@section Primary parameter

The cgi-bin invocations dealing with a single record will use the 
@strong{primary} parameter to carry the unique identifier of this record
in the database. If the table manipulated does not have a unique integer
identifier, most cgi-bin will not work properly. 

The field containing the primary key is usually named @strong{rowid} and
is not type @code{int autoincrement}. Although such a field indeed exists
for all the tables created by this library, it need not be named
@strong{rowid}. The library will identify the primary key by using the
output of the @strong{show table} command.

@node Recursive CGI call, CGI called with PATH_INFO, Primary parameter, CGI introduction
@section Recursive CGI call

@cindex Recursive CGI call
@cindex CGI recursive call
@cindex Call CGI recursively 

The explanation is much clearer if we begin with an example. Imagine that
a cgi-bin action, named @strong{New entry in catalog}, does the following:

@itemize @bullet
@item get values for an insertion in a catalog
@item insert a record containing these values
@item link this record at some point of the catalog
@end itemize

The first two actions may be performed by an existing cgi-bin action, the
one in charge of proposing an insert form to the user and insert the
record in the database, @xref{Record insert form (sinsert_form), ,@code{Record insert form (sinsert_form)}}.
When designing the @strong{New entry in catalog} action, we first want
to call the @strong{Record insert form} action, then perform the third
action (link record at the current point of the catalog) using
the record just created. 

Simply put, a recursive CGI call occurs when a cgi-bin make use of another
cgi-bin action to perform its action. From the user point of view, the
action that makes use of recursive CGI is always a multi step interaction
process.

The cgi-bin parameters that are visible in the URLs and are related to
the recursive calls are the following:

@itemize @bullet
@item 
fct_name
@item
fct_args
@item
fct_stack
@item
fct_returned
@end itemize

When a cgi-bin behaves in a different way if called recursively, it
will base it's action on those tags. 

@node CGI called with PATH_INFO, Multipage results parameters, Recursive CGI call, CGI introduction
@section CGI called with PATH_INFO

Assuming that you have a cgi-bin script accessed by /cgi-bin/Catalog, if you try to access
/cgi-bin/Catalog/Sport/Cars/, then you call the cgi-bin with PATH_INFO instead of regular parameters.
This may be very convenient if you want to give users an intuitive access to a thematic 
catalog. @strong{Catalog} provides support for this kind of usage in the following way.

If the @strong{PATH_INFO} environment variable is set when the navigation cgi-bin is called,
@strong{Catalog} behaves as if called with the @strong{pathcontext} context and the 
@strong{pathname} parameter is set with the value of @strong{PATH_INFO}, @xref{Intuitive navigation (pathcontext),,@code{Intuitive navigation (pathcontext)}},

@node Multipage results parameters,  , CGI called with PATH_INFO, CGI introduction
@section Multipage results parameters

@cindex multipage results
@cindex page parameter
@cindex page_length parameter

Some cgi-bin will display their result on more than one page to reduce
the overhead. By default the first ten units are shown and a footer
shows links that allow visualization of the following pages.

The number of units shown on a page and the page number is controlled by
the following parameters.

@table @samp
@item page_length (default 10)
@item page (default 1)
@end table

The associated template part is described elsewhere,
@xref{Multipage results template, ,@code{Multipage results template}}.

@node Catalog CGI, SQL manipulation CGI, CGI introduction, Top
@chapter Catalog CGI

This chapter lists all the invocations of the @code{Catalog} package
and is a reference for the available parameters, the template used
and the functionality provided.

@image{images/fctcatalog,15cm,}


@menu
* Control panel (ccontrol_panel)::  Control panel (ccontrol_panel)
* Ask for catalog destruction (cdestroy)::  Ask for catalog destruction (cdestroy)
* Catalog destruction (cdestroy_confirm)::  Catalog destruction (cdestroy_confirm)
* Reset count on alpha catalog (calpha_count)::  Reset count on alpha catalog (calpha_count)
* Reset count on theme catalog (category_count)::  Reset count on theme catalog (category_count)
* Build a new catalog (cbuild)::  Build a new catalog (cbuild)
* Modify catalog properties (ccatalog_edit)::  Modify catalog properties (ccatalog_edit)
* Browse alphabetical catalog root (calpha)::  Browse alphabetical catalog root (calpha)
* Browse alphabetical catalog (calpha)::  Browse alphabetical catalog (calpha)
* Browse theme catalog root (cbrowse_root)::  Browse theme catalog root (cbrowse_root)
* Browse theme catalog (cbrowse)::  Browse theme catalog (cbrowse)
* Intuitive navigation (pathcontext)::  Intuitive navigation (pathcontext)
* Catalog search (csearch)::    Catalog search (csearch)
* Browse chronological catalog (cdate)::  Browse chronological catalog root (cdate)
* Edit panel for a category node (cedit)::  Edit panel for a category node (cedit)
* Remove a category (categoryremove)::  Remove a category (categoryremove)
* Insert a category (categoryinsert)::  Insert a category (categoryinsert)
* Link a catalog entry (centryselect)::  Link a catalog entry (centryselect)
* Create and link a catalog entry (centryinsert)::  Create and link a catalog entry (centryinsert)
* Create a symbolic link (categorysymlink)::  Create a symbolic link (categorysymlink)
* Unlink a catalog entry (centryremove)::  Unlink a catalog entry (centryremove)
* Ask to remove a catalog entry (centryremove_all)::  Ask to remove a catalog entry (centryremove_all)
* Remove a catalog entry (centryremove_all_confirm)::  Remove a catalog entry (centryremove_all_confirm)
* Ask for confirmation before dump (cdump)::  Ask for confirmation before dump (cdump)
* Dump a thematic catalog (cdump_confirm)::  Dump a thematic catalog (cdump_confirm)
* Query parameters for load (cimport)::  Query parameters for load (cimport)
* Load a thematic catalog from file (cimport_confirm)::  Load a thematic catalog from file (cimport_confirm)
* Query parameters for unload (cexport)::  Query parameters for unload (cexport)
* Unload a thematic catalog to file (cexport_confirm)::  Unload a thematic catalog to file (cexport_confirm)
@end menu


@node Control panel (ccontrol_panel), Ask for catalog destruction (cdestroy), Catalog CGI, Catalog CGI
@section Control panel (ccontrol_panel)

@image{images/controlpanel4,10cm,}

@cindex Control Panel
@cindex ccontrol_panel
@cindex Catalog Control Panel

@table @samp

@item Description
Display a panel that shows all existing catalogs, allows creation of
new catalogs, shows links to edit or browse each catalog and have links
to edit the configuration files.

@item Template file
@xref{ccontrol_panel.html, ,@code{ccontrol_panel.html}}.

@item Parameters

@cindex parameter, context

@table @samp
@item context (mandatory, @strong{ccontrol_panel})
@end table

@end table

@node Ask for catalog destruction (cdestroy), Catalog destruction (cdestroy_confirm), Control panel (ccontrol_panel), Catalog CGI
@section Ask for catalog destruction (cdestroy)

@image{images/cdestroy,10cm,}

@cindex Catalog destruction
@cindex Destroy a catalog
@cindex Remove a catalog
@cindex cdestroy

@table @samp

@item Description
First step of catalog removal. Shows a screen asking for confirmation
of the removal.

@item Template file
@xref{cdestroy.html, ,@code{cdestroy.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{cdestroy})
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Catalog destruction (cdestroy_confirm), Reset count on alpha catalog (calpha_count), Ask for catalog destruction (cdestroy), Catalog CGI
@section Catalog destruction (cdestroy_confirm)

@cindex Catalog destruction
@cindex Destroy a catalog
@cindex Remove a catalog
@cindex cdestroy_confirm

@table @samp

@item Description
Effective destruction of the named catalog.

@item Template file
@xref{ccontrol_panel.html, ,@code{ccontrol_panel.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{cdestroy_confirm})
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Reset count on alpha catalog (calpha_count), Reset count on theme catalog (category_count), Catalog destruction (cdestroy_confirm), Catalog CGI
@section Reset count on alpha catalog (calpha_count)

@cindex Catalog count
@cindex Count entries in a catalog
@cindex calpha_count

@table @samp

@item Description
Reset the count of entries for an alphabetically ordered catalog.
The values contained in the field name used for ordering are listed.
Each alphanumerical character (A thru Z, 0 thru 9) that appear in first
position is counted. The result is stored in a table for use by the
@strong{Browse alphabetical catalog root} action.

This operation is not needed in normal operation since it will be
automatically calculated every 24 hours. It may be called for immediate
update, after a large update operation, for instance.

@item Template file
@xref{ccontrol_panel.html, ,@code{ccontrol_panel.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{calpha_count})
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Reset count on theme catalog (category_count), Build a new catalog (cbuild), Reset count on alpha catalog (calpha_count), Catalog CGI
@section Reset count on theme catalog (category_count)

@cindex Catalog count
@cindex Count entries in a catalog
@cindex category_count

@table @samp

@item Description
Reset the count of entries for an category tree ordered catalog.

Each node of the tree contains the number of entries it contains plus
the total number of entries contained in all its sub categories. Thus,
the root node contains the total number of entries in the catalog. 

The symbolic links are ignored when updating the counts. This is to prevent
counting entries twice.

This operation is never needed in normal operation. It may be used
after an accidental update of the count using a direct SQL order.

@item Template file
@xref{ccontrol_panel.html, ,@code{ccontrol_panel.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{category_count})
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Build a new catalog (cbuild), Modify catalog properties (ccatalog_edit), Reset count on theme catalog (category_count), Catalog CGI
@section Build a new catalog (cbuild)

@image{images/catalogcreate,10cm,}

@cindex Catalog build
@cindex Building a new catalog
@cindex cbuild

@table @samp

@item Recursion on insertion
The recursion is done on @strong{Record insert form}, @xref{Record insert form (sinsert_form), ,@code{Record insert form (sinsert_form)}}.

@item Description

Create a new catalog. This is done by inserting a new record in the
@strong{catalog} table. The information that should be filled in this
record depends on the type of catalog created. 

Here is a list of the fields:

@table @samp

@item Common to all types
@table @samp
@item name (mandatory)
The name of the catalog. May contain alphanumerical characters only 
(A thru Z, 0 thru 9). It must be unique.
@item corder (optional)
The @code{ORDER BY} SQL clause that will be used when displaying 
the catalogued table entries at one level of the catalog. 
@item cwhere (optional)
The @code{WHERE} SQL clause that will be used to find the entries that
will be displayed. This may be used to put in the catalog only part of
the records of the table.
@end table

@item Alphabetical and Chronological catalogs
@table @samp
@item fieldname (mandatory)
The name of the field from the catalogued table that will be considered
for alphabetical or chronological ordering.
@end table

@end table

@item Template files

@table @samp
@item Thematic
@xref{catalog_theme_insert.html, ,@code{catalog_theme_insert.html}}.

@item Alphabetical
@xref{catalog_alpha_insert.html, ,@code{catalog_alpha_insert.html}}.

@item Chronological
@xref{catalog_date_insert.html, ,@code{catalog_date_insert.html}}.

@end table

@item Parameters

@cindex parameter, context
@cindex parameter, table

@table @samp
@item context (mandatory, @strong{cbuild})
@item navigation (mandatory)
@item table (mandatory)
Name of the database table for which the catalog will be created.
@end table

@end table

@node Modify catalog properties (ccatalog_edit), Browse alphabetical catalog root (calpha), Build a new catalog (cbuild), Catalog CGI
@section Modify catalog properties (ccatalog_edit)

@image{images/ccatalogedit,10cm,}

@cindex Catalog properties modification
@cindex Modify catalog properties
@cindex ccatalog_edit

@table @samp

@item Recursion on edition
The recursion is done on @strong{Record edit form}, @xref{Record edit form (edit), ,@code{Record edit form (edit)}}.

@item Description
Modify the properties of an existing catalog.

Here is a list of the modifiable fields:

@table @samp

@item Common to all types of catalog
@table @samp
@item name (mandatory)
The name of the catalog. May contain alphanumerical characters only 
(A thru Z, 0 thru 9). Must be unique.
@item corder (optional)
The @code{order by} SQL clause that will be used when displaying 
the catalogued table entries at one level of the catalog. 
@item cwhere (optional)
The @code{where} SQL clause that will be used to find the entries that
will be displayed. This may be used to put in the catalog only part of
the records of the table.
@end table

@item Alphabetical and Chronological catalog
@table @samp
@item fieldname (mandatory)
The name of the field from the catalogued table that will be considered
for alphabetical ordering.
@end table

@end table

@item Template files

@table @samp
@item Thematic
@xref{catalog_theme_edit.html, ,@code{catalog_theme_edit.html}}.

@item Alphabetical
@xref{catalog_alpha_edit.html, ,@code{catalog_alpha_edit.html}}.

@item Chronological
@xref{catalog_date_edit.html, ,@code{catalog_date_edit.html}}.

@end table

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{ccatalog_edit})
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Browse alphabetical catalog root (calpha), Browse alphabetical catalog (calpha), Modify catalog properties (ccatalog_edit), Catalog CGI
@section Browse alphabetical catalog root (calpha)

@image{images/calpharoot,10cm,}

@cindex Browse alphabetical catalog
@cindex Catalog browsing
@cindex calpha

@table @samp

@item Description
Display the root page of the alphabetically ordered catalog. 
This page contains one entry for each letter and digit. This
entry is associated to an hypertext link if there exists 
records in the catalogued table. The number of records founds
for each letter is displayed next next to the letter.

The count associated with each letter is recalculated every 24 hour.
There may be differences between the count shown in this page and
the actual records shown by the @code{Browse alphabetical catalog} action.

@item Template file
@cindex calpha_root.html
@xref{calpha_root.html, ,@code{calpha_root.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{calpha})
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Browse alphabetical catalog (calpha), Browse theme catalog root (cbrowse_root), Browse alphabetical catalog root (calpha), Catalog CGI
@section Browse alphabetical catalog (calpha)

@image{images/calpha,10cm,}

@cindex Browse alphabetical catalog
@cindex Catalog browsing
@cindex calpha

@table @samp

@item Description
Display the records from the catalogued table for which the
field value begins with the @strong{letter} parameter letter.
The field name used for this operation is the value of the
@strong{fieldname} field of the record describing the catalog.

This action is implemented using the @strong{Search table} action, 
@xref{Search table (search),,@code{Search table (search)}}.

@item Template file
@xref{sqledit_search.html, ,@code{sqledit_search.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, letter

@table @samp
@item context (mandatory, @strong{calpha})
@item letter (mandatory)
The letter used for the search, may be (A thru Z, 0 thru 9).
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Browse theme catalog root (cbrowse_root), Browse theme catalog (cbrowse), Browse alphabetical catalog (calpha), Catalog CGI
@section Browse theme catalog root (cbrowse_root)

@cindex Browse theme catalog
@cindex Catalog browsing
@cindex cbrowse_root

@table @samp

@item Description
Provides exactly the same functionality as the @strong{Browse theme catalog}
action. The only difference is the name of the template file used to 
display the result.

@item Template file
@xref{cbrowse_root.html, ,@code{cbrowse_root.html}}.

@end table

@node Browse theme catalog (cbrowse), Intuitive navigation (pathcontext), Browse theme catalog root (cbrowse_root), Catalog CGI
@section Browse theme catalog (cbrowse)

@cindex Browse theme catalog
@cindex Catalog browsing
@cindex cbrowse

@table @samp

@item Description
Provides the same basic functionalities as the 
@strong{Edit panel for a category node} action. The differences are
listed below:

@table @samp
@item Category hiding
If a category is empty and the @strong{hideempty} flag of the catalog
is set, do not display the category.

@item Editing tags
The tags that allow editing of the catalog are not available.

@item context parameter
Is set to @strong{cbrowse} instead of @strong{cedit}

@item Template file
Is @strong{cbrowse.html} instead of @strong{cedit.html}.

@end table

@item Template file
@xref{cbrowse.html, ,@code{cbrowse.html}}.

@item Parameters

@cindex parameter, context

@table @samp
@item context (mandatory, @strong{cbrowse})
@item other tags
Same as @strong{cedit}, @xref{Edit panel for a category node (cedit), ,@code{Edit panel for a category node (cedit)}}.
@end table

@end table

@node Intuitive navigation (pathcontext), Catalog search (csearch), Browse theme catalog (cbrowse), Catalog CGI
@section Intuitive navigation (pathcontext)

@cindex Browse theme catalog
@cindex Catalog browsing
@cindex Intuitive browsing
@cindex pathcontext

@table @samp

@item Description
This context is implicitly called when the cgi-bin call has a PATH_INFO component, 
@xref{CGI called with PATH_INFO,,@code{CGI called with PATH_INFO}}. The PATH_INFO environment 
variable is available in the @strong{pathname} parameter. 
The name of the catalog to browse and other parameters are extracted from the
@strong{pathcontext_params} instruction found in the @strong{catalog.conf} configuration file,
@xref{Catalog configuration file,,@code{Catalog configuration file}}. 
The @strong{pathname} parameter is converted to a category id using the @strong{catalog_path_<name>}
table. Finally, the @strong{cbrowse} context is called for the category. 

@cindex multipage results, pathcontext
It must be noted that the results are @strong{not} paginated when browsing a catalog in this
way. This restriction is meant to simplify the implementation, in particular for dumping the
catalog in HTML pages. 

@cindex symbolic categories, pathcontext
The handling of symbolic links is different when browsing with @strong{pathcontext}. With
@strong{cbrowse} the symbolic links are displayed as normal sub categories. For instance,
if /a/b contains a symbolic link to /c, browsing /a/b to go in /c will show the full path
name /a/b/c. When browsing with @strong{pathcontext}, going to /c will show the full path
name /c. In other words symbolic links retain their original full path name when browsing
with @strong{pathcontext}.


@item Template file
@xref{cbrowse_root.html, ,@code{cbrowse_root.html}}.
@xref{cbrowse.html, ,@code{cbrowse.html}}.

@end table

@node Catalog search (csearch), Browse chronological catalog (cdate), Intuitive navigation (pathcontext), Catalog CGI
@section Catalog search (csearch)

@cindex Search theme catalog
@cindex Catalog search
@cindex csearch

@image{images/examplecsearch2,10cm,}

@table @samp

@item Description
Searching a thematic catalog is a two step process, if not specified otherwise by the @strong{what} parameter.
First, the category names are searched with the search criterion (@strong{text} parameter). If 
categories are found, they are displayed. If no category
matches the search criterion, the records are searched with the same criterion. 
A new search form is shown on top of the search results, giving the opportunity to the user to change the
search criterion or to search in the records instead of the categories. 

The search criterion specified in the @strong{text} parameter is split in a list of words (alphanumerical
sequence of character, including the dash (@strong{-})). The words are searched using the boolean operator
specified with the @strong{boolean} parameter. By default the boolean operator used is @strong{or} and 
any occurrence of a word is a hit. If the boolean operator is set to @strong{and}, the search only hits
if all the words are found, the order in which they appear is not relevant.

When searching the categories, the search is done on the @strong{name} field, @xref{catalog,,@code{catalog}}.
The ordering of the categories is ascending alphabetical.

When searching the records, the search is done using all the fields of type @strong{char}, @strong{varchar}
or @strong{text}, if not specified otherwise in the @strong{catalog.conf} configuration file, 
@xref{Catalog configuration file,,@code{Catalog configuration file}}.
The first order criterion of the records is the name of the category they belong to so that every record
in the same category are displayed together. Optional additional order criterion may be specified in the
@strong{catalog.conf} configuration file, 
@xref{Catalog configuration file,,@code{Catalog configuration file}}.

@item Template file
@xref{csearch.html, ,@code{csearch.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, text
@cindex parameter, what
@cindex parameter, mode
@cindex parameter, boolean

@table @samp

@item context (mandatory, @strong{csearch})
@item name (mandatory)
Unique name of the catalog. It must be the name of a thematic catalog.

@item text (mandatory)
The search criterion. Each alphanumerical and dash (@strong{-}) sequence of character of
this parameter is a distinct search criterion.

@item what (optional)
Specifies the domain of the search. 
If set to @strong{categories}, only the category names will be searched.
If set to @strong{records}, only the records will be searched. If not set
the categories will be searched first and, if no category matches, the records
will be searched.

@item mode (optional, default @strong{cbrowse})
Specifies the context in which the search is made. It can be either @strong{cbrowse}, @strong{cedit} or
@strong{pathcontext}. The href links displayed in the result page will use the specified context.

@item boolean (optional, default @strong{or})
Specifies the boolean operator used to glue search terms. 

@end table

@end table

@node Browse chronological catalog (cdate), Edit panel for a category node (cedit), Catalog search (csearch), Catalog CGI
@section Browse chronological catalog root (cdate)

@image{images/cdate,10cm,}

@cindex Browse chronological catalog
@cindex Catalog browsing
@cindex cdate

@table @samp

@item Description
Display the records associated with a date field included in the
period specified by the @strong{date} argument of the cgi-bin. 
A calendar of the period is displayed for each period that contains at
least one record and the number of records is calculated for each period.

The period used to find records to display can be different from the
period used to find entries displayed in the calendar. This is achieved
by using the @strong{index_date} and @strong{records_date} cgi-bin parameters.

To improve performances, the number of entries for each period is cached
in a temporary table. The cache is refreshed every 24h. If an immediate
refresh is necessary, the @strong{cdate_count} action may be used to flush
the cache.

@item Template files

@table @samp

@cindex cdate_default.html
@item cdate_default.html
@xref{cdate_default.html, ,@code{cdate_default.html}}.

@cindex cdate_<template>.html
@item cdate_<template>.html
This template will be used if the @strong{template} cgi-bin parameter is
set. This is typically the case if you want a different display to
display all the years of the current period, only one year, only one month
or only one day. See the @strong{template} parameter description below.

@end table

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{cdate})

@item name (mandatory)
Unique name of the catalog.

@cindex parameter, template
@item template (optional, default @strong{default})
Modifies the name of the template used to display the results. If omitted it
defaults to the string @strong{default}. The template name used is calculated
in the following manner:

@example
date_<template>.html
@end example

This is typically used to differentiate templates that display years, months
and days.

@cindex parameter, date
@item date (optional)
Specify the period for both calendar and records displayed. It may have
the following forms:

@table @samp
@item YYYY
Defines the period from January 1st 00:00 to December 31 23:59
of the YYYY year.

@item YYYYMM
Defines the period from the first day of YYYYMM month 00:00h
to last day of the same month 23:59h.

@item YYYYMMDD
Defines the period of the YYYYMMDD day from 00:00h to 23:59h.

@end table

@cindex parameter, records_date
@item records_date
Same syntax as parameter @strong{date} but only applies to the display of
records.

@cindex parameter, index_date
@item index_date
Same syntax as parameter @strong{date} but only applies to the display of
the calendar.

@end table

@end table

@node Edit panel for a category node (cedit), Remove a category (categoryremove), Browse chronological catalog (cdate), Catalog CGI
@section Edit panel for a category node (cedit)

@image{images/entryinsert2,10cm,}

@cindex Edit panel for a category
@cindex Category editing
@cindex cedit

@table @samp

@item Description
Display the sub-categories and entries of a given node in the category tree.
Buttons will be displayed to allow modification of each element in the page.

The information displayed is:

@itemize @bullet
@item 
The list of sub categories
@item 
The path, starting from the root of the catalog, that leads to the current
category node.
@item
The list of entries of the catalogued table linked to the current category
node.
@item 
The name of the current category.
@end itemize

List of actions that modify the displayed category:

@table @strong
@item @image{images/new,,}
Create a new record in the table associated with the catalog and link it
to the current category, 
@xref{Create and link a catalog entry (centryinsert),,@code{Create and link a catalog entry (centryinsert)}}.

@item @image{images/link,,}
Display a search form that will allow you to choose a record in the table 
associated with the catalog and link this record to the current category.
In short, add a link to an existing record in this category. This effectively
allows you to include a given record in many categories of the category tree,
@xref{Link a catalog entry (centryselect),,@code{Link a catalog entry (centryselect)}}.

@item @image{images/open,,}
Create a new sub category, @xref{Insert a category (categoryinsert), ,@code{Insert a category (categoryinsert)}}.

@item @image{images/plus,,}
A link to create a sub category that is a symbolic link to an existing
category, @xref{Create a symbolic link (categorysymlink), ,@code{Create a symbolic link (categorysymlink)}}.

@item @image{images/control,,}
A link to go back to the control panel, 
@xref{Control panel (ccontrol_panel), ,@code{Control panel (ccontrol_panel)}}.

@end table

The list of actions associated with each sub-category of the current category:

@table @strong
@item @image{images/cut,,}
Remove this sub-category. Note that only empty sub-categories can be removed.
@xref{Remove a category (categoryremove), ,@code{Remove a category (categoryremove)}}.

@item @image{images/edit,,}
Edit the properties of this sub-category.

@end table

The list of actions associated with each entry in the current category:
 
@table @strong
@item @image{images/unlink,,}
Destroy the link between the record and the current category, @xref{Unlink a catalog entry (centryremove), ,@code{Unlink a catalog entry (centryremove)}}. The
record itself is @strong{not} removed from the table associated with the
catalog.

@item @image{images/cut,,}
Remove the record and all links in all categories, @xref{Ask to remove a catalog entry (centryremove_all), ,@code{Ask to remove a catalog entry (centryremove_all)}}.

@item @image{images/edit,,}
Edit the record, @xref{Record edit form (edit),,@code{Record edit form (edit)}}. When
the record is updated the current category is displayed.

@end table

@cindex _PATH_
@cindex Path display in category
@cindex Category path display

The display of the path requires some explanation. The path of a category
is the list of category nodes used by the user to reach a given point
of the catalog. When the path is displayed, each component is a link
that gives direct access to the corresponding category. The last component
of the path is the currently displayed category node and is therefore not
shown as an hypertext link. The components of the path are separated by
a string (by default / ) taken from the catalog configuration file, 
@xref{Catalog configuration file, ,@code{Catalog configuration file}}.
The label displayed to represent the root of the catalog is @strong{Root}
by default or is taken from the catalog configuration file, 
@xref{Catalog configuration file, ,@code{Catalog configuration file}}.

If the path is omitted (in normal operation it is fully specified in 
the parameter list of the cgi, see below), it will be rebuilt using
the path from 
the category node designated by the @strong{id} parameter and the root
of the catalog that does not include any symbolic links.

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, id
@cindex parameter, path
@cindex parameter, fct_name

@table @samp
@item context (mandatory, @strong{cedit})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category node to display. The rowid is relative
to the @strong{catalog_category_<name>} table,  @xref{catalog_category_<name>, ,@code{catalog_category_<name>}}.
@item path (optional, default to shortest path)
The coma separated list of rowids used to reach the category node or the
shortest path from @strong{id} to root.
@item fct_name (optional)
@cindex _CATEGORYSYMLINK_
@cindex symlink part of cedit.html
If set to @strong{select}, the @strong{symlink} part of the template
is generated. Otherwise the part is omitted.
@end table

@end table

@node Remove a category (categoryremove), Insert a category (categoryinsert), Edit panel for a category node (cedit), Catalog CGI
@section Remove a category (categoryremove)

@cindex Remove a category
@cindex Sub-category remove
@cindex Category remove
@cindex Catalog remove a sub-category
@cindex categoryremove

@table @samp

@item Description
Remove the category designated by the @strong{child} parameter. 

If the category is indeed a symbolic link to another category, it is
remove regardless.

If the category is not as symbolic link and contains entries or 
sub categories, it is not removed and an error message is displayed.

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, id
@cindex parameter, child

@table @samp
@item context (mandatory, @strong{categoryremove})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category containing the @strong{child} category.
@item child (mandatory)
The rowid of the category to be removed.
@end table

@end table

@node Insert a category (categoryinsert), Link a catalog entry (centryselect), Remove a category (categoryremove), Catalog CGI
@section Insert a category (categoryinsert)

@image{images/categoryinsert,10cm,}

@cindex Insert a category
@cindex Sub-category insert
@cindex Category insert
@cindex Catalog, insertion of a category
@cindex categoryinsert

@table @samp

@item Recursion on insertion
The recursion is done on @strong{Record insert form}, @xref{Record insert form (sinsert_form), ,@code{Record insert form (sinsert_form)}}. The table used is @strong{catalog}.

The name of the new category must @strong{not} contain a slash (@strong{/}). It may contain
white spaces and accented characters.

@item Description
Insert a new category.

Here is the list of fields that can be filled when creating a category:

@table @samp
@item name
The name of the category

@item externalid
A unique key, imported from an external catalog.

@end table

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{categoryinsert})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category that will contain the new category.
@end table

@end table

@node Link a catalog entry (centryselect), Create and link a catalog entry (centryinsert), Insert a category (categoryinsert), Catalog CGI
@section Link a catalog entry (centryselect)

@image{images/centryselect,10cm,}

@cindex Link a record to category in catalog
@cindex Category, link an entry
@cindex Catalog, link an entry
@cindex centryselect

@table @samp

@item Recursion on selection
The recursion is done on @strong{Search table}, @xref{Search table (search), ,@code{Search table (search)}}. The catalogued table is used for the @strong{table} argument.

@item Description
The selected record of the catalogued table is linked to the current category.
When this is done the current category is displayed and shows the newly
inserted entry.

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, id

@table @samp
@item context (mandatory, @strong{centryselect})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category that will contain the new entry.
@end table

@end table

@node Create and link a catalog entry (centryinsert), Create a symbolic link (categorysymlink), Link a catalog entry (centryselect), Catalog CGI
@section Create and link a catalog entry (centryinsert)

@cindex Create and link a record to category in catalog
@cindex Category, create and link an entry
@cindex Catalog, create and link an entry
@cindex centryinsert

@table @samp

@item Recursion on insertion
The recursion is done on @strong{Record insert form}, @xref{Record insert form (sinsert_form), ,@code{Record insert form (sinsert_form)}}. 
The catalogued table is used for the @strong{table} argument.

@item Description
The insertion form for the catalogued table is shown. The user may
enter values for the various fields of the table. The constraints related
to the catalogued table is not defined here and depend on the application.

Once the insertion is done, the inserted record of the catalogued table
is linked to the current category and the current category is displayed
and shows the newly inserted entry.

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, id

@table @samp
@item context (mandatory, @strong{centryinsert})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category that will contain the new entry.
@end table

@end table

@node Create a symbolic link (categorysymlink), Unlink a catalog entry (centryremove), Create and link a catalog entry (centryinsert), Catalog CGI
@section Create a symbolic link (categorysymlink)

@image{images/categorysymlink,10cm,}

@cindex Create a symbolic link in catalog
@cindex Category, create a symbolic link
@cindex Catalog, create a symbolic link
@cindex categorysymlink

@table @samp

@item Recursion on navigation
The recursion is done on @strong{Edit panel}, @xref{Edit panel for a category node (cedit), ,@code{Edit panel for a category node (cedit)}}. 
The catalog used is the catalog named by the @strong{name} parameter.

@item Description
The objective is to chose a category that will be added as a sub-category
of the current category. However, instead of creating a brand new category,
we want to select an existing one and create a symbolic link to it.

To select a category, the category editor is called recursively,
@xref{Recursive CGI call, 
,@code{Recursive CGI call}}. This allows you to browse the catalog hierarchy.
Note that you will see an additional link that says 
@strong{Select this category as a symbolic link}. If you click on this link
you will effectively chose the current category as the end point of the
symbolic link to be created.

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, id

@table @samp
@item context (mandatory, @strong{categorysymlink})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category that will contain the new symbolic link to 
another category.
@end table

@end table

@node Unlink a catalog entry (centryremove), Ask to remove a catalog entry (centryremove_all), Create a symbolic link (categorysymlink), Catalog CGI
@section Unlink a catalog entry (centryremove)

@cindex Unlink a catalog entry
@cindex Category, unlink an entry
@cindex Catalog, unlink an entry
@cindex centryremove

@table @samp

@item Description
The record from the catalogued table designated by the @strong{row} parameter
is unlinked from the current category. The record itself is not removed and
the links to this record that appear in other categories of the same catalog
are not touched.

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, row
@cindex parameter, id

@table @samp
@item context (mandatory, @strong{centryremove})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category that will contain the new symbolic link to 
another category.
@item row (mandatory)
The primary key of the record from the catalogued table.
@end table

@end table

@node Ask to remove a catalog entry (centryremove_all), Remove a catalog entry (centryremove_all_confirm), Unlink a catalog entry (centryremove), Catalog CGI
@section Ask to remove a catalog entry (centryremove_all)


@cindex Remove and unlink a catalog entry
@cindex Category, remove and unlink an entry
@cindex Catalog, remove and unlink an entry
@cindex centryremove_all

@table @samp

@item Description
First step of entry removal.

@item Template file
@xref{centryremove_all.html, ,@code{centryremove_all.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, row
@cindex parameter, id

@table @samp
@item context (mandatory, @strong{centryremove_all})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category that will contain the new symbolic link to 
another category.
@item row (mandatory)
The primary key of the record from the catalogued table.
@end table

@end table

@node Remove a catalog entry (centryremove_all_confirm), Ask for confirmation before dump (cdump), Ask to remove a catalog entry (centryremove_all), Catalog CGI
@section Remove a catalog entry (centryremove_all_confirm)

@cindex Remove and unlink a catalog entry
@cindex Category, remove and unlink an entry
@cindex Catalog, remove and unlink an entry
@cindex centryremove_all_confirm

@table @samp

@item Description
The record from the catalogued table designated by the @strong{row} parameter
is removed from the catalogued table. All the links to this record in the
current catalog are removed, including the link in the current category. 

@item Template file
@xref{cedit.html, ,@code{cedit.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, row
@cindex parameter, id

@table @samp
@item context (mandatory, @strong{centryremove_all_confirm})
@item name (mandatory)
Unique name of the catalog.
@item id (mandatory)
The rowid of the category that will contain the new symbolic link to 
another category.
@item row (mandatory)
The primary key of the record from the catalogued table.
@end table

@end table

@node Ask for confirmation before dump (cdump), Dump a thematic catalog (cdump_confirm), Remove a catalog entry (centryremove_all_confirm), Catalog CGI
@section Ask for confirmation before dump (cdump)

@cindex Dump a thematic catalog, confirmation
@cindex Catalog, ask for confirmation before dump of a thematic
@cindex cdump

@table @samp

@item Description
Ask for confirmation before the dump of a thematic catalog. The user has the opportunity to 
change the path where the pages will be dumped and the HTML location from where they will
be read. The initial values of the @strong{path} and @strong{location} fields are read from 
the catalog description (in the @strong{catalog} table).

@item Template files
@xref{cdump.html, ,@code{cdump.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{cdump})
@item name (mandatory)
Unique name of the catalog.
@end table

@end table

@node Dump a thematic catalog (cdump_confirm), Query parameters for load (cimport), Ask for confirmation before dump (cdump), Catalog CGI
@section Dump a thematic catalog (cdump_confirm)

@cindex Dump a thematic catalog
@cindex Catalog, dump a thematic
@cindex cdump_confirm

@table @samp

@item Description
Each page of the thematic catalog is written to disk (starting from the full path name
specified with the @strong{path} location). All the files and sub directories of @strong{path}
will be removed before dump. Make sure it does not contain valuable data. Each category is written
in an index.html file
located in a sub directory of the @strong{path}. The sub directory name is the complete 
category path of the category. In each files the links to other categories are built as if
the @strong{location} parameter was the cgi-bin script.
When the operation is finished, the control panel is redisplayed.

@item Template files
@xref{cbrowse_root.html, ,@code{cbrowse_root.html}}.
@xref{cbrowse.html, ,@code{cbrowse.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, path
@cindex parameter, location

@table @samp
@item context (mandatory, @strong{cdump_confirm})
@item name (mandatory)
Unique name of the catalog.
@item path (mandatory)
Full path name of an existing directory. Saved in the @strong{dump} field of the
@strong{catalog} table.
@item location (mandatory)
The HTML location used as base for links in the dumped pages. Saved in the @strong{dumplocation} field of the
@strong{catalog} table.
@end table

@end table

@node Query parameters for load (cimport), Load a thematic catalog from file (cimport_confirm), Dump a thematic catalog (cdump_confirm), Catalog CGI
@section Query parameters for load (cimport)

@cindex Load a thematic catalog
@cindex Catalog, load a thematic
@cindex cimport

@table @samp

@item Description
Output a form so that user can specify the name of the thematic catalog to
load (@code{name} parameter) and the file containing an XML representation
of the catalog (@code{file} parameter).

@item Template files
@xref{cimport.html, ,@code{cimport.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{cimport})
@item name (optional)
Unique name of the catalog.
@end table

@end table

@node Load a thematic catalog from file (cimport_confirm), Query parameters for unload (cexport), Query parameters for load (cimport), Catalog CGI
@section Load a thematic catalog from file (cimport_confirm)

@cindex Load a thematic catalog
@cindex Catalog, load a thematic
@cindex cimport_confirm

@table @samp

@item Description
Build or rebuild a catalog from the external XML representation found in
the file specified by the @code{file} parameter, @xref{External representation, ,@code{External representation}}. 

@item Template files
@xref{ccontrol_panel.html, ,@code{ccontrol_panel.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, file

@table @samp
@item context (mandatory, @strong{cimport})
@item name (mandatory)
Unique name of the catalog.
@item file (mandatory)
Path name of the file containing the external representation, 
@xref{External representation, ,@code{External representation}}.
@end table

@end table

@node Query parameters for unload (cexport), Unload a thematic catalog to file (cexport_confirm), Load a thematic catalog from file (cimport_confirm), Catalog CGI
@section Query parameters for unload (cexport)

@cindex Unload a thematic catalog
@cindex Catalog, unload a thematic
@cindex cexport

@table @samp

@item Description
Output a form so that user can specify the name of the thematic catalog to
unload (@code{name} parameter) and the file that will containi an XML
representation of the catalog (@code{file} parameter).

@item Template files
@xref{cexport.html, ,@code{cexport.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name

@table @samp
@item context (mandatory, @strong{cexport})
@item name (optional)
Unique name of the catalog.
@end table

@end table

@node Unload a thematic catalog to file (cexport_confirm),  , Query parameters for unload (cexport), Catalog CGI
@section Unload a thematic catalog to file (cexport_confirm)

@cindex Unload a thematic catalog
@cindex Catalog, unload a thematic
@cindex cexport_confirm

@table @samp

@item Description
Build an external XML representation for the catalog specified by the
@code{name} parameter in
the file specified by the @code{file} parameter, @xref{External representation, ,@code{External representation}}. 

@item Template files
@xref{ccontrol_panel.html, ,@code{ccontrol_panel.html}}.

@item Parameters

@cindex parameter, context
@cindex parameter, name
@cindex parameter, file

@table @samp
@item context (mandatory, @strong{cexport})
@item name (mandatory)
Unique name of the catalog.
@item file (mandatory)
Path name of the file containing the external representation, 
@xref{External representation, ,@code{External representation}}.
@end table

@end table

@node SQL manipulation CGI, Relational constraints, Catalog CGI, Top
@chapter SQL manipulation CGI

This chapter lists all the invocations of the @code{sqledit} package
and is a reference for the available parameters, the template used
and the functionality provided.

@image{images/fctsqledit,15cm,}

@menu
* Record edit form (edit)::     Record edit form (edit)
* Record update (update)::      Record update (update)
* Search form (search_form)::   Search form (search_form)
* Record insert form (sinsert_form)::  Record insert form (sinsert_form)
* Record insert (sinsert)::     Record insert (sinsert)
* Record remove (remove)::      Record remove (remove)
* Remove confirm (remove_confirm)::  Remove confirm (remove_confirm)
* Search table (search)::       Search table (search)
* Hook search (hook_search)::   Hook search (hook_search)
@end menu

@node Record edit form (edit), Record update (update), SQL manipulation CGI, SQL manipulation CGI
@section Record edit form (edit)

@image{images/sqleditedit,10cm,}

@cindex Record edit
@cindex Edit record
@cindex Form to edit record

@table @samp

@item Description
Generate an HTML form that displays the content of the record from
@strong{table}, pointed by @strong{primary}, with
suitable input boxes for modification of the values contained in each
field.

@item Template file
@xref{sqledit_edit.html, ,@code{sqledit_edit.html}}.

@item Parameters

@cindex _EDITCOMMENT_
@cindex parameter, table
@cindex parameter, context
@cindex parameter, primary
@cindex parameter, comment

@table @samp
@item context (mandatory, @strong{edit})
@item table (mandatory)
@item primary (mandatory)
@item comment (optional)
The free text that will be instantiated as the @strong{_EDITCOMMENT_} tag.
@item @code{table parameters}
@xref{Database table parameters, ,@code{Database table parameters}}.
@end table

@end table

@node Record update (update), Search form (search_form), Record edit form (edit), SQL manipulation CGI
@section Record update (update)

@image{images/sqleditupdate,10cm,}

@cindex Record update
@cindex Update record
@cindex Form to update record

@table @samp

@item Description
Change the values of the fields of the record from @strong{table}, pointed by
@strong{primary},
with the values from the parameters. The HTML page displayed as a response
it the edit form for the modified record, @xref{Record edit form (edit), ,@code{Record edit form (edit)}}. 

The @strong{_EDITCOMMENT_} tag of the result page will be replaced with
a list of the modified fields.

@cindex empty field handling
@cindex reset field value

To set the value of a field to the empty string, one should fill the
input box with a white space. An empty input box means that no modification
is required for this field. This way of reseting the content of a field
may seem a bit strange but it is necessary because there is no way in HTML
to distinguish a parameter that was set to the empty string by the user from
a parameter that was originally the empty string.

@item Template file
@xref{sqledit_edit.html, ,@code{sqledit_edit.html}}.

@item Parameters

@cindex parameter, table
@cindex parameter, context
@cindex parameter, primary

@table @samp
@item context (mandatory, @strong{update})
@item table (mandatory)
@item primary (mandatory)
@item @code{table parameters}
@xref{Database table parameters, ,@code{Database table parameters}}.
@end table

@end table

@node Search form (search_form), Record insert form (sinsert_form), Record update (update), SQL manipulation CGI
@section Search form (search_form)

@image{images/sqleditsearchform,10cm,}

@cindex Search form
@cindex Query by example
@cindex Form to search in a table

@table @samp

@item Description
The HTML form to search in a @strong{table}
 may either be generated by a cgi-bin or
be a static HTML page. The advantage of generating the search form is that
you don't have to explicitly list all the search criterion, they can be
generated automatically by the cgi-bin.

The search form works as a basic query by example. Each parameter may 
contain a value. The search process will retrieve all the records of the table
that match all the provided values.

For instance, if a table has the @strong{url} field and that the parameter
@strong{url} is provided with the @strong{http://www.ecila.fr/} value, only
the records whose field @strong{url} contains @strong{http://www.ecila.fr/}
will be retrieved.

The values from the parameters are translated to SQL expressions according
to the data type of the corresponding field. All the expressions generated
are joined with the @strong{and} keyword. The resulting expression is
used as a @strong{where} clause to retrieve records.

Here is a table that shows which where expression is generated depending
on the data type of the field and the value entered by the user.

@table @samp
@item integer or time 
@table @samp
@item value
field = value
@item < value
field < value
@item > value
field > value
@end table

@item char
like 'value'

@item set or enum
like '%value%'

@end table

It is not possible to specify a negation, search for null fields or to change
the @strong{and} keyword to @strong{or}.

Note that the default values for fields are not shown on the search form. 

@item Template file
@xref{sqledit_search_form.html, ,@code{sqledit_search_form.html}}.

@item Parameters

@cindex parameter, table
@cindex parameter, context

@table @samp
@item context (mandatory, @strong{search_form})
@item table (mandatory)
@item @code{table parameters}
@xref{Database table parameters, ,@code{Database table parameters}}.
@end table

@end table

@node Record insert form (sinsert_form), Record insert (sinsert), Search form (search_form), SQL manipulation CGI
@section Record insert form (sinsert_form)

@image{images/sqleditinsert,10cm,}

@table @samp

@item Description

The HTML form to insert a new record into the designated @strong{table}
 may either be generated by a cgi-bin or
be a static HTML page. The advantage of generating the insert form is that
you don't have to explicitly list all the fields, they can be
generated automatically by the cgi-bin.

The @strong{table field names} parameters of the cgi-bin may carry values
that will be used as default values of the generated HTML form. If no
value is provided in the parameter list, the default value, as defined
by the database description will be used instead. If there is no default
value in the database description for a given field, the value is set
to the empty string.

@item Template file
@xref{sqledit_sinsert_form.html, ,@code{sqledit_sinsert_form.html}}.

@item Constraints

@xref{SQL editor configuration file, ,@code{SQL editor configuration file}}.

@item Parameters

@cindex parameter, table
@cindex parameter, context

@table @samp
@item context (mandatory, @strong{sinsert_form})
@item table (mandatory)
@item @code{table parameters}
@xref{Database table parameters, ,@code{Database table parameters}}.
@end table

@end table

@node Record insert (sinsert), Record remove (remove), Record insert form (sinsert_form), SQL manipulation CGI
@section Record insert (sinsert)

@cindex Record insertion
@cindex Insertion of a record

@table @samp

@item Description

Request to insert a record into the table designated by the 
@strong{table} parameter. The record is initialized with the values
specified by the @strong{table parameters}, 
@xref{Database table parameters, ,@code{Database table parameters}}.
When the insertion is complete, the record editing form is called
with the @strong{comment} parameter set to @strong{Record inserted}, thus
allowing to check that the inserted record is indeed what was expected.

@item Template file
@xref{sqledit_edit.html, ,@code{sqledit_edit.html}}.

@item Parameters

@cindex parameter, table
@cindex parameter, context

@table @samp
@item context (mandatory, @strong{sinsert})
@item table (mandatory)
@item @code{table parameters}
@xref{Database table parameters, ,@code{Database table parameters}}.
@end table

@end table

@node Record remove (remove), Remove confirm (remove_confirm), Record insert (sinsert), SQL manipulation CGI
@section Record remove (remove)

@cindex Remove record
@cindex Record removal

@table @samp

@item Description

Request to remove a record as designated by @strong{primary} from 
@strong{table}. The record will not be removed immediately. Instead
a form is generated to ask for confirmation, 
@xref{Remove confirm (remove_confirm), ,@code{Remove confirm (remove_confirm)}}.

@item Template file
@xref{sqledit_remove.html, ,@code{sqledit_remove.html}}.

@item Parameters

@cindex parameter, table
@cindex parameter, context

@table @samp
@item context (mandatory, @strong{remove})
@item table (mandatory)
@item primary (mandatory)
@end table

@end table

@node Remove confirm (remove_confirm), Search table (search), Record remove (remove), SQL manipulation CGI
@section Remove confirm (remove_confirm)

@cindex Confirm record removal
@cindex Record removal, confirmed

@table @samp

@item Description

This action should only be called after a first request from the user
to remove a record, @xref{Record remove (remove), ,@code{Record remove (remove)}}. The 
record whose primary key matches @strong{primary} is deleted from the
table @strong{table}.

@item Template file
@xref{sqledit_remove_confirm.html, ,@code{sqledit_remove_confirm.html}}.

@item Parameters

@cindex parameter, table
@cindex parameter, context

@table @samp
@item context (mandatory, @strong{remove_confirm})
@item table (mandatory)
@item primary (mandatory)
@end table

@end table

@node Search table (search), Hook search (hook_search), Remove confirm (remove_confirm), SQL manipulation CGI
@section Search table (search)

@image{images/sqleditsearch,10cm,}

@cindex Search result display
@cindex Display search result
@cindex Result of SQL search

@table @samp

@item Description

This action is run after the search form was filled. A where clause is
built on the basis of the query by example defined by the user, 
@xref{Search form (search_form), , @code{Search form (search_form)}}. 

The records found are ordered using the @strong{order} parameter.

In addition to the query by example defined by the user, the @strong{limit}
expression limit the context of the search. It must be a valid @strong{where}
expression.

The records found are displayed paginated, @xref{Multipage results template, ,@code{Multipage results template}}.

@cindex links_set definition
@cindex links_set parameter
@cindex Search result links_set
@cindex Indented search results
@cindex Relational structure display

The @strong{links_set} parameter, if defined, is used to display records
linked to each record found according to the relational specifications
described in the @strong{relations.spec} configuration file, 
@xref{Relational constraints, ,@code{Relational constraints}}. 
Please note that @strong{links_set} may only refer to tables described 
in the @strong{relations.spec} file.
Each
record found is displayed below the current record with a margin, as shown
on the screen shot above.

The generic syntax of @strong{links_set} is a tree description using 
nested parentheses. 

@example
links_set: table @code{or}
           tree_spec

tree_spec: table @code{or}
           tree_spec,tree_spec @code{or}
           table(tree_spec)

table: @code{name of a table}
@end example

For instance let's pretend that you have a database with the 
following relational structure, properly described in the 
@strong{relations.spec} file.

@example
table1 ----------> table2 ----------> table4
       |
       |---------> table3
@end example

You would like to display the records from @strong{table2}
for each record found in @strong{table1}. The value of @strong{links_set}
you should use for this purpose will be:

@example
links_set=table1(table2)

record1_table1
  record3_table2
  record10_table2
record2_table1
  record7_table2
record3_table1
  record5_table2
record4_table1
...

@end example

If you would like to display the records from @strong{table4} linked
indirectly to @strong{table1} thru @strong{table2}, the 
value of @strong{links_set} you should use for this purpose will be:

@example
links_set=table1(table2(table4))

record1_table1
  record3_table2
    record100_table4
  record10_table2
    record10_table4
    record7_table4
    record5_table4
record2_table1
  record7_table2
record3_table1
  record5_table2
    record23_table4
    record17_table4
record4_table1
...
@end example

If you would like to display the records from @strong{table2} and 
@strong{table3} both linked to @strong{table1}, the 
value of @strong{links_set} you should use for this purpose will be:

@example
links_set=table1(table2,table3)

record1_table1
  record3_table2
  record10_table2
  record1_table3
record2_table1
  record7_table2
  record10_table3
  record27_table3
record3_table1
  record5_table2
record4_table1
...
@end example

When a table is linked to another in the relational specification, it
is always possible to specify links in both ways. To continue the example
above, all the following case would be legal, with different results, of
course.

@example
links_set=table4(table2(table1(table3)))
links_set=table2(table1,table4)
@end example

@cindex _MARGIN_
@cindex _MARGINTABLE_

Whenever the exploration of the records dive deeper in the relational
specification described in @strong{links_set}, the @strong{_MARGIN_} tag
becomes wider. Let's continue with the example above and a @strong{links_set}
set to @code{table1(table2(table4))}. 
When displaying the records from
@strong{table1} the @strong{_MARGIN_} and @strong{_MARGINTABLE_} tags are
the empty string. 
When displaying the records from
@strong{table2} the @strong{_MARGIN_} tag is one (empty) cell table wide
 and @strong{_MARGINTABLE_} tag is one cell table wide, filled with the
string @strong{table2}.
When displaying the records from
@strong{table4} the @strong{_MARGIN_} tag is two (empty) cells table wide
 and @strong{_MARGINTABLE_} tag is two cells table wide, the last one
filled with the string @strong{table4}.

@cindex First table in links_set
@cindex Constraints in links_set
@cindex links_set constraint

The only, very important constraint, is that the first table mentioned in
the @strong{links_set} parameter must be the same as the value of the
@strong{table} parameter.

@item Template file
@xref{sqledit_search.html, ,@code{sqledit_search.html}}.

@item Constraints

@xref{SQL editor configuration file, ,@code{SQL editor configuration file}}.

@item Parameters

@cindex parameter, table
@cindex parameter, context
@cindex parameter, order
@cindex parameter, limit
@cindex parameter, links_set
@cindex parameter, fct_name

@table @samp
@item context (mandatory, @strong{search})
@item table (mandatory)
@item page (optional, default 1)
@item page_length (optional, default 10)
@item order (optional)
The @strong{order} clause of the generated SQL order.
@item links_set (optional)
Display tree specification of the form table1(table2,table3(table4),table5).
The @strong{table} must have the value @strong{table1}.
@item limit (optional)
A valid @strong{where} expression that will be added to the generated
@strong{where} expression using the @strong{and} keyword.
@item fct_name
If set to @strong{select}, the @strong{select} link is added to 
the @strong{_LINKS_} tag. The associated action is to return to the
calling cgi-bin with the primary key of the corresponding record.
@item @code{table parameters}
@xref{Database table parameters, ,@code{Database table parameters}}.
@end table

@end table

@node Hook search (hook_search),  , Search table (search), SQL manipulation CGI
@section Hook search (hook_search)

@table @samp
@item Description
Search the full text database coupled with the SQL database and display the
records found. The query is built following the instructions found in 
the configuration file,
@xref{Hook Fulcrum configuration file, ,@code{Hook Fulcrum configuration file}}.

@item Template file
@xref{hook_search.html, ,@code{hook_search.html}}.

@item Parameters

@table @samp
@item context (mandatory, @strong{hook_search})
@item query_text (optional)
The query typed by the user.
@item query_flexion (optional)
The possible values are:
@itemize @bullet
@item French
@item none
@end itemize
If the value of this parameter is null or set to @strong{none}, the
words from the user question are used verbatim.

If the value of this parameter is set to @strong{French}, the words
from the question are transformed according to the rules of the French
language for plural and conjugation. The resulting list of words is 
searched instead of the original word.

@item query_expand (optional)
The possible values are:
@itemize @bullet
@item or
@item and
@item phrase
@end itemize

If the value of this parameter is null, the question is rephrased
to express that we are much interested to find the records that match
the question exactly; still quite interested to find the records that
match all the words of the question, even if they are scattered over the
text; less interested by the documents that contain at least one word
from the question but not all of them.

If the value of this parameter is @strong{or}, we are equally interested
by all the records that contain at least one word from the question.

If the value of this parameter is @strong{and}, we are only interested
by the records that contain all the words from the question, 
even if they are scattered over the text.

If the value of this parameter is @strong{phrase}, we are only interested
by the records that contain the exact phrase that we wrote as a question, 
each word in order.

@item query_<fulcrum fieldname> (optional)

Each of these parameters must be built with a valid @strong{fulcrum fieldname}
as defined in the configuration file, @xref{Hook Fulcrum configuration file, ,@code{Hook Fulcrum configuration file}}.

The value associated with this parameter is called a constraint and 
is handled in the following way:

In each group that list this field, the records will only match if the
field contains the listed value. 

In each group that does not list this field, the records will only match
if at least one of the listed fields contain the value.

@end table

@end table

@node Relational constraints, Messages translation, SQL manipulation CGI, Top
@chapter Relational constraints

@cindex relational specifications
@cindex relational constraints
@cindex relations.spec

The relational specification file captures a portion of the relational 
database definition not covered by the table definitions. It defines the
links between the tables and the tables that should be treated as dictionaries.
The semantics of this description is rather limited compared to the full
power of the relational model. However it allows to do simple things that
would otherwise be quite complex to implement.

The general structure of a relation file is an ASCII file where
lines beginning with a dash (@strong{#}) are ignored as well as empty 
lines. 

The name of the relation file is @code{relations.spec} and will be found
either in the current directory or in the directory pointed
by the @code{CONFIG_DIR} environment variable. 

@table @samp
@item Link between two tables

The two tables are linked together thru a n-1 or n-n relation. 
The line describing
this relation is structured as follows:

@example
table1:field1   table2:field2
@end example

It means that table1 is linked to table2 using the values in field1 and field2.

@cindex L in relations.spec
@cindex Single value dictionaries
@cindex Dictionaries with a single value
@item Dictionary with a single possible value

Two tables are linked thru a n-1 relation. One table, the dictionary, provides
a list of possible values and the other table uses this list as dictionary. 

The line describing
this relation is structured as follows:

@example
table:field     dict:key        L       dict:label
@end example

The dictionary is the @code{dict} table. The table @code{table} refers to
it by the field @code{field} that contains a value linked to a value of
the @code{key} field of the @code{dict} table. The third field always
contain @code{L} indicating that this line describe a @strong{L}ist.
The last field specify that the user readable value associated to @code{key}
can be found in the @code{label} field.

@cindex M in relations.spec
@cindex Multiple value dictionaries
@cindex Dictionaries with multiple value
@item Dictionary with a multiple value

This is a bit more complex here since three tables are involved in a 
multiple value dictionary. The table that contains the list of possible values,
the table that contains the records and the table that link those two. 

The line describing
this relation is structured as follows:

@example
table:field     dict:key        M       dict:label      table2dict
@end example

@cindex table linking table and dictionary

The dictionary is the @code{dict} table. The @code{field} field
of @code{table} is a fake field name that will be used to refer to 
the list of the values associated to a single record of @code{table} if
necessary. The @code{table} must contain a field named @code{rowid}
that is the primary key of the table.
The @code{table2dict} table @strong{must} contain two fields
named @code{table} and @code{dict}. The @code{table2dict.table} field refer
to the @code{table.rowid} field and the @code{table2dict.dict} field refer
to the @code{dict.key} table.

@end table

Here is an example @strong{relations.spec} file:
@example
#
# Table dependencies
#
start:societe                   societe:rowid
personne:societe                societe:rowid
marque:societe                  societe:rowid
lecteur:personne                personne:rowid
produitsnouveaux:personne       personne:rowid
produitsnouveaux:societe        societe:rowid
images:produitsnouveaux         produitsnouveaux:rowid
#
# Dictionaries
#
#
# Societe table
#
societe:ca              ca:rowid                L       ca:libelle
societe:effectif        effectif:rowid          L       effectif:libelle
societe:statut          statut:rowid            L       statut:statut
societe:activite        activite:rowid          L       activite:activite
societe:pays            pays:rowid              L       pays:pays
societe:naf             naf:rowid               L       naf:libelle
societe:q               q:rowid                 M       q:q     q2societe
#
# Lecteur table
#
lecteur:navigateur      navigateur:rowid        L       navigateur:navigateur
lecteur:os              os:rowid                L       os:os
lecteur:provider        provider:rowid          L       provider:provider
lecteur:connexion       connexion:rowid         L       connexion:connexion
#
# Personne table
#
personne:pays           pays:rowid              L       pays:pays
personne:profil         profil:rowid            L       profil:profil
@end example

@node Messages translation, Catalog and HTTP server, Relational constraints, Top
@chapter Messages translation

All the packages use a library that maps English messages to strings
specified in a configuration file. 
The file used for messages translations is @strong{messages.conf}.
It's structure is as follows:

@example
original message: replacement line part 1
                  replacement line part 2
                  replacement line part 3
                  ...
original message: replacement line part 1
                  replacement line part 2
                  replacement line part 3
                  ...
...
@end example

The original message will be replaced by a concatenation of the 
replacement lines, concatenated together. The continuation of the
replacement message must start with a white space or the parse will
think that it's another original message.

When the original message contains one or more occurrence
of the @strong{%s} tag, they will appear in the same order in the
replacement message. If you want to get rid of the string that will
replace the @strong{%s} tag, just include it in HTML comments, as 
shown in the example below.

The configuration file is located using the same method as other 
configuration files, @xref{Configuration files, , @code{Configuration files}}.

Throughout this document, all messages followed by a reference to this
chapter may be translated using this configuration file. If you want
to find all the possible messages, refer to the concept index a look at
all the documentation pages pointed at the @strong{message string} entry.

Here is a message translation file example:

@example
#
# sqledit.pm messages
#       
table %s : field %s must be set
        <!-- Dans la table %s : --> La saisie du champ %s est obligatoire.

table %s : field %s : value %s is too long (max %s bytes)
        Dans la table %s : le champ %s dont la valeur est
        %s est trop long (maximum autoris&eacute; %s octets)

table %s : field %s : value %s match failed %s
        <!-- table %s --> Le champ %s (valeur %s) doit %s

table %s : field %s : value %s normalize failed %s
        <!-- table %s --> Le champ %s (valeur %s) doit %s

no entries for this letter in liensalpha
        Il n'existe pas d'entr&eacute;es pour cette lettre dans le 
        classement alphab&eacute;tique des liens sur le net.

found nothing
        Aucun enregistrement ne correspond &agrave; votre requ&ecirc;te
@end example

@node Catalog and HTTP server, Glossary, Messages translation, Top
@chapter Catalog and HTTP server

@cindex Apache
@cindex HTTP server
@cindex WEB server

@menu
* Apache::                      Apache
* Cgi-bin errors::              cgi-bin errors
* Using mod_perl::              Using mod_perl
@end menu

@node Apache, Cgi-bin errors, Catalog and HTTP server, Catalog and HTTP server
@section Apache

Add the following entries to @strong{httpd.conf}
@itemize @bullet
@item 
PassEnv CONFIG_DIR
@item
PassEnv TEMPLATESDIR
@end itemize

If your configuration files are not located in the same place as the 
cgi-bin you will need to run the @strong{httpd} server with a modified
@code{CONFIG_DIR} variable. The @strong{PassEnv} instructions instruct
@strong{httpd} to communicated these environment variables to the cgi-bin. 
If not specified it will hide them. The same applies for @code{TEMPLATESDIR}.

The performances of the Apache server highly depend on the use of the
@strong{mod_perl}. If you chose to use @strong{mod_perl}
(see the following chapter) you must be careful about the number of 
http processes that you will run. Each of them will connect to the
database and contain all the @strong{Catalog} software compiled with
dependent libraries. In this case you should carefully set the
MaxRequestsPerChild, StartServers,
MinSpareServers, MaxSpareServers, MaxClients parameters.

@node Cgi-bin errors, Using mod_perl, Apache, Catalog and HTTP server
@section cgi-bin errors

@cindex logs of errors
@cindex error logs and traces
@cindex traces for errors

When an error occurs in a cgi-bin it may either display an explicit
error message result to the user, using the @strong{error.html} template file,
or simply crash. If the cgi-bin crashes, the error messages will appear
in the HTTPD server log or whatever file contains the output of the
error channel of the cgi-bin process. 

If you're running @strong{Apache}, the file is very likely to be named
@code{error_log}.

@node Using mod_perl,  , Cgi-bin errors, Catalog and HTTP server
@section Using mod_perl

All the libraries have been tested with the @strong{mod_perl} Apache module.
The cgi-bin can be registered with the @strong{Registry} module. 
For more information refer to @uref{http://perl.apache.org/, 
the mod_perl home page}.

The advantage of using @strong{mod_perl} is that the cgi-bin executes in
an perl interpretor embedded in the Apache. This is much faster than running
the cgi-bin with a separate perl process. 

Here are the lines that must be added to the access.conf file:

@example
<Location /cgi-bin/Catalog>
SetHandler perl-script
PerlSendHeader On
PerlHandler Apache::Registry
Options ExecCGI
</Location>
@end example

In addition, the @strong{Apache::DBI} module has the ability to cache
the database connection that use the @strong{DBI} package. Since 
@strong{Catalog} uses @strong{DBI} to connect to @strong{MySQL}, it saves
the overhead of connecting and disconnecting each time an action is run.

To enable @strong{Apache::DBI} add the following line to httpd.conf:

@example
PerlModule Apache::DBI
@end example

@node Glossary, Environment variables, Catalog and HTTP server, Top
@chapter Glossary

@table @samp

@item catalog
An ordered collection of records. The order may be alphabetical in which
case we speak of alphabetically ordered catalog. The catalog may be
a tree of categories, each category being linked to one or more records.

@item catalogued table
The table for which a catalog order records. 

@item category
A node of a thematicaly ordered catalog. It is part of the category tree.

@item cgi
Name of the Perl package derived from CGI.pm and providing a few
additional functionalities like recursive CGI calls. 

@item cgi.conf
Path name of the configuration file of the cgi package.

@item instruction
Generic name for a configuration file line containing a keyword
and an value.

@item link an entry
Linking an entry means to associate a record from the catalogued table
with a category of a given catalog. This implies to create a new
record in the @strong{catalog_entry2category_<name>} table.

@item mysql
Name of the Perl package that implements the library on top of the MySQL
DBI package, providing relational constraints, dictionaries based on 
external tables etc.

@item mysql.conf
Path name of the configuration file of the mysql package.

@item sqledit
Name of the Perl package that implements the HTML interface to MySQL database.

@item sqledit.conf
Path name of the configuration file of the sqledit package.

@item tag
Usually used to designate the strings of the form @strong{_TAG_} found
in @code{templates} and replaced by actual values by a cgi-bin.

@item template
A file containing tags and used by cgi-bin to display the output.

@item unlink an entry
Break the link between a record of a catalogued table and a category
of a given catalog. This implies to remove a
record from the @strong{catalog_entry2category_<name>} table.

@cindex XML
@item XML
The Extensible Markup Language (XML) 
is a data format for structured document interchange on the Web.

@cindex XML attribute
@cindex attribute XML
@item XML attribute
An XML attribute a key/value pair found in the opening tag of an element.
For instance <tag attr=val> contains the @strong{attr=val} attribute.

@cindex XML element
@cindex element XML
@item XML element
An XML element is a <tag> bla bla </tag> pair. Elements may be nested.

@end table

@node Environment variables, Troubleshooting, Glossary, Top
@chapter Environment variables

A few environment variables modify the behavior for @code{Catalog}. These
variables have reasonable defaults for most applications.

@table @samp

@item CONFIG_DIR (default .)

The directory where all configuration files leave, @xref{Configuration files, , @code{Configuration files}}.

@item TEMPLATESDIR (default .)

A @strong{:} separated list of directories that contain template files. These
directories are considered in order when searching for a template file. The
first directory that contains the template file wins, 
@xref{Template files introduction, , @code{Template files introduction}}.

@end table

@node Troubleshooting, Concept Index, Environment variables, Top
@chapter Troubleshooting

@table @samp

@cindex Blank page
@cindex Very long actions
@cindex Actions that take a long time
@item Why do I have a blank page when loading/unloading a catalog ?

This is because the action takes a long time. Incoming characters show
that the action is running, @xref{Actions that takes a long time, ,@code{Actions that takes a long time}}.

@cindex /tmp, garbage in
@item My /tmp is filled with files created by @strong{Catalog}
If fct_dir is set to /tmp, @xref{CGI configuration file,,@code{CGI configuration file}}, 
these files come from recursive cgi calls that never returned. This may happen
if you create a catalog, get the HTML form and decide that, after all, you don't
want to create it and click on the Back button in your navigator. There are
a number of situations that leads to this case.

The solution is to run a process that will delete old @strong{Catalog} files
from time to time.

@cindex recursive cgi
@item recursive cgi call failed, check logs
This typically happens when you try to create a symbolic link to a category
while creating a symbolic link to a category. @strong{Catalog} uses
recursive cgi-bin calls to implement functions such as create a new catalog,
edit the record describing a catalog and so on. To prevent 
accidental stacking of recursive calls, a message is issued if you try to
enter a recursive operation while running a recursive operation. 

To get rid of this message reload the @strong{Catalog} control panel and
start again.

@item cannot execute select <table>.rowid from <table>

This error message in the logs of the HTTP server is related to the 
fact that you've created a catalog for a table that do not have a unique
numerical key named rowid, @xref{Catalog management guide, , @code{Catalog management guide}}.

@item I get an error when clicking on the edit link for my newly created catalog

If the associated error message in the logs is 
cannot execute select <table>.rowid from <table>, see the corresponding 
entry in this chapter.

@item Where are the error messages ?
If you're running @strong{Apache} they are in the @strong{error_log} file.

@item Why do I get weird results when using @strong{links_set} ?
Have you checked that the first table mentioned in the @strong{links_set}
parameter is the same as the table mentioned in the @strong{table}
parameter ?

@item Why setting the @strong{links_set} does not show anything ?
You've probably forgot to define the relational structure
of your database in the  @strong{relations.spec} file, 
@xref{Relational constraints, ,@code{Relational constraints}}. 

@item I can't reset the value of a field to NULL, why ?
In a HTML form you must put a white space in the input box to reset
the value of the field to the empty string. It is not possible to specify
that you want to set it to NULL. @xref{Record update (update), ,@code{Record update (update)}}.

@item I have a @strong{Document contains no data} error. What's happening ?
This error may occur for numerous reasons when executing the 
@strong{Catalog} cgi-bin from your WEB browser. It means that a system
error has occurred. It may be a straight bug, an error in the composition
of the template files or a data corruption. Whatever happens, the first
thing to do is to look in the HTTP server logs. The last lines will show
the reason of the error. 

@example
[Wed Jan 13 08:33:49 1999] Catalog: cannot open ./mysql.conf for writing :
       Permission denied at /usr/lib/perl5/site_perl/Catalog/tools/sqledit.pm
       line 2170
@end example

@item I keep getting the error message that suggests editing the MySQL configuration file.

The @code{MySQL} server is probably not running. Check that at least one @strong{mysqld}
process is running. There may be more on systems that show threads on the
ps output. 

@image{images/cannotconnect,10cm,}

If it is running, the permissions are probably wrong. 
By clicking on the @strong{editing mysql.conf} link you will be able to change the user name and
the password used to connect to the @code{MySQL} database. The @strong{mysql.conf} edition page looks like this:

@image{images/mysqlconfedit,10cm,}

@cindex mysql.conf
@cindex editing configuration file mysql.conf
@cindex configuration file mysql.conf
@cindex MySQL password
@cindex MySQL user name

Change the line beginning with @strong{user} with the @code{MySQL} user name
and the line beginning with @strong{passwd} with the password of this user in
the @code{MySQL} database. If you are not sure about which user name and
password to use, contact the system administrator of your machine. Note that
white space characters around the password and the user name are ignored.

@cindex save mysql.conf

To save the modified configuration file click on the save button. The modified
configuration file is displayed again for edition and you should see a line at
the bottom of the screen that says @strong{mysql.conf saved}.

You are now ready to come back to the control panel by clicking on 
the @strong{Back to Catalog Control Panel} link on the top of the page.

For a guide on how to build a sample catalog, @xref{First use, , @code{First use}}.

@item My table named catalog_foobar was destroyed !

All the table names beginning by @code{catalog} are reserved by @code{Catalog}
and may not be used for other purpose. The removal of your table has probably
been done by the Catalog software. Sorry.

@end table

@node Concept Index,  , Troubleshooting, Top
@unnumbered Index of Concepts

@printindex cp

@c @node Name Index,  , Concept Index, Top
@c @unnumbered Index of File Names

@c @printindex fn

@summarycontents
@contents
@bye
