diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 120 |
1 files changed, 95 insertions, 25 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. |