NAME

CGI::CIPP - Use CIPP embedded HTML Pages in a CGI environment

DESCRIPTION

CGI::CIPP is a Perl module which enables you to use CIPP on every CGI capable webserver. It is based on a central wrapper script, which does all the preprocessing. It executes the generated Perl code directly afterwards.

Additionally, it implements a filesystem based cache for the generated code. Preprocessing is done only when the corresponding CIPP source code changed on disk, otherwise this step is skipped.

WHAT IS CIPP?

CIPP is a Perl module for translating CIPP sources to pure Perl programs. CIPP defines a HTML embedding language also called CIPP which has powerful features for CGI and database developers.

Many standard CGI and database operations (and much more) are covered by CIPP, so the developer does not need to code them again and again.

CIPP is not part of this distribution, please download it from CPAN.

SIMPLE CIPP EXAMPLE

To give you some imagination of what you can do with CIPP: here is a (really) simple example of using CIPP in a HTML source to retrieve some information from a database. Think this as a HTML page which is "executed" on the fly by your webserver.

Note: there is no code to connect to the database. This is done implicitely. The configuration is taken from the central CGI::CIPP wrapper srcipt.

  # print table of users who match the given parameter
  
  <?INTERFACE INPUT="$search_name">

  <HTML>
  <HEAD><TITLE>tiny litte CIPP example</TITLE></HEAD>
  <BODY>
  <H1>Users matching '$search_name'</H1>
  <P>

  <TABLE BORDER=1>
  <TR><TD>Name</TD><TD>Adress</TD><TD>Phone</TD></TR>
  <?SQL SQL="select name, adress, phone
             from   people
             where  name like '%' || ? || '%'"
        PARAMS="$search_name"
        MY VAR="$n, $a, $p">
    <TR><TD>$n</TD><TD>$a</TD><TD>$p</TD></TR>
  <?/SQL>
  </TABLE>

  </BODY>
  </HTML>

SYNOPSIS

Create a CGI program in a directory, where CGI programs usually reside on your server (e.g. /cgi-bin/cipp), or configure this program another way to be a CGI program (see sections beyond for details).

This program is the central CGI::CIPP wrapper. It only consists of a single function call to the CGI::CIPP module, with a hash of parameters for configuration. This is a example:

  #!/usr/local/bin/perl

  use strict;
  use CGI::CIPP;

  # this program has the URL /cgi-bin/cipp

  CGI::CIPP->request (
        document_root  => '/www/cippfiles',
        directoy_index => 'index.cipp',
        cache_dir      => '/tmp/cipp_cache',
        databases      => {
                test => {
                        data_source => 'dbi:mysql:test',
                        user        => 'dbuser',
                        password    => 'dbpassword',
                        auto_commit => 1
                },
                foo => {
                        ...
                }
        }
        default_database => 'test',
        lang => 'EN'
  );

A brief description of the parameters passed to the CGI::CIPP->request call follows:

document_root

This is the base directory where all your CIPP files resides. You will place CIPP programs, Includes and Config files inside this subdirectory. Using subdirectories is permitted. If you use the Apache webserver you should point this to your Apache DocumentRoot and set up a extra handler for CIPP. See the Apache chapter beyond for details.

directory_index

If you want CGI::CIPP to treat a special filename as a directory index file, pass this filename here. If you access a directory with CGI::CIPP and a according index file is found there, it will be executed.

cache_dir

This names the directory where CGI::CIPP can store the preprocessed CIPP programs. If the directory does not exist it will be created. Aware, that the directory must have write access for the user under which your webserver software is running.

databases

This parameter contains a hash reference, which defines several database configurations. The key of this hash is the CIPP internal name of the database, which can be addressed by the DB parameter of all CIPP SQL commands. The value is a hash reference with the following keys defined.

data_source

This must be a DBI conforming data source string. Please refer to the DBI documentation for details about this.

user

This is the username CIPP uses to connect to the database

password

This password is used for the database user.

auto_commit

This parameter sets the initial state of the AutoCommit flag. Please refer to the description of the <?AUTOCOMMIT> command or the DBI documentation for details about AutoCommit.

default_database

This takes the name of the default database. This database is always used, if a CIPP SQL command ommits the DB parameter. The value passed here must be a defined key in the databases hash.

lang

CIPP has multilanguage support for its error messages, actually english ('EN') and german ('DE') are supported.

The CGI wrapper program uses the CGI feature PATH_INFO to determine which page should be executed. To execute the CIPP page 'test.cipp' located in '/www/htdocs/cippfiles/foo/test.cipp' you must specify the following URL (assuming the configuration of the example above):

  http://somehost/cgi-bin/cipp/foo/test.cipp

You simply add the path of your page (relative to the path you specified with the document_root parameter) to the URL of the CGI wrapper.

Be aware of the real URL of your page if you use relative URL's to non CIPP pages in your CIPP page. In the above example relative URL's must consider that the CGI wrapper program is located in a different location as the directory you declared as the CIPP document root. This implies that it is not possible to place CIPP program files and traditional static HTML documents or images into the same directory.

APACHE CONFIGURATION

If you're using the Apache webserver (what is always recommended :) you can avoid the above stated disadvantages. In this case you should configure your CIPP CGI wrapper program as a extra handler.

Simply add the following directives to your appropriate Apache config file:

  AddHandler x-cipp-execute cipp
  Action x-cipp-execute /cgi-bin/cipp

The CGI wrapper program is still located in a extra cgi-bin directory. But now all files with the extension .cipp are handled through it.

The CGI::CIPP configuration slightly changes, we reasign the document_root:

  document_root /www/htdocs

We now declare the Apache DocumentRoot also to be the document_root of CGI::CIPP, so no special subdirectory is needed.

This is a example URL for a CIPP page located in /www/htdocs/foo/test.cipp

  http://somehost/foo/test.cipp

Now you are able to place CIPP files on your webserver wherever you want, because there is no special CIPP directory anymore. Only the suffix .cipp is relevant, due to the AddHandler directive above. So you can mix traditional static documents with CIPP files and relative URL adressing is no problem at all.

Security Hint

To prevent users from viewing your Include or Config files, you should configure your webserver to forbid access to these files. In case of Apache add the following contatiner to your Apache configuration:

  <Location ~ "\.(conf|inc)$">
    Order allow,deny
    Deny from all
  </Location>  

This assumes that you name your Config files *.conf and your Include *.inc. CIPP does not care about the extensions of your Config and Include files. To make your life easier, you should ;)

CGI::SpeedyCGI and CIPP::CGI

There exists a really nice module called CGI::SpeedyCGI, which is available freely via CPAN. It implements a nifty way of making Perl CGI processes persistent, so subseqeuent CGI calls are answered much more faster.

Using CIPP::CGI together with CGI::SpeedyCGI is easy. Simply replace the perl interpreter path in the shebang line #!/usr/local/bin/perl with the according path to the speedy program, e.g.: #!/usr/local/bin/speedy.

Refer to the CGI::SpeedyCGI documentation for details about configuring SpeedyCGI. I recommend the usage of the -r and -t switch, so you are able to control the number of parallel living speedy processes, e.g.

  #!/usr/local/bin/speedy -- -r30 -t120

Each speedy process now answeres a maximum of 30 requests and then dies. If a process is idle for longer than 120 secs it dies also.

AUTHOR

Joern Reder <joern@dimedis.de>

COPYRIGHT

Copyright 1998-1999 Joern Reder, All Rights Reserved

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), CIPP(3pm), Apache::CIPP(3pm), CGI::SpeedyCGI(3pm)