Fix bug when second argument is absent, improve documentation

Before, the InjectFoot variable wasn't cleared.

1 files changed, 42 insertions, 21 deletions

diff --git a/lib/Apache/Inject.pm b/lib/Apache/Inject.pm
index eb4fa36..83870bd 100644
--- a/lib/Apache/Inject.pm
+++ b/lib/Apache/Inject.pm
@@ -2,13 +2,13 @@ package Apache::Inject;
 
 use 5.008000;
 use strict;
-use warnings;
 
 our $VERSION = '0.01';
 
 use Apache2::CmdParms ();
-use Apache2::Module ();
 use Apache2::Const qw/OR_LIMIT OR_AUTHCFG TAKE12/;
+use Apache2::Log ();
+use Apache2::Module ();
 
 my @directives = (
 	{ name => 'Inject',
@@ -22,18 +22,23 @@ Apache2::Module::add(__PACKAGE__, \@directives);
 sub Inject {
 	my ($self, $parms, @args) = @_;
 
-	# Construct directives for passing arguments to handler
-	my @vars;
-	my @names = qw/InjectHead InjectFoot/;
 	for (@args) {
-		s/\\/\\\\/; s/"/\\"/;
-		push @vars, 'PerlSetVar ' . (shift @names) . ' "' . $_ . '"';
+		if ($_ eq ' ') {
+			$parms->server->log_error('Inject: Argument cannot be a single space');
+		}
 	}
 
+	# Construct directives for passing arguments to handler
+	my $head = $args[0];
+	my $foot = $args[1] || ' '; # single space signifies absence of argument
+	$head =~ s/\\/\\\\/; s/"/\\"/;
+	$foot =~ s/\\/\\\\/; s/"/\\"/;
+
 	# Add relevant directives to current configuration
 	$parms->add_config(['SetHandler perl-script',
 	                    'PerlResponseHandler Apache::Inject::Handler',
-	                    @vars]);
+	                    qq{PerlSetVar InjectHead "$head"},
+	                    qq{PerlSetVar InjectFoot "$foot"}]);
 }
 
 1;
@@ -61,9 +66,9 @@ 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 before the body of
-the requested HTML file, while the second file (the footer) is
-inserted after the body.
+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
@@ -73,6 +78,20 @@ E<lt>headE<gt> or E<lt>bodyE<gt> tag is present in the source of
 the requested HTML page).  Likewise, the contents of the second
 file is placed before any potential final E<lt>/htmlE<gt>.
 
+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 E<lt>bodyE<gt> element, such as headings,
+menu bars and copyright notices.  While you can technically include
+E<lt>headE<gt> elements in your header file, they will be placed
+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:
 
 =over
@@ -84,14 +103,10 @@ blocks.  It is valid in .htaccess files if AllowOverride
 Limit/AuthConfig/All is enabled.
 
 =item *
-The file paths given to Inject are relative to the document root
-of the current server or virtual server.
-
-=item *
-Apache::Inject is designed for injecting headers and footers that
-belong in the E<lt>bodyE<gt> element, such as headings, menu bars
-and copyright notices.  It is not built for inserting E<lt>headE<gt>
-elements.
+The file paths given to Inject are relative to the B<document root>
+of the current server or virtual server -- B<not> the directory to
+which the current directory section or .htaccess file applies.  They
+should be specified without a leading slash.
 
 =back
 
@@ -128,8 +143,9 @@ contents.
 
 =head1 DIAGNOSTICS
 
-Apache::Inject::Handler logs all errors and warnings to the Apache
-log file.  Below is a list of all issued errors and warnings.
+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
@@ -137,6 +153,11 @@ Apache handle it as it would if the Inject directive were not used.
 
 =over
 
+=item 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.
+
 =item Error: InjectHead/InjectFoot should not begin with slash, as
 it is already always relative to document root