/ 
CGI-CIPP-0.02
River stage zero No dependents
/ CGI::CIPP

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.

Beware that if you place your CIPP files into a subdirectory of your webservers document root, you risk that someone can fetch your CIPP source files, if he knows the URL of your CIPP document root. If you do not use the mod_rewrite configuration explained beyond, you never should place your CIPP files into your webservers document root. There is no advantage for doing this.

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, the 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. To avoid confusion about this, you should configure your webserver in that way, that the CGI wrapper program has a URL which is located inside your webservers document root. This way using relative URLs is easier, because you never left the document root of your webserver.

If you're using the Apache webserver (what is always recommended :) you have several alternatives of doing this, e.g

- using a extra ScriptAlias
- using mod_rewrite

Using a extra ScriptAlias

This is a example configuration of using a ScriptAlias to configure CIPP for easy usage of relative URLs.

These are the corresponding basic Apache configuration parameters:

DocumentRoot	"/www/htdocs"
ScriptAlias	"/cipp" "/www/cgi-bin/cipp"

The CIPP document root is still placed outside your webservers document root, so nobody can access your CIPP source files directly.

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

http://somehost/cipp/foo/test.cipp

The disadvantage of this configuration is, that your CIPP root directory /www/cippfiles cannot contain other files than CIPP files. It is not possible to put images or static HTML documents here, because you cannot reach these documents with normal URLs.

Using mod_rewrite

You avoid the above mentioned disadvantage if you use mod_rewrite. These are the corresponding basic Apache configuration parameters (please refer to the Apache documentation for details). You will need Apache version 1.2.x or better for using mod_rewrite.

DocumentRoot	"/www/htdocs"
ScriptAlias	"/cgi-bin" "/www/cgi-bin"
RewriteEngine	"on"
RewriteRule	"^/(.*\.cipp.*)" "/cgi-bin/cipp/$1" [PT]

The CGI wrapper program is still located in a extra cgi-bin directory. But the RewriteRule directs all URL's with the suffix .cipp, no matter where they are located, to the CIPP CGI wrapper program.

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

document_root	/www/htdocs

We now declare the Apache DocumentRoot also to the document_root of CGI::CIPP, so no special subdirectory is needed. The Apache rewrite engine is responsible for translating URL's with the suffix .cipp to a appropriate call of the CGI wrapper program.

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 RewriteRule above. So you can mix traditional static documents with CIPP files and relative URL adressing is no problem at all.

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