Senga Home Page Information retrieval software GNU
Savannah
FSF France
Node:Top, Next:, Up:(dir)

Top

<<p>ul>

--- The Detailed Node Listing ---

First use

Catalog management guide

Full text search

Catalog tables

Configuration files

External representation

Template files introduction

Catalog template files

SQL template files

CGI introduction

Catalog CGI

SQL manipulation CGI

Catalog and HTTP server

Node:Introduction, Next:, Previous:Top, Up:Top

Introduction

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 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.

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 Catalog:

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

Getting Catalog

The home site of Catalog is Senga 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. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

Node:Setup, Next:, Previous:Getting Catalog, Up:Top

Setup

Catalog requires perl5.006 or higher and MySQL-3.23.39 or higher to run. More detailed instructions may be found in the distribution.

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

To install the Catalog software follow these steps:

  • gtar -zxvf Catalog-1.03.tar.gz
  • cd Catalog-1.03
  • perl Makefile.PL
  • make all
  • make test
  • make install

If something went wrong, check See FAQ.

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

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

Copy this URL, change 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, See FAQ.

The Catalog management guide chapter will show you how to build a fully functional catalog, using an example installed with Catalog, See Catalog management guide.

Node:First use, Next:, Previous:Setup, Up:Top

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 , See Setup.

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

Node:Control Panel, Next:, Previous:First use, Up:First use

Control Panel

First display the control panel using the URL http://www.mymachine.org/cgi-bin/Catalog?context=ccontrol_panel. images/controlpanel.png

Click on the Yes, setup a catalog button to create the administrative tables needed by Catalog. The page displayed in response should be something like : images/controlpanel2.png

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

The Create a demo table link at the bottom of the page creates a sample table for the purpose of the demo. This table, named 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 urldemo table when scrolling the menu that lists all the tables of the database. images/controlpanel3.png

Please chose the urldemo item in the menu and click on the Create it button on the right of the menu.

Node:Creation form, Next:, Previous:Control Panel, Up:First use

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 urlcatalog as shown below. images/catalogcreate.png

You should then click on the 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. images/controlpanel4.png

Node:Catalog editing, Next:, Previous:Creation form, Up:First use

Catalog editing

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

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, Software, Sport and Movies. To create the first category, click on the icon and type Software in the Category name field. images/categoryinsert.png

Then click on the Create it! button. Repeat the same procedure for the Sport and Movies categories. When finished you should get the following screen: images/categoryinsert2.png

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

Node:Inserting entries, Next:, Previous:Catalog editing, Up:First use

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. images/categoryinsert3.png

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

This is an insertion form for the urldemo table. Fill the url and comment field as shown on the screen shot and click on insert. The Software category is displayed again and the newly created entry is shown. images/entryinsert2.png

Node:Browsing, Next:, Previous:Inserting entries, Up:First use

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 Control Panel using the link at the bottom of the screen and then click on browse link. images/browse.png

Node:Conclusion, Previous:Browsing, Up:First use

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, Next:, Previous:First use, Up:Top

Catalog management guide

Node:Goal, Next:, Previous:Catalog management guide, Up:Catalog management guide

Goal

This chapter will explain the most common usage of 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 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, Next:, Previous:Goal, Up:Catalog management guide

Create a table

In the example used in this chapter, the 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).

  • The table must contain a numerical field named rowid which is the primary key so that Catalog can use it. Here is a typical example: 
    create table urldemo (
...
  rowid int autoincrement,
...
  unique urldemo1 (rowid)
);
  • The table field names must only be alphanumerical. Specifically it may not contain underscore which is a reserved character for Catalog.
  • 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 Catalog, See Catalog tables.

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 Catalog tables chapter.

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

Node:Example installed, Next:, Previous:Create a table, Up:Catalog management guide

Example installed

When 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 Catalog is installed). If you've installed the documentation in the HTMLDIR/Catalog/ directory, the URL http://www.mymachine.com/Catalog/ will display the following page: images/example.png

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

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

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

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)
)

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

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

urlcatalog
is a thematic tree that classifies the resources found in the urldemo table. This catalog defines a small hierarchical tree containing /Directory, Full text/Conferences, Full text/Software and so on. The classification is done by associating each record in the urldemo table to a specific category in the thematic tree. This association is maintained in an administrative table of the urlcatalog and is not contained in the urldemo table.
urldate
is a chronological catalog. We have chosen to chronologically order the records of the urldemo table according to their creation date (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.
urlalpha
is an alphabetical catalog. We have chosen to alphabetically order the records of the urldemo table according to the content of the 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.

It must be clearly understood that any number of catalog can be created for a given table (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 catalog_example and is loaded with three catalogs (urlcatalog, urldate and urlalpha) based on the urldemo table. The database may be dropped if you want to get rid of it at a later time with the following MySQL instruction:

drop database catalog_example;

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


HTMLDIR/Catalog/index.html
The entry point.
CGIDIR/admin/
Catalog administration configuration.
CGIDIR/browse/
Catalog user view configuration.
catalog_example database
The example database.
Node:Quick tour, Next:, Previous:Example installed, Up:Catalog management guide

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 Control panel link shows that three catalogs exist, as displayed in the following figure: images/examplecontrolpanel.png

The urldate catalog shows the urldemo records in the order in which they have been created (created field). The urlalpha catalog display an alphabetical index of the records in the urldemo table, based on the comment field. The urlcatalog catalog classifies the URLs in a thematic tree. If you click on the 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 /Directory category of the urlcatalog catalog. images/examplecbrowse1.png

You can also click on the edit button for the urlcatalog catalog to see the administration interface that allows you to create categories, insert records etc. images/examplecedit1.png

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 urlcatalog catalog administration interface thru the link Edit URL catalog. You can compare the display with the non customized version for the /Directory category, as shown in the following figure: images/examplecedit2.png

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 Browse URL catalog (urlcatalog), Chronological history of the URL catalog (urldate) and Alphabetical URL catalog (urlalpha) links). You can compare them with what you saw when clicking on the browse links in the control panel.

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

Node:Records ordering, Next:, Previous:Quick tour, Up:Catalog management guide

Records ordering

When the urlcatalog was created it was bound to the urldemo table. In addition, the order of the urldemo records displayed in a given category was set to ascending lexicographic order on the 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): images/exampleurlcatalog.png

The urldate and urlalpha catalogs were configured in the same way.

Node:Record layout (urlcatalog), Next:, Previous:Records ordering, Up:Catalog management guide

Record layout (urlcatalog)

Our purpose is to understand how the template for the administration of urlcatalog was modified to display the 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: images/examplelayout1.png

We want them to be displayed in this fashion instead: images/examplelayout.png

The 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:

  • display a value
  • conditionally show a part of the template
  • repeat a part of the template to display lists of values

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

For instance, in the following cedit.html template, the part enclosed between <!- start categories -> and <!- 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 cedit.html template:

<title>Edit category _CATEGORY_</title>

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

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>

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

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>

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 -->

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 -->

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

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

The entry part (delimited by the <!- start entry -> and <!- end entry -> HTML comments) will be repeated for each record in the category. We want to preserve the _LINKS_ tag that displays the buttons to perform actions on the record (remove, unlink and edit). But we want to change _DEFAULTROW_ to display only the fields of interest. The values of the fields of the urldemo table for the displayed record are available with the following tags : _URL_, _COMMENT_ and _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 -QUOTED string to the field name. This variation replaces HTML reserved characters such as quote (') or double quote (") by the appropriate HTML elements. This is useful to include a value in quotes, for instance. Here is the modified template part:

<!-- 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 -->

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

Node:Overriding a template (urlcatalog), Next:, Previous:Record layout (urlcatalog), Up:Catalog management guide

Overriding a template (urlcatalog)

We have modified the cedit.html template and now we would like Catalog to use it instead of the default template. The simplest method would be to create a file named cedit.html in the cgi-bin/admin directory. The default templates used by Catalog are included in the code of the application, therefore you will not find a cedit.html file anywhere. You will have to create it, copying it from the example or from this documentation. When the 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 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 style cgi-bin parameter and the templates.conf configuration file.

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

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

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

In short, the modified cedit.html template is put in the urlcatalog_cedit.html file and cedit.html is mapped to urlcatalog_cedit.html for the urlcatalog style in the 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), Next:, Previous:Overriding a template (urlcatalog), Up:Catalog management guide

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 urlcatalog was modified to display as shown in the following figures:

  • The root of the catalog. images/examplecbrowse2.png
  • The display of a category containing records. images/examplecbrowse3.png

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

  • The top level category (root category) is displayed using a separate template.
  • The editing buttons are not available.

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

Here is the default cbrowse_root.html:

<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 -->

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 <!- 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 images/examplelayout2.png

instead of images/examplelayout3.png

We will have to modify the part of the template that is between <!- start categories -> and <!- end categories ->. Within this part there is a nested part delimited by <!- start entry -> and <!- 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 entry part with something else. Fortunately, the row part is precisely designed for this purpose. Here is the final result:

<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>

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

Now we want to customize the 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 <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 cbrowse.html template:

<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>

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

#
# 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
Node:Customizing search results (urlcatalog), Next:, Previous:Customizing user view (urlcatalog), Up:Catalog management guide

Customizing search results (urlcatalog)

Now that the browsing interface for 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 csearch.html and contains:

<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 -->

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

  • if categories match the search criterion (categories part)
  • if we only want categories and no categories match the search criterion (nocategories part)
  • if records match the search criterion (records part)
  • if no categories and no records match the search criterion (norecords part)

Assuming that we search for records in the example database, the default display looks like this: images/examplecsearch1.png

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

<!-- start records -->

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

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

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 -->

This subpart must always be in the 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 csearch.html into urlcatalog_csearch.html in the templates.conf file.

#
# 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

The search results when searching for www is now: images/examplecsearch2.png

At this point we have covered all the operations needed to customize the user view of the urlcatalog thematic catalog as shown when clicking on the Browse URL catalog (urlcatalog) link in the example HTML entry point. By defining a new 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), Next:, Previous:Customizing search results (urlcatalog), Up:Catalog management guide

Customizing chronological browsing (urldate)

The urldate catalog displays the entries of the table urldemo in chronological order. Using the browse link in the control panel, you will see the following screen: images/examplecdate1.png

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 cdate_default.html. It contains two logical parts : the display of the calendar and the display of the records.

<html>
<body bgcolor=#ffffff>
<title>Date catalog</title>
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 -->

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>

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

The part of the template that displays the calendar contains three nested parts : days is included in months, itself included in 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 date cgi-bin parameter, however, it is possible to require that the cgi-bin only displays a given time interval. For instance, if date is set to 1999, it will only consider the records of year 1999. If the date is set to 199902 it will only consider the records of February 1999. If the date is set to 19990219 it will only consider the records of February, 19 1999. Here is a display for this specific day: images/examplecdate2.png

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:

  • unbounded (cdate_default.html). images/examplecdate3.png
  • a specific year (cdate_year.html). images/examplecdate4.png
  • a specific month (cdate_month.html). images/examplecdate5.png
  • a specific day (cdate_day.html). images/examplecdate6.png

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 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 template cgi-bin parameter. For instance, if the chronological display is called with

template=year

then it will use the template cdate_year.html instead of cdate_default.html.

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

<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>

The records part has been removed because we don't want to display them. The months and days parts of the 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 (_YEARLINK_) that leads to the chronological display limited to the current year. We have appended the &template=year parameter to this tag so that the cdate_year.html is used instead of cdate_default.html.

Let's now configure the cdate_year.html template. Here is the customized template:

<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>

As for cdate_default.html, we have removed the parts that are not wanted : records and 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 (<title>) inside the years part. This is necessary because the _YEARFORMATED_ is only substituted in the 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 months part we use the same method as in cdate_default.html to force the usage of the cdate_month.html template when following the hypertext link to a specific month : we append &template=month.

One more trick is used to control the format of the _MONTHFORMATED_ tag. By default _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 <!- params format => '%M' -> comment in the months part controls the format of the _MONTHFORMATED_ tag. The string in single quotes is a MySQL date format specification (more information may be found in the MySQL date_format function documentation). The %M says that we only want the name of the month. The same format control method applies to the _YEARFORMATED_ and _DAYFORMATED_ tags.

Let's now configure the cdate_month.html template. Here is the customized template:

<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>

There is no new concept in this template. The title (<title>) has been moved to the months part to show the current month using _MONTHFORMATED_ because this tag is only substituted in the 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 cdate_day.html template is built as follows:

<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>

We now see the records part which looks exactly the same as in the 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), Next:, Previous:Customizing chronological browsing (urldate), Up:Catalog management guide

Customizing alphabetical browsing (urlalpha)

The urlalpha catalog displays the entries of the table urldemo in alphabetical order, based on the comment field. Using the browse link in the control panel, you will see the following screen: images/examplecalpha1.png

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: images/examplecalpha2.png

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

The default calpha_root.html template is as follows:

<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>

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: images/examplecalpha3.png

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

<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_.png border=0>
  </a>
  <font size=-1>_ACOUNT_</font>
 </td>
 <td>
  <a href=_BURL_>
   <img src=_HTMLPATH_/images/letter_BLETTER_.png border=0>
  </a>
  <font size=-1>_BCOUNT_</font>
 </td>
                 .
                 .
                 .
</tr>
</table>

We have done two things : put the letters in a table and expand the default _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:

_AURL_
is the URL that shows the records for letter A.
_ACOUNT_
is the number of records for the letter A.
_ALETTER_
is either the letter A in lower case (a), if there is at least one record for which the comment field starts with an A, or the string 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 lettera.png is shown if there are records and the GIF file named lettera0.png is shown if there are no records.

The lines specifying the display for one letter must be duplicated for each letter. Note that we use the _HTMLPATH_ tag to locate the images installed by 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 (calpha.html) is much simpler. The default template is as follows:

<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 -->

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

<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 -->
images/examplecalpha4.png

Note that the _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, Previous:Customizing alphabetical browsing (urlalpha), Up:Catalog management guide

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 Catalog. You can modify all of them to fit your needs.

Node:Full text search, Next:, Previous:Catalog management guide, Up:Top

Full text search

Node:Default full text, Next:, Previous:Full text search, Up:Full text search

Default full text

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

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

This basically means that only the isolated foobar word will be found and not the word foobarnitz, See 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, See Catalog configuration file.

like '%word1 word2%'
Node:Real full text, Previous:Default full text, Up:Full text search

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, See Hook Fulcrum configuration file.

To activate the automatic indexation of a MySQL database set the hook attribute of the mysql.conf file to either Catalog::tools::hook_mifluz or Catalog::tools::hook_fulcrum, See MySQL configuration file.

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

Node:Catalog tables, Next:, Previous:Full text search, Up:Top

Catalog tables

Node:Catalog tables introduction, Next:, Previous:Catalog tables, Up:Catalog tables

Catalog tables introduction

The catalog table has a record for every existing catalog. The other tables have names that end with the name of the catalog (NAME).

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

The 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, Next:, Previous:Catalog tables introduction, Up:Catalog tables

catalog

Describe all the existing catalogs.

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)
)
Node:catalog_category_NAME, Next:, Previous:catalog, Up:Catalog tables

catalog_category_NAME

Describe a category (theme only).

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 '',
)
Node:catalog_category2category_NAME, Next:, Previous:catalog_category_NAME, Up:Catalog tables

catalog_category2category_NAME

Link two categories (theme only).

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,
  #
  # Category name replacement
  #
  replacement varchar(255),
  #
  # External identifier to synchronize with alien catalogs
  #
  externalid varchar(32) not null default '',
)
Node:catalog_entry2category_NAME, Next:, Previous:catalog_category2category_NAME, Up:Catalog tables

catalog_entry2category_NAME

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

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 '',
)
Node:catalog_path_NAME, Next:, Previous:catalog_entry2category_NAME, Up:Catalog tables

catalog_path_NAME

Maps category id to category path (theme only).

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)
)
Node:catalog_alpha_NAME, Next:, Previous:catalog_path_NAME, Up:Catalog tables

catalog_alpha_NAME

Count information for each letter (alpha only).

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,
)
Node:catalog_date_NAME, Previous:catalog_alpha_NAME, Up:Catalog tables

catalog_date_NAME

Count information for each period (date only).

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)
)
Node:Configuration files, Next:, Previous:Catalog tables, Up:Top

Configuration files

The 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 CONFIG_DIR environment variable is set, See Environment variables.

The instructions found in the configuration files alter the behavior of 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 (#) are ignored as well as empty lines.

A configuration instruction has the following form

keyword = value

or

keyword : value

The prefered form is using the equal sign instead of colon.

The keyword can contain alpha-numerical characters, underscore (_) and dash (-). 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:

#
# Name of the database to connect.
#
base = test

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 end, alone on a line. Here is a simple example:

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

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:

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

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 Catalog.

Node:Catalog configuration file, Next:, Previous:Configuration files, Up:Configuration files

Catalog configuration file

Used by the Catalog package (Catalog.pm). It influences the global behavior of Catalog.


path_separator (optional, default /)
The string that separates path components of the _PATH_ tag in the navigation pages of the catalog, See cedit.html.
path_root_label (optional, default Root)
Label shown for the root of the path shown as the _PATH_ tag in the navigation pages of the catalog, See cedit.html.
pathcontext_params (optional)
Parameters that must be used in the pathcontext context, See Intuitive navigation (pathcontext). If set it must contain the name parameter that specifies the name of the catalog to display.
search (optional, nested)
Specifies fields searched and extracted when searching records and the order in which they are displayed, See Catalog search (csearch).

<catalog name> (optional, nested)
The following instructions only apply to the thematic catalog whose name is catalog name. All the field names must belong to the table associated with the named catalog.

searched (optional)
A comma separated list of fields to be searched. These fields must be of type char, varchar or text. If not specified, all the fields of the listed types are used. All the fields must be fully qualified by prepending the name of the table in the following way: table.field.
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, See 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 must be fully qualified by prepending the name of the table in the following way: table.field.
order (optional)
An ORDER BY clause to sort the records found. The fields mentioned in this clause must be fully qualified by prepending the name of the table in the following way: table.field.

Here is an example configuration file:

#
# 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
Node:MySQL configuration file, Next:, Previous:Catalog configuration file, Up:Configuration files

MySQL configuration file

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


base (mandatory)
Name of the MySQL database to connect. Equivalent of base parameter in mysql command.
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.
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.
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.
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.
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.
auto_created (optional)
If this instruction exists and its value is set to yes, the field named created is treated in a special way in every table. It must be of type datetime not null. Each time a record is inserted using the mysql package, if the created field does not contain any value, it is set with the current date.
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:
Catalog::tools::hook_fulcrum
See Hook Fulcrum configuration file.
Catalog::tools::hook_mifluz
See Hook Mifluz configuration file.

Here is an example configuration file:

#
# 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
Node:CGI configuration file, Next:, Previous:MySQL configuration file, Up:Configuration files

CGI configuration file

Used by the cgi package (cgi.pm).

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


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.

Here is an example configuration file:

#
# Derived cgi class (Catalog::cgi) configuration file
#
#
# Directory that will contain the saved execution contexts.
#
fct_dir = /usr/local/lib/interbat/cache
Node:Install configuration file, Next:, Previous:CGI configuration file, Up:Configuration files

Install configuration file

Used by the sqledit package (sqledit.pm).

This configuration file is created during the installation. It is used by sqledit to find the location of the Catalog components.


cgidir (optional)
The absolute path of the cgi-bin directory.
cgipath (optional)
The absolute location of the cgi-bin directory.
config_dir (optional)
The absolute path of the directory containing configuration files.
htmldir (optional)
The absolute location of the cgi-bin directory.
htmlpath (mandatory)
Absolute location of the 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.
infodir (optional)
The absolute path of the Emacs info directory where the documentation was installed.

Here is an example configuration file:

#
# 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
Node:SQL editor configuration file, Next:, Previous:Install configuration file, Up:Configuration files

SQL editor configuration file

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.


context_allow (optional, default *)
The list of allowed values for the 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, See 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:

"%s context is not allowed"
See Messages translation.

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

context_allow = cbrowse

encoding (optional, default ISO-8859-1)
Defines the encoding of the user interface. The HTML pages sent to the client navigator will all be encoded using this encoding. All the input parameters received from HTML forms must be encoded in the same way. The internal charset of Catalog is UTF-8. Input and output is converted to and from UTF-8 using XPG4 iconv thru the Text::Iconv interface.
functions (optional, nested)
Defines functions that may be used as values for the normalize and match instructions in the check nested instruction.

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 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 $_ variable contains the current value of the field for which the function was called. See the description of the match and 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 Perl libraries here.

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

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: 
check
        table1
                field1
                        normalize = <function>
                        match = <function>
                        mandatory = yes
                end
                field2
                        ...
                end
                ...
        end
        ...
end

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


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

The 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

  • 1 if the normalization of the value was a success.
  • 0 if the value cannot be normalized.

If the return value is 1, the $_ 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:

table %s : field %s : value %s normalize failed %s
See Messages translation.
match (optional, default returns 1)
The <function> may be either a valid Perl function or a function defined in the function section of this configuration file. The $_ variable contains the value of the field for the current record.

The 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

  • 1 if the value matches the constraint.
  • a string if the value does not match the constraint.

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

table %s : field %s : value %s match failed %s
See Messages translation.

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

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:

table %s : field %s must be set
See Messages translation.

dictionaries (optional, nested)

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

dictionary
        tablename1
                where = <where clause1>
                order = <order clause1>
        end
        tablename2
                where = <where clause2>
                order = <order clause2>
        end
        ...
end

where (optional)
The <where clause> may be any expression valid in a SQL where clause. The beginning of the SQL order is something like 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 See Template files introduction.
order (optional)
The <where clause> may be any expression valid in a SQL order clause. The beginning of the SQL order is something like 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.

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:

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

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


select
Provides instructions for customizing a select HTML tag.

multiple (optional, default 4)
The value of the multiple parameter in the select tag.
labelnull (optional, default ---------)
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.

table
Provides instructions for customizing the display of a set of radio buttons or checkboxes within a table.

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

nph (optional, default no)
Set it to yes if your script is nph (non parsed header). This changes the header sent by Catalog. For more information on nph cgi-bin see the Apache documentation and the CGI.pm documentation.
Node:Template configuration file, Next:, Previous:SQL editor configuration file, Up:Configuration files

Template configuration file

style (optional, nested)
Maps template file names according to style names.

The structure of this nested instruction is as follows:

style
        stylename
                templatepath = othertemplatepath
                ...
        end
        ...

The templatepath must be a template path name as defined for the current application, See Template files introduction.

#
# 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
Node:Hook Fulcrum configuration file, Previous:Template configuration file, Up:Configuration files

Hook Fulcrum configuration file


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.


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.


<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.


params (mandatory, nested)
Database wide parameters.


table (mandatory)
The name of the fulcrum table that will contain the indexed data.

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


<sql tablename> (mandatory, nested)

params (optional, nested)

where (optional)
A where clause applied on the SQL table that will limit the scope of records taken in account during indexing.


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.

table (mandatory)
An SQL table linked to the current table, See Relational constraints.
fields (mandatory)
The list of fields from the table that must be imported.

fields (mandatory, nested)
All the keywords must be valid fieldnames of the SQL table.

<sql fieldname>

field
The name of the fulcrum field that will contain a copy of the value from the SQL field.

query (mandatory, nested)
Specifications to build the full text query.


table (mandatory)
The name of the fulcrum table to use for the query.
divide_or (optional)
The division factor applied to or query in each group.
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 r_. If an order clause is present must also contain all the fields mentioned in the order clause (due to fulcrum limitations).
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).
order (optional)
Order by clause.
constraint_weight (optional)
If a constraint matches in a given group, give it the weight mentioned in here.
templates (optional, nested)
Re-map each automatically generated sub template name.

groups (mandatory, nested)


<group number> (mandatory nested)
Each group number is taken in numerical order to build the query.

where (optional)
The record must match the where condition in addition to the generated full text query.
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 divide_or parameter.
constraint (optional)
If specified list the fields on which a constraint may be applied.
fields (mandatory)
The list of fulcrum table fields that will be searched during the full text search process.

The general structure of the file is as follows:

#
# 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
    #
    table