Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_ssi_module.xml @ 399:a56540cdcea5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
English translation of ngx_http_ssi_module.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 07 Feb 2012 11:01:25 +0000
parents
children 694db9597ee0
comparison
equal deleted inserted replaced
398:8548b80a4552 399:a56540cdcea5
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_ssi_module"
6 link="/en/docs/http/ngx_http_ssi_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <literal>ngx_http_ssi_module</literal> module is a filter
13 that processes SSI (Server Side Includes) commands in responses
14 passing through it.
15 Currently, the list of supported SSI commands is incomplete.
16 </para>
17
18 </section>
19
20
21 <section id="example" name="Example Configuration">
22
23 <para>
24 <example>
25 location / {
26 ssi on;
27 ...
28 }
29 </example>
30 </para>
31
32 </section>
33
34
35 <section id="directives" name="Directives">
36
37 <directive name="ssi">
38 <syntax><literal>on</literal> | <literal>off</literal></syntax>
39 <default>off</default>
40 <context>http</context>
41 <context>server</context>
42 <context>location</context>
43 <context>if in location</context>
44
45 <para>
46 Enables or disables processing of SSI commands in responses.
47 </para>
48
49 </directive>
50
51
52 <directive name="ssi_silent_errors">
53 <syntax><literal>on</literal> | <literal>off</literal></syntax>
54 <default>off</default>
55 <context>http</context>
56 <context>server</context>
57 <context>location</context>
58
59 <para>
60 Allows to suppress output of the string
61 “<literal>[an error occurred while processing the directive]</literal>”
62 if an error occurred during SSI processing.
63 </para>
64
65 </directive>
66
67
68 <directive name="ssi_types">
69 <syntax><value>mime-type</value> ...</syntax>
70 <default>text/html</default>
71 <context>http</context>
72 <context>server</context>
73 <context>location</context>
74
75 <para>
76 Enables processing of SSI commands in responses with the specified MIME types
77 in addition to “<literal>text/html</literal>”.
78 </para>
79
80 </directive>
81
82 </section>
83
84
85 <section id="commands" name="SSI Commands">
86
87 <para>
88 SSI commands have the following generic format:
89 <example>
90 &lt;!--# command parameter1=value1 parameter2=value2 ... --&gt;
91 </example>
92 </para>
93
94 <para>
95 The following commands are supported:
96 <list type="tag">
97
98 <tag-name><literal>block</literal></tag-name>
99 <tag-desc>
100 Defines a block that can be used as a stub
101 in the <literal>include</literal> command.
102 The block can contain other SSI commands.
103 The command has the following parameter:
104
105 <list type="tag">
106 <tag-name><literal>name</literal></tag-name>
107 <tag-desc>
108 block name.
109 </tag-desc>
110 </list>
111
112 Example:
113 <example>
114 &lt;!--# block name="one" --&gt;
115 stub
116 &lt;!--# endblock --&gt;
117 </example>
118
119 </tag-desc>
120
121
122 <tag-name><literal>config</literal></tag-name>
123 <tag-desc>
124 Sets some parameters used during SSI processing, namely:
125
126 <list type="tag">
127 <tag-name><literal>errmsg</literal></tag-name>
128 <tag-desc>
129 a string that is output if an error occurs during SSI processing.
130 By default, the following string is output:
131 <example>
132 [an error occurred while processing the directive]
133 </example>
134 </tag-desc>
135
136 <tag-name><literal>timefmt</literal></tag-name>
137 <tag-desc>
138 a format string passed to the <c-func>strftime</c-func> function
139 used to output date and time.
140 By default, the following format is used:
141 <example>
142 "%A, %d-%b-%Y %H:%M:%S %Z"
143 </example>
144 The “<literal>%s</literal>” format is suitable to output time in seconds.
145 </tag-desc>
146 </list>
147
148 </tag-desc>
149
150
151 <tag-name><literal>echo</literal></tag-name>
152 <tag-desc>
153 Outputs the value of a variable.
154 The command has the following parameters:
155
156 <list type="tag">
157 <tag-name><literal>var</literal></tag-name>
158 <tag-desc>
159 variable name.
160 </tag-desc>
161
162 <tag-name><literal>encoding</literal></tag-name>
163 <tag-desc>
164 encoding method.
165 Possible values include <literal>none</literal>, <literal>url</literal>, and
166 <literal>entity</literal>.
167 By default, <literal>entity</literal> is used.
168 </tag-desc>
169
170 <tag-name><literal>default</literal></tag-name>
171 <tag-desc>
172 non-standard parameter that sets a string to be output
173 if a variable is undefined.
174 By default, “<literal>none</literal>” is output.
175 The command
176 <example>
177 &lt;!--# echo var="name" default="<emphasis>no</emphasis>" --&gt;
178 </example>
179 replaces the following sequence of commands:
180 <example>
181 &lt;!--# if expr="$name" --&gt;&lt;!--# echo var="name" --&gt;&lt;!--#
182 else --&gt;<emphasis>no</emphasis>&lt;!--# endif --&gt;
183 </example>
184 </tag-desc>
185 </list>
186
187 </tag-desc>
188
189
190 <tag-name><literal>if</literal></tag-name>
191 <tag-desc>
192 Performs a conditional inclusion.
193 The following commands are supported:
194 <example>
195 &lt;!--# if expr="..." --&gt;
196 ...
197 &lt;!--# elif expr="..." --&gt;
198 ...
199 &lt;!--# else --&gt;
200 ...
201 &lt;!--# endif --&gt;
202 </example>
203 Only one level of nesting is currently supported.
204 The command has the following parameter:
205
206 <list type="tag">
207 <tag-name><literal>expr</literal></tag-name>
208 <tag-desc>
209 expression.
210 An expression can be:
211
212 <list type="bullet">
213
214 <listitem>
215 variable existence check:
216 <example>
217 &lt;!--# if expr="$name" --&gt;
218 </example>
219 </listitem>
220
221 <listitem>
222 comparison of a variable with a text:
223 <example>
224 &lt;!--# if expr="$name = <value>text</value>" --&gt;
225 &lt;!--# if expr="$name != <value>text</value>" --&gt;
226 </example>
227 </listitem>
228
229 <listitem>
230 comparison of a variable with a regular expression:
231 <example>
232 &lt;!--# if expr="$name = /<value>text</value>/" --&gt;
233 &lt;!--# if expr="$name != /<value>text</value>/" --&gt;
234 </example>
235 </listitem>
236 </list>
237
238 If a <value>text</value> contains variables,
239 their values are substituted.
240 A regular expression can contain positional and named captures
241 that can later be used through variables, for example:
242 <example>
243 &lt;!--# if expr="$name = /(.+)@(?P&lt;domain&gt;.+)/" --&gt;
244 &lt;!--# echo var="1" --&gt;
245 &lt;!--# echo var="domain" --&gt;
246 &lt;!--# endif --&gt;
247 </example>
248 </tag-desc>
249 </list>
250
251 </tag-desc>
252
253
254 <tag-name><literal>include</literal></tag-name>
255 <tag-desc>
256 Includes the result of another request into a response.
257 The command has the following parameters:
258
259 <list type="tag">
260 <tag-name><literal>file</literal></tag-name>
261 <tag-desc>
262 specifies an included file, for example:
263 <example>
264 &lt;!--# include file="footer.html" --&gt;
265 </example>
266 </tag-desc>
267
268 <tag-name><literal>virtual</literal></tag-name>
269 <tag-desc>
270 specifies an included request, for example:
271 <example>
272 &lt;!--# include virtual="/remote/body.php?argument=value" --&gt;
273 </example>
274 Several requests specified on one page and processed by proxied or
275 FastCGI servers run in parallel.
276 If sequential processing is desired, the <literal>wait</literal>
277 parameter should be used.
278 </tag-desc>
279
280 <tag-name><literal>stub</literal></tag-name>
281 <tag-desc>
282 non-standard parameter that names the block whose
283 content will be output if an included request results in an empty
284 body or if an error occurs during request processing, for example:
285 <example>
286 &lt;!--# block name="one" --&gt;&amp;nbsp;&lt;!--# endblock --&gt;
287 &lt;!--# include virtual="/remote/body.php?argument=value" stub="one" --&gt;
288 </example>
289 The replacement block content is processed in the included request context.
290 </tag-desc>
291
292 <tag-name><literal>wait</literal></tag-name>
293 <tag-desc>
294 non-standard parameter that instructs to wait for a request to fully
295 complete before continuing with SSI processing, for example:
296 <example>
297 &lt;!--# include virtual="/remote/body.php?argument=value" wait="yes" --&gt;
298 </example>
299 </tag-desc>
300
301 <tag-name><literal>set</literal></tag-name>
302 <tag-desc>
303 non-standard parameter that instructs to write a successful result
304 of request processing to the specified variable,
305 for example:
306 <example>
307 &lt;!--# include virtual="/remote/body.php?argument=value" set="one" --&gt;
308 </example>
309 It should be noted that only the results of responses obtained using the
310 <link doc="ngx_http_proxy_module.xml">ngx_http_proxy_module</link> and
311 <link doc="ngx_http_memcached_module.xml">ngx_http_memcached_module</link>
312 modules can be written into variables.
313 </tag-desc>
314
315 </list>
316
317 </tag-desc>
318
319
320 <tag-name><literal>set</literal></tag-name>
321 <tag-desc>
322 Sets a value of a variable.
323 The command has the following parameters:
324
325 <list type="tag">
326 <tag-name><literal>var</literal></tag-name>
327 <tag-desc>
328 variable name.
329 </tag-desc>
330
331 <tag-name><literal>value</literal></tag-name>
332 <tag-desc>
333 variable value.
334 If an assigned value contains variables,
335 their values are substituted.
336 </tag-desc>
337 </list>
338
339 </tag-desc>
340
341 </list>
342 </para>
343
344 </section>
345
346
347 <section id="variables" name="Embedded Variables">
348
349 <para>
350 The <literal>ngx_http_ssi_module</literal> module supports
351 two embedded variables:
352 <list type="tag">
353
354 <tag-name><var>$date_local</var></tag-name>
355 <tag-desc>
356 current time in local time zone.
357 The format is set by the <literal>config</literal> command
358 with the <literal>timefmt</literal> parameter.
359 </tag-desc>
360
361 <tag-name><var>$date_gmt</var></tag-name>
362 <tag-desc>
363 current time in GMT.
364 The format is set by the <literal>config</literal> command
365 with the <literal>timefmt</literal> parameter.
366 </tag-desc>
367
368 </list>
369 </para>
370
371 </section>
372
373 </module>