B.15 Output Filters and Layering Modules

B.15.1 Apache::OutputChain—Chain Stacked Perl Handlers

Apache::OutputChain was written to explore the possibilities of stacked handlers in mod_perl. It ties STDOUT to an object that catches the output and makes it easy to build a chain of modules that work on the output data stream.

Examples of modules that are built using this idea are Apache::SSIChain, Apache::GzipChain, and Apache::EmbperlChain—the first processes the SSIs in the stream, the second compresses the output on the fly, and the last provides Embperl processing.

The syntax is like this:

<Files *.html>
    SetHandler perl-script
    PerlHandler Apache::OutputChain Apache::SSIChain Apache::PassHtml
</Files>

The modules are listed in reverse order of their execution—here the Apache::PassHtml module simply collects a file's content and sends it to STDOUT, and then it's processed by Apache::SSIChain, which sends its output to STDOUT again. Then it's processed by Apache::OutputChain, which finally sends the result to the browser.

An alternative to this approach is Apache::Filter, which has a more natural forward configuration order and is easier to interface with other modules.

Apache::OutputChain works with Apache::Registry as well. For example:

Alias /foo /home/httpd/perl/foo
<Location /foo>
    SetHandler "perl-script"
    Options +ExecCGI
    PerlHandler Apache::OutputChain Apache::GzipChain Apache::Registry
</Location>

It's really a regular Apache::Registry setup, except for the added modules in the PerlHandler line.

Available from CPAN. See the module manpage for more information.

B.15.2 Apache::Clean—mod_perl Interface Into HTML::Clean

Apache::Clean uses HTML::Clean to tidy up large, messy HTML, saving bandwidth. It is particularly useful with Apache::Compress for maximum size reduction.

Available from CPAN. See the module manpage for more information.

B.15.3 Apache::Filter—Alter the Output of Previous Handlers

In the following configuration:

<Files ~ "*\.fltr">
    SetHandler perl-script
    PerlSetVar Filter On
    PerlHandler Filter1 Filter2 Filter3
</Files>

each of the handlers Filter1, Filter2, and Filter3 will make a call to $r->filter_input( ), which will return a file handle. For Filter1, the file handle points to the requested file. For Filter2, the file handle contains whatever Filter1 wrote to STDOUT. For Filter3, it contains whatever Filter2 wrote to STDOUT. The output of Filter3 goes directly to the browser.

Available from CPAN. See the module manpage for more information.

B.15.4 Apache::GzipChain—Compress HTML (or Anything) in the OutputChain

Covered in Chapter 13.

Available from CPAN. See the module manpage for more information.

B.15.5 Apache::PassFile—Send File via OutputChain

See Apache::GzipChain. It's a part of the same package as Apache::GzipChain.

B.15.6 Apache::Gzip—Auto-Compress Web Files with gzip

Similar to Apache::GzipChain but works with Apache::Filter.

This configuration:

PerlModule Apache::Filter
<Files ~ "*\.html">
    SetHandler perl-script
    PerlSetVar Filter On
    PerlHandler Apache::Gzip
</Files>

will send all the *.html files compressed if the client accepts the compressed input.

And this one:

PerlModule Apache::Filter
Alias /home/http/perl /perl
<Location /perl>
    SetHandler perl-script
    PerlSetVar Filter On
    PerlHandler Apache::RegistryFilter Apache::Gzip
</Location>

will compess the output of the Apache::Registry scripts. Note that you should use Apache::RegistryFilter instead of Apache::Registry for this to work.

You can use as many filters as you want:

PerlModule Apache::Filter
<Files ~ "*\.fltr">
    SetHandler perl-script
    PerlSetVar Filter On
    PerlHandler Filter1 Filter2 Apache::Gzip
</Files>

You can test that it works by either looking at the size of the response in the access.log file or by telnet:

panic% telnet localhost 8000
Trying 127.0.0.1
Connected to 127.0.0.1
Escape character is '^]'.
GET /perl/test.pl HTTP 1.1
Accept-Encoding: gzip
User-Agent: Mozilla

You will get the data compressed if it's configured correctly.

B.15.7 Apache::Compress—Auto-Compress Web Files with gzip

This module lets you send the content of an HTTP response as gzip-compressed data. Certain browsers (e.g., Netscape and IE) can request content compression via the Content-Encoding header. This can speed things up if you're sending large files to your users through slow connections.

Browsers that don't request gzipped data will receive uncompressed data.

This module is compatibile with Apache::Filter, so you can compress the output of other content generators.

Available from CPAN. See the module manpage for more information.

B.15.8 Apache::Layer—Layer Content Tree Over One or More Others

This module is designed to allow multiple content trees to be layered on top of each other within the Apache server.

Available from CPAN. See the module manpage for more information.

B.15.9 Apache::Sandwich—Layered Document (Sandwich) Maker

The Apache::Sandwich module allows you to add per-directory custom "header" and "footer" content to a given URI. Works only with GET requests. Output of combined parts is forced to text/html. The handler for the sandwiched document is specified by the SandwichHandler configuration variable. If it is not set, default-handler is used.

The basic concept is that the concatenation of the header and footer parts with the sandwiched file in between constitutes a complete valid HTML document.

Available from CPAN. See the module manpage for more information.

B.15.10 Apache::SimpleReplace—Simple Template Framework

Apache::SimpleReplace provides a simple way to insert content within an established template for uniform content delivery. While the end result is similar to Apache::Sandwich, Apache::SimpleReplace offers two main advantages:

• It does not use separate header and footer files, easing the pain of maintaining syntactically correct HTML in separate files.

• It is Apache::Filter aware, so it can both accept content from other content handlers and pass its changes on to others later in the chain.

Available from CPAN. See the module manpage for more information.

B.15.11 Apache::SSI—Implement Server-Side Includes in Perl

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

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

Available from CPAN. See the module manpage for more information.