PrePAN

Sign in to PrePAN

Apache::Inject Apache directive for injecting HTML headers and footers

Good

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 head.html foot.html
</Directory>

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.

Comments

"Inject" sounds a bit dramatic, I would have called it something like Apache::Header or something similar. I probably would not use this module but alter the static HTML pages instead, it seems like a complicated way of doing things. I suppose it could be useful if one really cannot alter the static HTML pages at all, though.
I've done similar things to this in the past using Aapche's mod_substitute, but that can get fiddly if you're wanting to include more than a little bit of HTML.

In my experience the main use for this sort of operation is when you want to make it obvious that the site being served out by Apache is actually a Development or Testing version of a site and not a live one (i.e. stick a big banner at the top saying "Test Site" so users don't get it confused with a the production instance of the site).

It would be really good if the files to be included could be absolute as well as relative to the document root.

Splitting the Inject directive into two directives (InjectHeader and InjectFooter) would allow people the option to inject a footer without a header.

An alternative way to tackle this would be to have InjectAtStartOf and InjectAtEndOf directives where you can specify a block tag and a file to insert at the start of end of the block. This would make the module more generic without loosing current functionality.
Thanks for all the feedback.

> It would be really good if the files to be included could be absolute as well as relative to the document root.

I considered allowing this, but considering that I want to allow the directive in .htaccess files, it seems unsafe.

> Splitting the Inject directive into two directives (InjectHeader and InjectFooter) would allow people the option to inject a footer without a header.

Yes, some way to specify a footer without a header is needed. I'll think about how to implement it.
> > It would be really good if the files to be included could be absolute as well as relative to the document root.
>
> I considered allowing this, but considering that I want to allow the directive in .htaccess files, it seems unsafe.

Yes, there's definitely security issues that need to be considered around any file include logic and while it's easy to block a mod_perl command from being used in a .htaccess context it isn't easy for that command to know when it's configuration has come from a .htaccess file.

One option might be to have another command, that isn't available to .htaccess files, which lets you define a list valid paths that files to be injected can live under. If you default the list to the document root then you'll have the same functionality, but someone with access to Apache's configs could add in other paths to the list.

Or you could just have a simple toggle command that isn't allowed in .htaccess files, but which lets you enable/disable support for absolute paths.

Please sign up to post a review.