Catalog
view release on metacpan or search on metacpan
doc/catalog.texinfo view on Meta::CPAN
* 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
doc/catalog.texinfo view on Meta::CPAN
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_}
doc/catalog.texinfo view on Meta::CPAN
@item Parameters
@cindex parameter, context
@cindex parameter, name
@cindex parameter, text
@cindex parameter, what
@cindex parameter, mode
@cindex parameter, querymode
@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},
@strong{pathcontext} or @strong{static}. The href links displayed in the result page will use the specified context.
The @strong{static} context allows to include a search form that uses the static dump of a catalog.
When set to @strong{static}, the @strong{_SCRIPT_} tag will be replaced by the dump location stored in
the @strong{dumplocation} field of the record describing the catalog,
@xref{Dump a thematic catalog (cdump_confirm), ,@code{Dump a thematic catalog (cdump_confirm)}}.
If you want to include a search form in the results of the search, make sure that the templates
contains the explicit location of the cgi-bin script to use instead of @strong{_SCRIPT_}.
@item querymode (optional, default @strong{simple})
Specifies syntax of the search string. If set to @strong{simple}, @code{AltaVista} simple search syntax is used.
If set to @strong{advanced}, @code{AltaVista} advanced search syntax is used.
@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)}}.
( run in 1.599 second using v1.01-cache-2.11-cpan-5a3173703d6 )