NAME
    Apache::Sandwich - Layered document (sandwich) maker

SYNOPSIS
     SetHandler  perl-script
     PerlHandler Apache::Sandwich
     PerlSetVar SandwichHandler default-handler

DESCRIPTION
    The Apache::Sandwich module allows you to add a per-directory custom
    "header" and/or "footer" content to a given uri. Only works 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 inbetween constitute a complete valid
    HTML document.

    Here's a configuration example:

     #in httpd.conf or .htaccess

     <Location /foo>
      #any request for /foo and it's document tree
      #are run through our Apache::Sandwich::handler
      SetHandler  perl-script
      PerlHandler Apache::Sandwich

      #we send this file first
      PerlSetVar HEADER "/my_header.html"

      #requested uri (e.g. /foo/index.html) is sent in the middle

      #we send output of this mod_perl script last  
      PerlSetVar FOOTER "/perl/footer.pl"
     </Location>

    With the above example, one must be careful not to put graphics within
    the same directory, otherwise they will be Sandwiched also.

    Here's another example which only Sandwiches the files we want (using
    Apache 1.3 syntax). In this example, all *.brc files are sandwiched
    using the defined HEADER and FOOTER parts, with the file itself assumed
    to be a plain text file (or static HTML file). All *.sbrc files are
    similarly sandwiched, except that the file itself is assumed to be an
    "shtml" file, i.e., it is given to the SSI handler for server side
    includes to be processed.

     # filter *.brc files through Sandwich maker, but define
     # HEADER/FOOTER per section below
 
     <FilesMatch "\.brc$">
      SetHandler  perl-script
      PerlHandler Apache::Sandwich
     </FilesMatch>
 
     <FilesMatch "\.sbrc$">
      SetHandler  perl-script
      PerlHandler Apache::Sandwich
      PerlSetVar SandwichHandler server-parsed
     </FilesMatch>
 
     # now specify the header and footer for each major section
     #
     <Location /misc>
       PerlSetVar HEADER "/misc/HEADER.shtml ADS.shtml"
       PerlSetVar FOOTER "/misc/FOOTER.html"
     </Location>
 
     <Location /getting_started>
       PerlSetVar HEADER "/getting_started/HEADER.shtml ADS.shtml"
       PerlSetVar FOOTER "/misc/FOOTER.html"
     </Location>

    Note that in this example, the file ADS.shtml is included from the same
    directory as the requested file.

    The files referenced in the HEADER and FOOTER variables are fetched
    using the "GET" method and may be of any type file the server can
    process.

  Sandwiching mod_perl Programs
    The helper function insert_parts() can be used to make your CGI programs
    look like the rest of your pages. A simple script would be:

     #! /usr/local/bin/perl
     use strict;

     use CGI;
     use Apache::Sandwich;

     use vars qw($query);

     $query = new CGI or die "Something failed";

     print $query->header();
     Apache::Sandwich::insert_parts('HEADER');

     print $query->p("Hello, world!");

     Apache::Sandwich::insert_parts('FOOTER');

KNOWN BUGS
    Headers printed by mod_perl scripts used as a HEADER, FOOTER or
    in-the-middle uri need to use CGI.pm version 2.37 or higher or headers
    will show up in the final document (browser window). Suggested
    work-around (if you don't want to upgrade CGI.pm):

     if($ENV{MOD_PERL} and Apache->request->is_main) {
        #send script headers
        print "Content-type: text/html\n\n";
     } else {
        #we're part of a sub-request, don't send headers
     }

    Setting $Apache::Sandwich::Debug to 1 will log debugging information
    into the Apache ErrorLog.

AUTHOR
    Doug MacEachern. Modifications and cleanup by Vivek Khera.

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