NAME
Apache::Inject - Apache directive for injecting HTML headers and footers
SYNOPSIS
LoadModule perl_module libexec/apache24/mod_perl.so
PerlLoadModule Apache::Inject
DocumentRoot /usr/local/www/apache24/data
<Directory /usr/local/www/apache24/data>
# Inject both header and footer on all pages on the server
Inject head.html foot.html
</Directory>
<Location /blog>
# Inject only header on pages under /blog
Inject head.html
</Location>
<Files index.html>
# Inject only footer on pages named index.html
Inject - foot.html
</Files>
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 <head> and before any elements belonging to <body>
(regardless of whether any explicit <head> or <body> tag is present in
the source of the requested HTML page). Likewise, the contents of the
second file is placed before any potential final </html>.
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 <body> element, such as headings, menu bars and
copyright notices. While you can technically include <head> 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 <Directory>, <Location> and <FilesMatch> 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.
SYNTAX
The Inject directive takes one or two arguments:
Inject HEADER_FILE [FOOTER_FILE]
Each argument can consist of one of two things:
1. the path to a file relative to the document root, or
2. a single hyphen ("-"), signifying the absence of an argument.
Passing a hyphen as the first argument disables the header, and passing
a hyphen as the second argument disables the footer.
If you leave out the second argument, then it is implicitly equivalent
to a hyphen.
OPERATION
Behind the scenes, the Inject directive works as an alias for
PerlOutputFilterHandler and PerlSetVar. For example, "Inject head.html
foot.html" results in the following configuration being added:
PerlOutputFilterHandler Apache::Inject::Filter
PerlSetVar InjectHeader head.html
PerlSetVar InjectFooter foot.html
This results in Apache::Inject::Filter being registered as an output
filter for requests to the current directory or location.
Apache::Inject::Filter accepts all requests where the content type is
"text/html". It receives the contents of the original page from Apache
and, in addition, reads the contents of the "InjectHeader" and
"InjectFooter" files. It then concatenates all of these intelligently
and forwards their combined contents.
CAVEATS
* Apache::Inject::Filter uses a regular expression to determine the
proper location of the injected header. It supports all valid HTML.
However, it does not parse embedded CSS and JavaScript, which means
that it is *possible* to construct an example where it will fail:
<script>
/* this looks like the closing tag for script: </script> */
/* this looks like an opening tag for a new element: <title> */
</script>
<body>
This is where the header <i>should</i> be inserted.
<script>
/* this looks like the closing tag for the title: </title>
This is where the header is <i>actually</i> inserted.
*/
</script>
</body>
This specific type of document, however, is *incredibly* unlikely.
In this case, an ad-hoc solution is simpler, more efficient and more
maintainable than a general one.
* Because of how Apache filters work, Inject may fail to find the end
of the <head> if the <head> is very long (in my experience over 7000
characters). If this happens, it will decline the request, and the
contents will be served as though Inject had not been enabled.
* 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.
DIAGNOSTICS
Apache::Inject and Apache::Inject::Filter 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::Filter 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: 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::Filter for some reason
cannot retrieve the current document root from Apache.
AUTHOR
John Ankarström, <john [at] ankarstrom.se>
SEE ALSO
mod_perl2: <https://perl.apache.org/>
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.