aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorroot <root@rbsd.ankarstrom.se>2021-04-24 14:49:48 +0000
committerroot <root@rbsd.ankarstrom.se>2021-04-24 14:49:48 +0000
commit713e751bb92b6cf957de17ed6cd7ff3c0a3c9f2c (patch)
treeda4c03a99cf4e466487450786dee8e7d79b77bbf /README
parent0cbcdb0d4083eb97a6e052471cb51f8b31f3c92c (diff)
downloadApache-Inject-713e751bb92b6cf957de17ed6cd7ff3c0a3c9f2c.tar.gz
Update documentation and README
Diffstat (limited to 'README')
-rw-r--r--README120
1 files changed, 95 insertions, 25 deletions
diff --git a/README b/README
index c93070e..636bd09 100644
--- a/README
+++ b/README
@@ -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.