NAME Apache::Inject - Apache directive for injecting HTML headers and footers SYNOPSIS LoadModule perl_module libexec/apache24/mod_perl.so PerlLoadModule Apache::Inject DocumentRoot /uar/local/www/apache24/data Inject head.html foot.html DESCRIPTION Apache::Inject is a mod_perl module that adds an Apache directive called Inject. The Inject directive takes one or two arguments, which correspond to the file names of two HTML files in the document root. The contents of these files are then inserted into any requested HTML file. The first file (the header) is inserted at the top of the body of the requested HTML file, while the second, optional file (the footer) is inserted at the bottom of the body. The directive is smart enough to place the header and footer in the proper places. The contents of the header file is inserted after any elements belonging to and before any elements belonging to (regardless of whether any explicit or tag is present in the source of the requested HTML page). Likewise, the contents of the second file is placed before any potential final . The Inject directive serves a much more specific purpose than server-side includes. It is designed for injecting headers and footers that belong in the element, such as headings, menu bars and copyright notices. While you can technically include elements in your header file, Apache::Inject will place them in the body of the HTML page and not in the head. The main benefit over server-side includes is that the header and footer is specified in the server configuration instead of the HTML files themselves. Thus, it is useful for adding headers and footers to a large number of pre-existing static HTML pages. Furthermore, this means that the headers and footers on all pages can be changed at once by a single change in the server configuration. Please note: * The Inject directive is valid only inside directory sections, such as , and blocks. It is valid in .htaccess files if AllowOverride Limit/AuthConfig/All is enabled. * The file paths given to Inject are relative to the document root of the current server or virtual server -- not the directory to which the current directory section or .htaccess file applies. They should be specified without a leading slash. INSTALLATION To install this module type the following: perl Makefile.PL make make test make install Note that all steps in this process require mod_perl2 to be installed. I recommend installing mod_perl2 via your operating system's package manager or ports collection before installing Apache::Inject. Note further that, because they depend on Apache, the tests require an unprivileged user and will be skipped if they are run as root. This is relevant if you install Apache::Inject via App::Cpan, which normally runs as root. OPERATION Behind the scenes, the Inject directive works as an alias for PerlResponseHandler and PerlSetVar. For example, "Inject head.html foot.html" results in the following configuration being added: PerlResponseHandler Apache::Inject::Handler PerlSetVar InjectHeader head.html PerlSetVar InjectFooter foot.html This results in Apache::Inject::Handler being registered as a handler for requests to the current directory or location. Apache::Inject::Handler accepts all requests to files where the content type is "text/html". It reads the contents of the requested file, as well as the contents of the "InjectHeader" and "InjectFooter" files, concatenates them intelligently and prints their combined contents. DIAGNOSTICS Apache::Inject and Apache::Inject::Handler log all errors and warnings to the Apache log file. Below is a list of all issued errors and warnings. Note that whenever Apache::Inject::Handler issues an error or a warning, this means that it also declines the request, letting Apache handle it as it would if the Inject directive were not used. Error: Argument cannot be a single space The file names given to Inject are not allowed to by a single space, as this is a special value signifying absence of an argument. Error: InjectHead/InjectFoot should not begin with slash, as it is already always relative to document root The paths given to Inject are always relative to the document root, even if the Inject directive is located within a directory section that applies to another path. Beginning any of the paths with a slash implies that there would be some difference in behavior compared to omitting the slash, which is false. Error: InjectHead/InjectFoot cannot extend past document root This error is issued if any of the paths given to Inject tries to go above the document root by using "../". Error: InjectHead/InjectFoot *path/to/file* does not exist This error is issued if any of the paths given to Inject doesn't exist. Warning: Declining request due to empty document root This warning is issued if Apache::Inject::Handler for some reason cannot retrieve the current document root from Apache. CAVEATS On FreeBSD, you may need to enable the accf_http kernel module in order for the tests to work. Note that Apache::Inject works fine without the module; it is only the tests that require it. AUTHOR John Ankarström, SEE ALSO mod_perl2: COPYRIGHT AND LICENSE Copyright (C) 2021 by John Ankarström This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.32.1 or, at your option, any later version of Perl 5 you may have available.