SYNOPSIS

# autotie STDOUT or any other open filehandle

use CGI::SSI (autotie => 'STDOUT');

print $shtml; # browser sees resulting HTML

# or tie it yourself to any open filehandle

use CGI::SSI;

open(FILE,'+>'.$html_file) or die $!; $ssi = tie(*FILE, 'CGI::SSI', filehandle => 'FILE'); print FILE $shtml; # HTML arrives in the file

# or use the object-oriented interface

use CGI::SSI;

$ssi = CGI::SSI->new();

$ssi->if('"$varname" =~ /^foo/'); $html .= $ssi->process($shtml); $ssi->else(); $html .= $ssi->include(file => $filename); $ssi->endif();

print $ssi->exec(cgi => $url); print $ssi->flastmod(file => $filename);

# # or roll your own favorite flavor of SSI #

package CGI::SSI::MySSI; use CGI::SSI; @CGI::SSI::MySSI::ISA = qw(CGI::SSI);

sub include { my($self,$type,$file_or_url) = @_; # my idea of include goes something like this... return $html; } 1; _\|_END_\|_

# # or use .htaccess to include all files in a dir #

# in .htaccess Action cgi-ssi /cgi-bin/ssi/process.cgi <FilesMatch "\.shtml"> SetHandler cgi-ssi </FilesMatch>

# in /cgi-bin/ssi/process.cgi #!/usr/local/bin/perl use CGI::SSI; CGI::SSI->handler(); _\|_END_\|_

DESCRIPTION

\s-1CGI::SSI\s0 is meant to be used as an easy way to filter shtml through \s-1CGI\s0 scripts in a loose imitation of Apache's mod_include. If you're using Apache, you may want to use either mod_include or the Apache::SSI module instead of \s-1CGI::SSI\s0. Limitations in a \s-1CGI\s0 script's knowledge of how the server behaves make some \s-1SSI\s0 directives impossible to imitate from a \s-1CGI\s0 script.

Most of the time, you'll simply want to filter shtml through \s-1STDOUT\s0 or some other open filehandle. \*(C`autotie\*(C' is available for \s-1STDOUT\s0, but in general, you'll want to tie other filehandles yourself:

$ssi = tie(*FH, 'CGI::SSI', filehandle => 'FH'); print FH $shtml;

Note that you'll need to pass the name of the filehandle to \*(C`tie()\*(C' as a named parameter. Other named parameters are possible, as detailed below. These parameters are the same as those passed to the \*(C`new()\*(C' method. However, \*(C`new()\*(C' will not tie a filehandle for you.

\s-1CGI::SSI\s0 has it's own flavor of \s-1SSI\s0. Test expressions are Perlish. You may create and use multiple \s-1CGI::SSI\s0 objects; they will not step on each others' variables.

Object-Oriented methods use the same general format so as to imitate \s-1SSI\s0 directives:

<!--#include virtual="/foo/bar.footer" -->

would be

$ssi->include(virtual => '/foo/bar.footer');

likewise,

<!--#exec cgi="/cgi-bin/foo.cgi" -->

would be

$ssi->exec(cgi => '/cgi-bin/foo.cgi');

Usually, if there's no chance for ambiguity, the first argument may be left out:

<!--#echo var="var_name" -->

could be either

$ssi->echo(var => 'var_name');

or

$ssi->echo('var_name');

Likewise,

$ssi->set(var => $varname, value => $value)

is the same as

$ssi->set($varname => $value) Creates a new \s-1CGI::SSI\s0 object. The following are valid (optional) arguments: DOCUMENT_URI => $doc_uri, DOCUMENT_NAME => $doc_name, DOCUMENT_ROOT => $doc_root, errmsg => $oops, sizefmt => ('bytes' || 'abbrev'), timefmt => $time_fmt, MAX_RECURSIONS => $default_100, # when to stop infinite loops w/ error msg COOKIE_JAR => HTTP::Cookies->new, $type is either 'sizefmt', 'timefmt', or 'errmsg'. $arg is similar to those of the \s-1SSI\s0 \*(C`spec\*(C', referenced below. Sets variables internal to the \s-1CGI::SSI\s0 object. (Not to be confused with the normal variables your script uses!) These variables may be used in test expressions, and retreived using $ssi->echo($varname). These variables also will not be available in external, included resources. Returns the value of the variable named $varname. Such variables may be set manually using the \*(C`set()\*(C' method. There are also several built-in variables: DOCUMENT_URI - the URI of this document DOCUMENT_NAME - the name of the current document DATE_GMT - the same as 'gmtime' DATE_LOCAL - the same as 'localtime' LAST_MODIFIED - the last time this script was modified $type is either 'cmd' or 'cgi'. $arg is similar to the \s-1SSI\s0 \*(C`spec\*(C' (see below). Similar to \*(C`exec\*(C', but \*(C`virtual\*(C' and \*(C`file\*(C' are the two valid types. \s-1SSI\s0 variables will not be available outside of your \s-1CGI::SSI\s0 object, regardless of whether the virtual resource is on the local system or a remote system. Similar to \*(C`include\*(C'. Same as \*(C`flastmod\*(C'. Returns the environment similar to Apache's mod_include. Returns the currently-used HTTP::Cookies object. You may optionally pass in a new HTTP::Cookies object. The jar is used for web requests in exec cgi and include virtual directives.

FLOW-CONTROL \s-1METHODS\s0

The following methods may be used to test expressions. During a \*(C`block\*(C' where the test $expr is false, nothing will be returned (or printed, if tied). The expr can be anything Perl, but care should be taken. This causes problems: $ssi->set(varname => "foo"); <!--#if expr="'\$varname' =~ /^foo$/" -->ok<!--#endif --> The $varname is expanded as you would expect. (We escape it so as to use the $varname within the \s-1CGI::SSI\s0 object, instead of that within our progam.) But the $/ inside the regex is also expanded. This is fixed by escaping the \*(C`$\*(C': <!--#if expr="'\$varname' =~ /^value\$/" -->ok<!--#endif --> The expressions used in if and elif tags/calls are tricky due to the number of escapes required. In some cases, you'll need to write \*(C`\\\\\*(C' to mean \*(C`\\*(C'.

RELATED TO CGI::SSI…

\*(C`Apache::SSI\*(C' and the \s-1SSI\s0 \*(C`spec\*(C' at http://www.apache.org/docs/mod/mod_include.html

AUTHOR

(c) 2000-2005 James Tolley <[email protected]> All Rights Reserved.

This is free software. You may copy and/or modify it under the same terms as perl itself.

CREDITS

Many Thanks to Corey Wilson and Fitz Elliot for bug reports and fixes.