aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 5e553141c544bf33c1aea125a25307161e921bd2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
NAME
    Apache::Inject - Apache directive for injecting HTML headers and footers

SYNOPSIS
      LoadModule perl_module libexec/apache24/mod_perl.so
      PerlLoadModule Apache::Inject
      DocumentRoot /uar/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.

INSTALLATION
    To install this module type the following:

      perl Makefile.PL
      make
      make test
      make install

    Note that the Apache::* and Apache2::* dependencies are included with
    mod_perl2.

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 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 Apache handle it
    as it would if the Inject directive were not used.

    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.

    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.

    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 "../".

    Error: InjectHead/InjectFoot *path/to/file* does not exist
        This error is issued if any of the paths given to Inject doesn't
        exist.

    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.

CAVEATS
    On FreeBSD, you may 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.

AUTHOR
    John Ankarström, <john [at] ankarstrom.se>

SEE ALSO
    mod_perl2: <https://perl.apache.org/>

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.