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

SYNOPSIS
     SetHandler  perl-script
     PerlHandler Apache::Sandwich

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 for static content HTML or text files. Output of combined parts
    is forced to *text/html*.

    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):

     # filter *.brc files through Sandwich maker, but define
     # HEADER/FOOTER per section below
     
     <FilesMatch "\.brc$">
      SetHandler  perl-script
      PerlHandler Apache::Sandwich
     </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 produce dynamically generated text.

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.

    The sandwiched file must be a plain static HTML or text file. If someone
    knows how to call an alternate handler for the file, please contribute
    the patches!

AUTHOR
    Doug MacEachern. Modifications and cleanup by Vivek Khera.