Ken Williams > Apache-SSI > Apache::SSI

Download:
Apache-SSI-2.19.tar.gz

Dependencies

Annotate this POD

Related Modules

CGI::SSI
Data::Dumper
HTML::Template
CGI::SSI_Parser
File::Find
Date::Calc
Text::Template
Apache::Registry
HTML::Mason
LWP::Simple
more...
By perlmonks.org

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 2.19   Source  

NAME ^

Apache::SSI - Implement Server Side Includes in Perl

SYNOPSIS ^

In httpd.conf:

    <Files *.phtml>  # or whatever
    SetHandler perl-script
    PerlHandler Apache::SSI
    </Files>

You may wish to subclass Apache::SSI for your own extensions. If so, compile mod_perl with PERL_METHOD_HANDLERS=1 (so you can use object-oriented inheritance), and create a module like this:

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

    #embedded syntax:
    #<!--#something param=value -->
    sub ssi_something {
       my($self, $attr) = @_;
       my $cmd = $attr->{param};
       ...
       return $a_string;   
    }
 
 Then in httpd.conf:
 
    <Files *.phtml>
     SetHandler perl-script
     PerlHandler MySSI
    </Files>

DESCRIPTION ^

Apache::SSI implements the functionality of mod_include for handling server-parsed html documents. It runs under Apache's mod_perl.

In my mind, there are two main reasons you might want to use this module: you can sub-class it to implement your own custom SSI directives, and/or you can parse the output of other mod_perl handlers, or send the SSI output through another handler (use Apache::Filter to do this).

Each SSI directive is handled by an Apache::SSI method with the prefix "ssi_". For example, <!--#printenv--> is handled by the ssi_printenv method. attribute=value pairs inside the SSI tags are parsed and passed to the method in a hash reference.

'Echo' directives are handled by the ssi_echo method, which delegates lookup to methods with the prefix "echo_". For instance, <!--#echo var=DOCUMENT_NAME--> is handled by the echo_DOCUMENT_NAME method.

You can customize behavior by inheriting from Apache::SSI and overriding 'ssi_*' and 'echo_*' methods, or writing new ones.

SSI Directives

This module supports the same directives as mod_include. At least, that's the goal. =) For methods listed below but not documented, please see mod_include's online documentation at http://www.apache.org/ .

CHAINING HANDLERS ^

There are two fairly simple ways for this module to exist in a stacked handler chain. The first uses Apache::Filter, and your httpd.conf would look something like this:

 PerlModule Apache::Filter
 PerlModule Apache::SSI
 PerlModule My::BeforeSSI
 PerlModule My::AfterSSI
 <Files ~ "\.ssi$">
  SetHandler perl-script
  PerlSetVar Filter On
  PerlHandler My::BeforeSSI Apache::SSI My::AfterSSI
 </Files>

The "PerlSetVar Filter On" directive tells the three stacked handlers that they should use their filtering mode. It's mandatory.

The second uses Apache::OutputChain, and your httpd.conf would look something like this:

 PerlModule Apache::OutputChain
 PerlModule Apache::SSIChain
 PerlModule My::BeforeSSI
 PerlModule My::AfterSSI
 <Files ~ "\.ssi$">
  SetHandler perl-script
  PerlHandler Apache::OutputChain My::AfterSSI Apache::SSIChain My::BeforeSSI
 </Files>

Note that the order of handlers is reversed in the two different methods. One reason I wrote Apache::Filter is to get the order to be more intuitive. Another reason is that Apache::SSI itself can be used in a handler stack using Apache::Filter, whereas it needs to be wrapped in Apache::SSIChain to be used with Apache::OutputChain.

Please see the documentation for Apache::OutputChain and Apache::Filter for more specific information. And look at the note in CAVEATS too.

CAVEATS ^

* When chaining handlers via Apache::Filter, if you use <!--#include ...--> or <!--#exec cgi=...-->, then Apache::SSI must be the last filter in the chain. This is because Apache::SSI uses $r->lookup_uri(...)->run to include the files, and this sends the output through C's stdout rather than Perl's STDOUT. Thus Apache::Filter can't catch it and filter it.

If Apache::SSI is the last filter in the chain, or if you stick to simpler SSI directives like <!--#fsize-->, <!--#flastmod-->, etc. you'll be fine.

* Currently, the way <!--#echo var=whatever--> looks for variables is to first try $r->subprocess_env, then try %ENV, then the five extra environment variables mod_include supplies. Is this the correct order?

TO DO ^

Revisit http://www.apache.org/docs/mod/mod_include.html and see what else there I can implement.

It would be nice to have a "PerlSetVar ASSI_Subrequests 0|1" option that would let you choose between executing a full-blown subrequest when including a file, or just opening it and printing it.

I'd like to know how to use Apache::test for the real.t test.

SEE ALSO ^

mod_include, mod_perl(3), Apache(3), HTML::Embperl(3), Apache::ePerl(3), Apache::OutputChain(3)

AUTHOR ^

Ken Williams ken@mathforum.org

Concept based on original version by Doug MacEachern dougm@osf.org . Implementation different.

COPYRIGHT ^

Copyright 1998 Swarthmore College. All rights reserved.

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

syntax highlighting: