README.md
1# HTTP Footer filter module for Nginx
2
3## Introduction
4
5This is a module that is distributed with
6[tengine](http://tengine.taobao.org) which is a distribution of
7[Nginx](http://nginx.org) that is used by the e-commerce/auction site
8[Taobao.com](http://en.wikipedia.org/wiki/Taobao). This distribution
9contains some modules that are new on the Nginx scene. The
10`ngx_http_footer_filter` module is one of them.
11
12This module implements a body filter that adds a given string to the
13page footer.
14
15You might say that it provides a particular case of the
16[http sub module](http://wiki.nginx.org/HttpSubModule) in the sense
17that it adds something to the footer. You can do the same using the
18`http sub module` but using the footer filter should be faster since
19there's no string matching done on the request body.
20
21## Configuration example
22
23 location / {
24 ## Using the $date_gmt variable from the SSI module (prints a
25 ## UNIX timestamp).
26 footer "<!-- $date_gmt -->";
27 index index.html;
28 }
29
30 location ^~ /assets/css {
31 ## Add CSS to the MIME types to be added a footer.
32 footer_types text/css;
33
34 footer "/* host: $server_name - $date_local */";
35 }
36
37## Module directives
38
39**footer** `string`
40
41**default:** ``
42
43**context:** `http, server, location`
44
45It defines the string to be printed at the footer of the request
46body. This string can have variables embedded.
47
48<br/>
49<br/>
50
51**footer_types** `MIME types`
52
53**default:** `footer_types: text/html`
54
55**context:** `http, server, location`
56
57Defines the [MIME types](http://en.wikipedia.org/wiki/MIME_type) of
58the files where the footer will be included.
59
60## Installation
61
62 1. Clone the git repo.
63
64 git clone git://github.com/perusio/nginx-http-footer-filter.git
65
66 2. Add the module to the build configuration by adding
67 `--add-module=/path/to/nginx-http-footer-filter`.
68
69 3. Build the nginx binary.
70
71 4. Install the nginx binary.
72
73 5. Configure contexts where footer filter is enabled.
74
75 6. Done.
76
77## Tagging releases
78
79I'm tagging each release in synch with the
80[Tengine](http://tengine.taobao.org) releases.
81
82## Other tengine modules on Github
83
84 + [http concat](https://github.com/perusio/nginx-http-concat):
85 allows to concatenate a given set of files and ship a single
86 response from the server. It's particularly useful for **aggregating**
87 CSS and Javascript files.
88
89## Original documentation
90
91The
92[original documentation](http://tengine.taobao.org/document_cn/http_footer_filter_cn.html)
93in Chinese. Note that the examples given therein rely on
94**non-standard** Nginx
95[variables](http://tengine.taobao.org/document_cn/variables_cn.html)
96that are not
97[available](http://nginx.org/en/docs/http/ngx_http_core_module.html#variables)
98on the official Nginx source but only on [tengine](http://tengine.taobao.org).
99
100## License
101
102Copyright (C) 2010-2012 Alibaba Group Holding Limited
103
104Redistribution and use in source and binary forms, with or without
105modification, are permitted provided that the following conditions
106are met:
107
108 1. Redistributions of source code must retain the above copyright
109 notice, this list of conditions and the following disclaimer.
110
111 2. Redistributions in binary form must reproduce the above copyright
112 notice, this list of conditions and the following disclaimer in the
113 documentation and/or other materials provided with the distribution.
114
115THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS "AS IS" AND ANY
116EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
117IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
118PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE
119LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
120CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
121SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
122BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
123WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
124OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
125IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
126