Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_ssi_module.xml @ 398:8548b80a4552

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Revision.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 07 Feb 2012 10:59:48 +0000
parents 15f81ed48a43
children 694db9597ee0
comparison
equal deleted inserted replaced
397:f1c0ae9c1c48 398:8548b80a4552
1 <?xml version="1.0"?> 1 <?xml version="1.0"?>
2 2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4 4
5 <module name="Директивы модуля ngx_http_ssi_module" 5 <module name="Модуль ngx_http_ssi_module"
6 link="/ru/docs/http/ngx_http_ssi_module.html" 6 link="/ru/docs/http/ngx_http_ssi_module.html"
7 lang="ru"> 7 lang="ru">
8 8
9 <section id="summary"> 9 <section id="summary">
10 10
11 <para> 11 <para>
12 Модуль ngx_http_ssi_module — фильтр, обрабатывающий команды SSI (Server 12 Модуль <literal>ngx_http_ssi_module</literal> — это фильтр,
13 Side Includes) в проходящих через него ответах. 13 обрабатывающий команды SSI (Server Side Includes) в проходящих
14 через него ответах.
14 На данный момент список поддерживаемых команд SSI неполон. 15 На данный момент список поддерживаемых команд SSI неполон.
15 </para> 16 </para>
16 17
17 </section> 18 </section>
18 19
19 20
20 <section name="Пример конфигурации" id="example"> 21 <section id="example" name="Пример конфигурации">
21 22
22 <para> 23 <para>
23 <example> 24 <example>
24 location / { 25 location / {
25 ssi on; 26 ssi on;
26 ... 27 ...
27 } 28 }
28 </example> 29 </example>
29 </para> 30 </para>
30 31
31 </section> 32 </section>
32 33
33 34
34 <section name="Директивы" id="directives"> 35 <section id="directives" name="Директивы">
35 36
36 <directive name="ssi"> 37 <directive name="ssi">
37 <syntax><literal>on</literal> | <literal>off</literal></syntax> 38 <syntax><literal>on</literal> | <literal>off</literal></syntax>
38 <default>off</default> 39 <default>off</default>
39 <context>http, server, location, if в location</context> 40 <context>http</context>
40 41 <context>server</context>
41 <para> 42 <context>location</context>
42 Директива разрешает обработку команд SSI в ответах. 43 <context>if в location</context>
44
45 <para>
46 Разрешает или запрещает обработку команд SSI в ответах.
43 </para> 47 </para>
44 48
45 </directive> 49 </directive>
46 50
47 51
48 <directive name="ssi_silent_errors"> 52 <directive name="ssi_silent_errors">
49 <syntax><literal>on</literal> | <literal>off</literal></syntax> 53 <syntax><literal>on</literal> | <literal>off</literal></syntax>
50 <default>off</default> 54 <default>off</default>
51 <context>http, server, location</context> 55 <context>http</context>
52 56 <context>server</context>
53 <para> 57 <context>location</context>
54 Директива разрешает не выводить строку 58
55 "[an error occurred while processing the directive]", 59 <para>
60 Разрешает не выводить строку
61 “<literal>[an error occurred while processing the directive]</literal>”,
56 если во время обработки SSI произошла ошибка. 62 если во время обработки SSI произошла ошибка.
57 </para> 63 </para>
58 64
59 </directive> 65 </directive>
60 66
61 67
62 <directive name="ssi_types"> 68 <directive name="ssi_types">
63 <syntax><value>mime-тип</value> ...</syntax> 69 <syntax><value>mime-тип</value> ...</syntax>
64 <default>text/html</default> 70 <default>text/html</default>
65 <context>http, server, location</context> 71 <context>http</context>
66 72 <context>server</context>
67 <para> 73 <context>location</context>
68 Разрешает обработку команд SSI в ответах с указанными MIME-типами в дополнение 74
69 к "text/html". 75 <para>
76 Разрешает обработку команд SSI в ответах с указанными MIME-типами
77 в дополнение к “<literal>text/html</literal>”.
70 </para> 78 </para>
71 79
72 </directive> 80 </directive>
73 81
74 </section> 82 </section>
75 83
76 84
77 <section name="Команды SSI" id="commands"> 85 <section id="commands" name="Команды SSI">
78 86
79 <para> 87 <para>
80 Формат команды следующий 88 Общий формат команд SSI такой:
81 <example> 89 <example>
82 &lt;!--# команда параметр1=значение параметр2=значение ... --&gt; 90 &lt;!--# команда параметр1=значение1 параметр2=значение2 ... --&gt;
83 </example> 91 </example>
84 </para> 92 </para>
85 93
86 <para> 94 <para>
87 Ниже перечислены поддерживаемые команды: 95 Поддерживаются следующие команды:
88 <list type="bullet"> 96 <list type="tag">
89 97
90 <listitem> 98 <tag-name><literal>block</literal></tag-name>
91 <emphasis>block</emphasis> — команда описывает блок, который можно использовать 99 <tag-desc>
92 как заглушку в команде include. 100 Описывает блок, который можно использовать
93 Внутри блока могут быть команды SSI. 101 как заглушку в команде <literal>include</literal>.
94 102 Внутри блока могут быть другие команды SSI.
95 <list type="bullet"> 103 Параметр команды:
96 <listitem> 104
97 <emphasis>name</emphasis> — имя блока. 105 <list type="tag">
98 </listitem> 106 <tag-name><literal>name</literal></tag-name>
99 </list> 107 <tag-desc>
100 108 имя блока.
101 Пример использования: 109 </tag-desc>
110 </list>
111
112 Пример:
102 <example> 113 <example>
103 &lt;!--# block name="one" --&gt; 114 &lt;!--# block name="one" --&gt;
104 заглушка 115 заглушка
105 &lt;!--# endblock --&gt; 116 &lt;!--# endblock --&gt;
106 </example> 117 </example>
107 118
108 </listitem> 119 </tag-desc>
109 120
110 <listitem> 121
111 <emphasis>config</emphasis> — команда задаёт некоторые параметры при обработке SSI. 122 <tag-name><literal>config</literal></tag-name>
112 123 <tag-desc>
113 <list type="bullet"> 124 Задаёт некоторые параметры, используемые при обработке SSI, а именно:
114 <listitem> 125
115 <emphasis>errmsg</emphasis> — строка, выводящаяся при ошибке во время обработки 126 <list type="tag">
116 SSI. По умолчанию используется такая строка: 127 <tag-name><literal>errmsg</literal></tag-name>
128 <tag-desc>
129 строка, выводящаяся при ошибке во время обработки SSI.
130 По умолчанию выводится такая строка:
117 <example> 131 <example>
118 [an error occurred while processing the directive] 132 [an error occurred while processing the directive]
119 </example> 133 </example>
120 </listitem> 134 </tag-desc>
121 135
122 <listitem> 136 <tag-name><literal>timefmt</literal></tag-name>
123 <emphasis>timefmt</emphasis> — строка, используемая функцией strftime(3) 137 <tag-desc>
124 для вывода дат и времени. 138 строка формата, передаваемая функции <c-func>strftime</c-func>
139 для вывода даты и времени.
125 По умолчанию используется такой формат: 140 По умолчанию используется такой формат:
126 <example> 141 <example>
127 "%A, %d-%b-%Y %H:%M:%S %Z" 142 "%A, %d-%b-%Y %H:%M:%S %Z"
128 </example> 143 </example>
129 Для вывода времени в секундах подходит формат "%s". 144 Для вывода времени в секундах подходит формат
130 </listitem> 145 “<literal>%s</literal>”.
131 </list> 146 </tag-desc>
132 147 </list>
133 </listitem> 148
134 149 </tag-desc>
135 150
136 <listitem> 151
137 <emphasis>echo</emphasis> — команда выводит значение переменной. 152 <tag-name><literal>echo</literal></tag-name>
138 153 <tag-desc>
139 <list type="bullet"> 154 Выводит значение переменной.
140 <listitem> 155 Параметры команды:
141 <emphasis>var</emphasis> — имя переменной. 156
142 </listitem> 157 <list type="tag">
143 158 <tag-name><literal>var</literal></tag-name>
144 <listitem> 159 <tag-desc>
145 <emphasis>encoding</emphasis> — способ кодирования. 160 имя переменной.
146 Возможны три значения — none, url и entity. 161 </tag-desc>
147 По умолчанию используется entity. 162
148 </listitem> 163 <tag-name><literal>encoding</literal></tag-name>
149 164 <tag-desc>
150 <listitem> 165 способ кодирования.
151 <emphasis>default</emphasis> — нестандартный параметр, задающий строку, 166 Возможны три значения — <literal>none</literal>, <literal>url</literal> и
152 которая выводится, если переменная не определена. 167 <literal>entity</literal>.
153 По умолчанию выводится строка "none". Команда 168 По умолчанию используется <literal>entity</literal>.
169 </tag-desc>
170
171 <tag-name><literal>default</literal></tag-name>
172 <tag-desc>
173 нестандартный параметр, задающий строку, которая выводится,
174 если переменная не определена.
175 По умолчанию выводится строка
176 “<literal>none</literal>”.
177 Команда
154 <example> 178 <example>
155 &lt;!--# echo var="name" default="<emphasis>нет</emphasis>" --&gt; 179 &lt;!--# echo var="name" default="<emphasis>нет</emphasis>" --&gt;
156 </example> 180 </example>
157 заменяет такую последовательность команд 181 заменяет такую последовательность команд:
158 <example> 182 <example>
159 &lt;!--# if expr="$name" --&gt;&lt;!--# echo var="name" --&gt;&lt;!--# 183 &lt;!--# if expr="$name" --&gt;&lt;!--# echo var="name" --&gt;&lt;!--#
160 else --&gt;<emphasis>нет</emphasis>&lt;!--# endif --&gt; 184 else --&gt;<emphasis>нет</emphasis>&lt;!--# endif --&gt;
161 </example> 185 </example>
162 </listitem> 186 </tag-desc>
163 </list> 187 </list>
164 188
165 </listitem> 189 </tag-desc>
166 190
167 191
168 <listitem> 192 <tag-name><literal>if</literal></tag-name>
169 <emphasis>if</emphasis> — команда выполняет условное включение. 193 <tag-desc>
194 Выполняет условное включение.
170 Поддерживаются следующие команды: 195 Поддерживаются следующие команды:
171 <example> 196 <example>
172 &lt;!--# if expr="..." --&gt; 197 &lt;!--# if expr="..." --&gt;
173 ... 198 ...
174 &lt;!--# elif expr="..." --&gt; 199 &lt;!--# elif expr="..." --&gt;
175 ... 200 ...
176 &lt;!--# else --&gt; 201 &lt;!--# else --&gt;
177 ... 202 ...
178 &lt;!--# endif --&gt; 203 &lt;!--# endif --&gt;
179 </example> 204 </example>
180 На данный момент поддерживаются только один уровень вложенности. 205 На данный момент поддерживается только один уровень вложенности.
206 Параметр команды:
207
208 <list type="tag">
209 <tag-name><literal>expr</literal></tag-name>
210 <tag-desc>
211 выражение.
212 В выражении может быть:
181 213
182 <list type="bullet"> 214 <list type="bullet">
215
183 <listitem> 216 <listitem>
184 <emphasis>expr</emphasis> — выражение. 217 проверка существования переменной:
185 В выражении может быть проверка существования переменной:
186 <example> 218 <example>
187 &lt;!--# if expr="$name" --&gt; 219 &lt;!--# if expr="$name" --&gt;
188 </example> 220 </example>
221 </listitem>
222
223 <listitem>
189 сравнение переменной с текстом: 224 сравнение переменной с текстом:
190 <example> 225 <example>
191 &lt;!--# if expr="$name = text" --&gt; 226 &lt;!--# if expr="$name = <value>text</value>" --&gt;
192 &lt;!--# if expr="$name != text" --&gt; 227 &lt;!--# if expr="$name != <value>text</value>" --&gt;
193 </example> 228 </example>
194 или с регулярным выражением: 229 </listitem>
195 <example> 230
196 &lt;!--# if expr="$name = /text/" --&gt; 231 <listitem>
197 &lt;!--# if expr="$name != /text/" --&gt; 232 сравнение переменной с регулярным выражением:
198 </example> 233 <example>
199 Если в text встречаются переменные, то производится подстановка их значений. 234 &lt;!--# if expr="$name = /<value>text</value>/" --&gt;
235 &lt;!--# if expr="$name != /<value>text</value>/" --&gt;
236 </example>
237 </listitem>
238 </list>
239
240 Если в <value>text</value> встречаются переменные,
241 то производится подстановка их значений.
200 В регулярном выражении можно задать позиционные и именованные выделения, 242 В регулярном выражении можно задать позиционные и именованные выделения,
201 а затем использовать их через переменные: 243 а затем использовать их через переменные, например:
202 <example> 244 <example>
203 &lt;!--# if expr="$name = /(.+)@(?P&lt;domain&gt;.+)/" --&gt; 245 &lt;!--# if expr="$name = /(.+)@(?P&lt;domain&gt;.+)/" --&gt;
204 &lt;!--# echo var="1" --&gt; 246 &lt;!--# echo var="1" --&gt;
205 &lt;!--# echo var="domain" --&gt; 247 &lt;!--# echo var="domain" --&gt;
206 &lt;!--# endif --&gt; 248 &lt;!--# endif --&gt;
207 </example> 249 </example>
208 </listitem> 250 </tag-desc>
209 </list> 251 </list>
210 252
211 </listitem> 253 </tag-desc>
212 254
213 255
214 <listitem> 256 <tag-name><literal>include</literal></tag-name>
215 <emphasis>include</emphasis> — команда включает в ответ результат другого запроса. 257 <tag-desc>
216 258 Включает в ответ результат другого запроса.
217 <list type="bullet"> 259 Параметры команды:
218 <listitem> 260
219 <emphasis>file</emphasis> — задаёт включаемый файл, например: 261 <list type="tag">
262 <tag-name><literal>file</literal></tag-name>
263 <tag-desc>
264 задаёт включаемый файл, например:
220 <example> 265 <example>
221 &lt;!--# include file="footer.html" --&gt; 266 &lt;!--# include file="footer.html" --&gt;
222 </example> 267 </example>
223 </listitem> 268 </tag-desc>
224 269
225 <listitem> 270 <tag-name><literal>virtual</literal></tag-name>
226 <emphasis>virtual</emphasis> — задаёт включаемый запрос, например: 271 <tag-desc>
272 задаёт включаемый запрос, например:
227 <example> 273 <example>
228 &lt;!--# include virtual="/remote/body.php?argument=value" --&gt; 274 &lt;!--# include virtual="/remote/body.php?argument=value" --&gt;
229 </example> 275 </example>
230 Несколько запросов на одной странице, обрабатываемые через прокси или FastCGI, 276 Несколько запросов, указанных на одной странице и обрабатываемых
231 работают параллельно. Если нужно последовательная обработка, то нужно 277 проксируемыми или FastCGI-серверами, работают параллельно.
232 воспользоваться параметром wait. 278 Если нужна последовательная обработка, следует воспользоваться параметром
233 </listitem> 279 <literal>wait</literal>.
234 280 </tag-desc>
235 <listitem> 281
236 <emphasis>stub</emphasis> — нестандартный параметр, задающий имя блока, 282 <tag-name><literal>stub</literal></tag-name>
283 <tag-desc>
284 нестандартный параметр, задающий имя блока,
237 содержимое которого будет выведено, если тело ответа на включаемый запрос 285 содержимое которого будет выведено, если тело ответа на включаемый запрос
238 пустое или при исполнении запроса произошла ошибка, например: 286 пустое или если при исполнении запроса произошла ошибка, например:
239 <example> 287 <example>
240 &lt;!--# block name="one" --&gt;&amp;nbsp;&lt;!--# endblock --&gt; 288 &lt;!--# block name="one" --&gt;&amp;nbsp;&lt;!--# endblock --&gt;
241 &lt;!--# include virtual="/remote/body.php?argument=value" stub="one" --&gt; 289 &lt;!--# include virtual="/remote/body.php?argument=value" stub="one" --&gt;
242 </example> 290 </example>
243 при этом содержимое замещающего блока обрабатывается в контексте включаемого 291 Содержимое замещающего блока обрабатывается в контексте включаемого запроса.
244 запроса. 292 </tag-desc>
245 </listitem> 293
246 294 <tag-name><literal>wait</literal></tag-name>
247 <listitem> 295 <tag-desc>
248 <emphasis>wait</emphasis> — нестандартный параметр, указывающий, нужно ли ждать 296 нестандартный параметр, указывающий, нужно ли ждать
249 полного исполнения данного запроса, прежде чем продолжать выполнение 297 полного исполнения данного запроса, прежде чем продолжать выполнение
250 SSI, например: 298 SSI, например:
251 <example> 299 <example>
252 &lt;!--# include virtual="/remote/body.php?argument=value" wait="yes" --&gt; 300 &lt;!--# include virtual="/remote/body.php?argument=value" wait="yes" --&gt;
253 </example> 301 </example>
254 </listitem> 302 </tag-desc>
255 303
256 <listitem> 304 <tag-name><literal>set</literal></tag-name>
257 <emphasis>set</emphasis> — нестандартный параметр, указывающий, что удачный 305 <tag-desc>
306 нестандартный параметр, указывающий, что удачный
258 результат выполнения запроса нужно записать в заданную переменную, 307 результат выполнения запроса нужно записать в заданную переменную,
259 например: 308 например:
260 <example> 309 <example>
261 &lt;!--# include virtual="/remote/body.php?argument=value" set="one" --&gt; 310 &lt;!--# include virtual="/remote/body.php?argument=value" set="one" --&gt;
262 </example> 311 </example>
263 Необходимо учитывать, что в переменные можно записать только результаты 312 Необходимо учитывать, что в переменные можно записать только результаты
264 ответов, полученные через модули 313 ответов, полученные через модули
265 ngx_http_proxy_module и ngx_http_memcached_module. 314 <link doc="ngx_http_proxy_module.xml">ngx_http_proxy_module</link> и
266 </listitem> 315 <link doc="ngx_http_memcached_module.xml">ngx_http_memcached_module</link>.
267 316 </tag-desc>
268 </list> 317
269 318 </list>
270 </listitem> 319
271 320 </tag-desc>
272 <listitem> 321
273 <emphasis>set</emphasis> — команда присваивает значение переменной. 322
274 323 <tag-name><literal>set</literal></tag-name>
275 <list type="bullet"> 324 <tag-desc>
276 <listitem> 325 Присваивает значение переменной.
277 <emphasis>var</emphasis> — имя переменной. 326 Параметры команды:
278 </listitem> 327
279 328 <list type="tag">
280 <listitem> 329 <tag-name><literal>var</literal></tag-name>
281 <emphasis>value</emphasis> — значение переменной. Если в присваиваемом значении 330 <tag-desc>
282 есть переменные, то производится подстановка их значений. 331 имя переменной.
283 </listitem> 332 </tag-desc>
284 </list> 333
285 334 <tag-name><literal>value</literal></tag-name>
286 </listitem> 335 <tag-desc>
287 336 значение переменной.
288 </list> 337 Если в присваиваемом значении есть переменные,
289 </para> 338 то производится подстановка их значений.
290 339 </tag-desc>
291 </section> 340 </list>
292 341
293 342 </tag-desc>
294 <section name="Встроенные переменные" id="variables"> 343
295 344 </list>
296 <para> 345 </para>
297 Модуль ngx_http_ssi_module поддерживает две встроенные переменные: 346
298 <list type="bullet"> 347 </section>
299 348
300 <listitem> 349
301 $date_local, эта переменная равна текущему времени в локальной временной зоне. 350 <section id="variables" name="Встроенные переменные">
302 Формат даты задаётся командой config с параметром timefmt. 351
303 </listitem> 352 <para>
304 353 Модуль <literal>ngx_http_ssi_module</literal> поддерживает
305 <listitem> 354 две встроенные переменные:
306 $date_gmt, эта переменная равна текущему времени в GMT. 355 <list type="tag">
307 Формат даты задаётся командой config с параметром timefmt. 356
308 </listitem> 357 <tag-name><var>$date_local</var></tag-name>
358 <tag-desc>
359 текущее время в локальной временной зоне.
360 Формат задаётся командой <literal>config</literal>
361 с параметром <literal>timefmt</literal>.
362 </tag-desc>
363
364 <tag-name><var>$date_gmt</var></tag-name>
365 <tag-desc>
366 текущее время в GMT.
367 Формат задаётся командой <literal>config</literal>
368 с параметром <literal>timefmt</literal>.
369 </tag-desc>
309 370
310 </list> 371 </list>
311 </para> 372 </para>
312 373
313 </section> 374 </section>