DESCRIPTION

This is a very simple program that shows how to use the SWISH::API module in a CGI script. Unlike swish.cgi, this is suppose to not have many built-in features. So don't ask why it doesn't do something. The point is that this is used as a starting point that YOU customize.

This program is intended for programmers that want to create a custom search script.

This program does require that some modules are installed from CPAN. See REQUIREMENTS below for details and an explanation of why.

This program does not handle multiple index files, special metanames that can be selected by drop-down boxes or anything else fancy. Again, the point is that this script gets customized by you.

Template-Toolkit is used to render the output. The template is included below the program code in the __DATA__ section. A Template-Toolkit ``filter'' is created to highlight terms in the description. The filter uses the same modules that the swish.cgi script uses for highlighting.

The template can be placed in its own file if you like. That's the normal way templates are used. It's in the __DATA__ section in this script so that only one file is needed. If you run under mod_perl or SpeedyCGI you must use a separate template file.

The index file is hard-coded as index.swish-e. Change it as needed. The script uses page numbers instead of record numbers. Record numbers might be more flexible.

This script can be run under SpeedyCGI by changing the top line to:

#!/usr/bin/speedy -w

and installing SpeedyCGI, of course. When run under SpeedyCGI or mod_perl the template must be moved out into a separate file. Set the INCLUDE_PATH to the directory where you store the template file.

The script can also be run as a mod_perl handler. If you use mod_perl you might want to use Apache::Request instead of CGI.pm.

[ TOC ]

USAGE

The script is installed when Swish-e is installed. On unix-like systems this will like be at /usr/local/lib/swish-e/search.cgi. If you used a different --prefix option at compile time then it would be wise to look there, instead. Windows users will find the program someplace similar, but different. If installed as part of your OS distribution then it might be in /usr/lib/swish-e.

Install the required modules (see next section) and then copy or symlink the program to where you normally run CGI scripts. Use .htaccess or whatever your web server requires to indicate that the script is indeed a CGI script.

Create an index. If the index is not in the current working directory when the script is run, and is not called ``index.swish-e'' (the default swish-e index name) then modify the script to find the correct index file.

Testing CGI script from the command line first will impress your friends.

The script is lightly commented so that hopefully you can understand how it works and thus understand how to add the features you need.

[ TOC ]

REQUIREMENTS

To use this script as-is a few Perl modules will need to be installed. You are not required to use these modules, but I like them and thus I'm recommending that you give them a try.

Template-Toolkit

Template-Toolkit (or TT) is available from CPAN or from

http://search.cpan/org/ http://tt2.org/

TT is used to generate the HTML output. It's good code design to separate the output generation from the ``model'' code that does the work of fetching the data.

I'm a big fan of Template-Toolkit. It's simple enough that it's easy to learn how to work with basic templates. It's also not limiting and provides power to do what's needed in the template without requiring too much setup in the logic part of your code. Note in the code how TT works directly with the objects returned by SWISH::API. TT's dot notation means that you can change the backend data (e.g. from a hash to an object) and the template does not need to change.

Please give TT a try. It's a much better use of your time than writing Yet Another Homemade Templating System.

HTML::FillInForm

This module is also available from CPAN

http://search.cpan.org/

HTML::FillInForm makes HTML forms ``sticky'' -- that is, it takes previous data from a CGI request and fills in the form elements. What this means is you can write very plain, basic HTML forms in the template and HTML::FillInForm will make them sticky.

The other way to have sticky forms is to use the CGI.pm module (which can be used directly with Template-Toolkit). Besides requiring that the large CGI.pm module gets loaded, it means there's more programming-like code in the template, which should really just be basic HTML, and means the template writer needs to also learn a little more Perl.

[ TOC ]