diff options
| -rw-r--r-- | README | 120 | ||||
| -rw-r--r-- | lib/Apache/Inject.pm | 121 |
2 files changed, 179 insertions, 62 deletions
@@ -1,40 +1,110 @@ -Apache-Inject version 0.01 -========================== +NAME + Apache::Inject - Apache directive for injecting HTML headers and footers -The README is used to introduce the module and provide instructions on -how to install the module, any machine dependencies it may have (for -example C compilers and installed libraries) and any other information -that should be provided before the module is installed. +SYNOPSIS + DocumentRoot /uar/local/www/apache24/data + PerlModule Apache::Inject + <Directory /usr/local/www/apache24/data> + Inject head.html foot.html + </Directory> -A README file is required for CPAN modules since CPAN extracts the -README file from a module distribution so that people browsing the -archive can use it get an idea of the modules uses. It is usually a -good idea to provide version information here so that people can -decide whether fixes for the module are worth downloading. +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 before the body of the requested HTML file, + while the second file (the footer) is inserted after 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>. + + 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. + + * Apache::Inject is designed for injecting headers and footers that + belong in the <body<gt> element, such as headings, menu bars and + copyright notices. It is not built for inserting <head> elements. INSTALLATION + To install this module type the following: + + perl Makefile.PL + make + make test + make install + +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::Handler logs all errors and warnings to the Apache log + file. Below is a list of all issued errors and warnings. -To install this module type the following: + 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. - perl Makefile.PL - make - make test - make install + 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. -DEPENDENCIES + 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. -This module requires these other modules and libraries: + 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 "../". - blah blah blah + Error: InjectHead/InjectFoot *path/to/file* does not exist + This error is issued if any of the paths given to Inject doesn't + exist. -COPYRIGHT AND LICENCE + 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. -Put the correct copyright and licence information here. +CAVEATS + On FreeBSD, you 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. -Copyright (C) 2021 by Charlie & +AUTHOR + John Ankarström, <john [at] ankarstrom.se> -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. +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. diff --git a/lib/Apache/Inject.pm b/lib/Apache/Inject.pm index e82e174..15281fb 100644 --- a/lib/Apache/Inject.pm +++ b/lib/Apache/Inject.pm @@ -38,65 +38,111 @@ sub Inject { 1; __END__ +=encoding latin1 + =head1 NAME Apache::Inject - Apache directive for injecting HTML headers and footers =head1 SYNOPSIS -DocumentRoot /uar/local/www/apache24/data -PerlModule Apache::Inject -<Directory /usr/local/www/apache24/data> - Inject head.html foot.html -</Directory> + DocumentRoot /uar/local/www/apache24/data + PerlModule Apache::Inject + <Directory /usr/local/www/apache24/data> + Inject head.html foot.html + </Directory> =head1 DESCRIPTION -Apache::Inject is a mod_perl module that adds the Inject directive. -It injects a header before the body and (optionally) a footer after the body -of any requested HTML file. +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 before the body of +the requested HTML file, while the second file (the footer) is +inserted after the body. -The directive is smart enough to place the inserted contents -in the proper places. -The contents of the first file is inserted after any elements -belonging to E<lt>headE<gt> and before any elements belonging to E<lt>bodyE<gt>, -regardless of whether any explicit 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 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 E<lt>headE<gt> and before any elements +belonging to E<lt>bodyE<gt> (regardless of whether any explicit +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>. -Note: +Please note: =over + =item * -The Inject directive is valid only inside directory sections, -such as E<lt>DirectoryE<gt>, E<lt>LocationE<gt> and E<lt>FilesMatchE<gt> blocks. -It is valid in .htaccess files if AllowOverride Limit/AuthConfig/All is enabled. +The Inject directive is valid only inside directory sections, such +as E<lt>DirectoryE<gt>, E<lt>LocationE<gt> and E<lt>FilesMatchE<gt> +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>body<gt> element, such as headings, menu bars +and copyright notices. It is not built for inserting E<lt>headE<gt> +elements. + =back +=head1 INSTALLATION + +To install this module type the following: + + perl Makefile.PL + make + make test + make install + +=head1 OPERATION + +Behind the scenes, the Inject directive works as an alias for +PerlResponseHandler and PerlSetVar. For example, C<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 C<text/html>. It reads the contents of the requested +file, as well as the contents of the C<InjectHeader> and C<InjectFooter> +files, concatenates them intelligently and prints their combined +contents. + =head1 DIAGNOSTICS -Apache::Inject::Handler, which is the actual handler of the requests, -logs errors to the Apache log file. -Below is a list of all issued errors and warnings. -All of them result in Apache::Inject::Handler declining the request, -letting Apache handle it as it would if the Inject directive were not used. +Apache::Inject::Handler logs 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. =over -=item Error: InjectHead/InjectFoot should not begin with slash, as it is already always relative to document root +=item 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. +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. =item Error: InjectHead/InjectFoot cannot extend past document root @@ -105,7 +151,8 @@ go above the document root by using C<../>. =item Error: InjectHead/InjectFoot I<path/to/file> does not exist -This error is issued if any of the paths given to Inject doesn't exist. +This error is issued if any of the paths given to Inject doesn't +exist. =item Warning: Declining request due to empty document root @@ -116,21 +163,21 @@ cannot retrieve the current document root from Apache. =head1 CAVEATS -On FreeBSD, you 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. +On FreeBSD, you 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. =head1 AUTHOR -John Ankarström, E<lt>john [at] ankarstrom.se<gt> +John Ankarström, E<lt>john [at] ankarstrom.seE<gt> =head1 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. +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. =cut |