Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_ssi_module.xml @ 76:4a4caa566120

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Russian documentation import. Changes in module.dtd: <example> now allowed to contain <value> and <emphasis> elements (we need this to show important parts in examples), less strict checking of <directive> syntax (we don't want to fully document some directives, notably deprecated ones). Known issues: 1. <syntax> elements are preserved as is, they will require manual conversion (likely to some not-yet-existed format a la DocBook cmdsynopsis, as currently used one seems to be incomplete); 2. <value> no longer corresponds to replaceable content, and it's use in examples isn't correct; 3. <link doc="document#fragment"> doesn't work with current xslt, either should be supported or changed to <link doc="document" id="fragment">. The following files are intentionally omitted: maillists.xml (support.xml should be used instead), experimental.xml (obsolete), faq.xml (conflicts with existing one, needs discussion). Not yet linked to site.
author Maxim Dounin <mdounin@mdounin.ru>
date Tue, 11 Oct 2011 12:57:50 +0000
parents
children c76a257f3fd4
comparison
equal deleted inserted replaced
75:2bf4cd2787c5 76:4a4caa566120
1 <?xml version="1.0" encoding="utf-8"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Директивы модуля ngx_http_ssi_module"
6 link="/ru/docs/http/ngx_http_ssi_module.html"
7 lang="ru">
8
9 <section name="" id="summary">
10
11 <para>
12 Модуль ngx_http_ssi_module — фильтр, обрабатывающий команды SSI (Server
13 Side Includes) в проходящих через него ответах.
14 На данный момент список поддерживаемых команд SSI неполон.
15 </para>
16
17 </section>
18
19
20 <section name="Пример конфигурации" id="example">
21
22 <para>
23 <example>
24 location / {
25 ssi on;
26 ...
27 }
28 </example>
29 </para>
30
31 </section>
32
33
34 <section name="Директивы" id="directives">
35
36 <directive name="ssi">
37 <syntax>ssi <value>[on|off]</value></syntax>
38 <default>ssi off</default>
39 <context>http, server, location, if в location</context>
40
41 <para>
42 Директива разрешает обработку команд SSI в ответах.
43 </para>
44
45 </directive>
46
47
48 <directive name="ssi_silent_errors">
49 <syntax>ssi_silent_errors <value>[on|off]</value></syntax>
50 <default>ssi_silent_errors off</default>
51 <context>http, server, location</context>
52
53 <para>
54 Директива разрешает не выводить строку
55 "[an error occurred while processing the directive]",
56 если во время обработки SSI произошла ошибка.
57 </para>
58
59 </directive>
60
61
62 <directive name="ssi_types">
63 <syntax>ssi_types <value>mime-тип [mime-тип ...]</value></syntax>
64 <default>ssi_types text/html</default>
65 <context>http, server, location</context>
66
67 <para>
68 Разрешает обработку команд SSI в ответах с указанными MIME-типами в дополнение
69 к "text/html".
70 </para>
71
72 </directive>
73
74 </section>
75
76
77 <section name="Команды SSI" id="commands">
78
79 <para>
80 Формат команды следующий
81 <example>
82 &lt;!--# команда параметр1=значение параметр2=значение ... --&gt;
83 </example>
84 </para>
85
86 <para>
87 Ниже перечислены поддерживаемые команды:
88 <list type="bullet">
89
90 <listitem>
91 <emphasis>block</emphasis> — команда описывает блок, который можно использовать
92 как заглушку в команде include.
93 Внутри блока могут быть команды SSI.
94
95 <list type="bullet">
96 <listitem>
97 <emphasis>name</emphasis> — имя блока.
98 </listitem>
99 </list>
100
101 Пример использования:
102 <example>
103 &lt;!--# block name="one" --&gt;
104 заглушка
105 &lt;!--# endblock --&gt;
106 </example>
107
108 </listitem>
109
110 <listitem>
111 <emphasis>config</emphasis> — команда задаёт некоторые параметры при обработке SSI.
112
113 <list type="bullet">
114 <listitem>
115 <emphasis>errmsg</emphasis> — строка, выводящаяся при ошибке во время обработки
116 SSI. По умолчанию используется такая строка:
117 <example>
118 [an error occurred while processing the directive]
119 </example>
120 </listitem>
121
122 <listitem>
123 <emphasis>timefmt</emphasis> — строка, используемая функцией strftime(3)
124 для вывода дат и времени.
125 По умолчанию используется такой формат:
126 <example>
127 "%A, %d-%b-%Y %H:%M:%S %Z"
128 </example>
129 Для вывода времени в секундах подходит формат "%s".
130 </listitem>
131 </list>
132
133 </listitem>
134
135
136 <listitem>
137 <emphasis>echo</emphasis> — команда выводит значение переменной.
138
139 <list type="bullet">
140 <listitem>
141 <emphasis>var</emphasis> — имя переменной.
142 </listitem>
143
144 <listitem>
145 <emphasis>encoding</emphasis> — способ кодирования.
146 Возможны три значения — none, url и entity.
147 По умолчанию используется entity.
148 </listitem>
149
150 <listitem>
151 <emphasis>default</emphasis> — нестандартный параметр, задающий строку,
152 которая выводится, если переменная не опеределена.
153 По умолчанию выводится строка "none". Команда
154 <example>
155 &lt;!--# echo var="name" default="<emphasis>нет</emphasis>" --&gt;
156 </example>
157 заменяет такую последовательность команд
158 <example>
159 &lt;!--# if expr="$name" --&gt;&lt;!--# echo var="name" --&gt;&lt;!--#
160 else --&gt;<emphasis>нет</emphasis>&lt;!--# endif --&gt;
161 </example>
162 </listitem>
163 </list>
164
165 </listitem>
166
167
168 <listitem>
169 <emphasis>if</emphasis> — команда выполняет условное включение.
170 Поддерживаются следующие команды:
171 <example>
172 &lt;!--# if expr="..." --&gt;
173 ...
174 &lt;!--# elif expr="..." --&gt;
175 ...
176 &lt;!--# else --&gt;
177 ...
178 &lt;!--# endif --&gt;
179 </example>
180 На данный момент поддерживаются только один уровень вложенности.
181
182 <list type="bullet">
183 <listitem>
184 <emphasis>expr</emphasis> — выражение.
185 В выражении может быть проверка существования переменной:
186 <example>
187 &lt;!--# if expr="$name" --&gt;
188 </example>
189 сравнение переменной с текстом:
190 <example>
191 &lt;!--# if expr="$name = text" --&gt;
192 &lt;!--# if expr="$name != text" --&gt;
193 </example>
194 или с регулярным выражением:
195 <example>
196 &lt;!--# if expr="$name = /text/" --&gt;
197 &lt;!--# if expr="$name != /text/" --&gt;
198 </example>
199 Если в text встречаются переменные, то производится подстановка их значений.
200 </listitem>
201 </list>
202
203 </listitem>
204
205
206 <listitem>
207 <emphasis>include</emphasis> — команда включает в ответ результат другого запроса.
208
209 <list type="bullet">
210 <listitem>
211 <emphasis>file</emphasis> — задаёт включаемый файл, например:
212 <example>
213 &lt;!--# include file="footer.html" --&gt;
214 </example>
215 </listitem>
216
217 <listitem>
218 <emphasis>virtual</emphasis> — задаёт включаемый запрос, например:
219 <example>
220 &lt;!--# include virtual="/remote/body.php?argument=value" --&gt;
221 </example>
222 Несколько запросов на одной странице, обрабатываемые через прокси или FastCGI,
223 работают параллельно. Если нужно последовательная обработка, то нужно
224 воспользоваться параметром wait.
225 </listitem>
226
227 <listitem>
228 <emphasis>stub</emphasis> — нестандартный параметр, задающий имя блока,
229 содержимое которого будет выведено, если тело ответа на включаемый запрос
230 пустое или при исполнении запроса произошла ошибка, например:
231 <example>
232 &lt;!--# block name="one" --&gt;&amp;nbsp;&lt;!--# endblock --&gt;
233 &lt;!--# include virtual="/remote/body.php?argument=value" stub="one" --&gt;
234 </example>
235 при этом содержимое замещающего блока обрабатывается в контексте включаемого
236 запроса.
237 </listitem>
238
239 <listitem>
240 <emphasis>wait</emphasis> — нестандартный параметр, указывающий, нужно ли ждать
241 полного исполнения данного запроса, прежде чем продолжать выполнение
242 SSI, например:
243 <example>
244 &lt;!--# include virtual="/remote/body.php?argument=value" wait="yes" --&gt;
245 </example>
246 </listitem>
247
248 <listitem>
249 <emphasis>set</emphasis> — нестандартный параметр, указывающий, что удачный
250 результат выполнения запроса нужно записать в заданную переменную,
251 например:
252 <example>
253 &lt;!--# include virtual="/remote/body.php?argument=value" set="one" --&gt;
254 </example>
255 Необходимо учитывать, что в переменные можно записать только результаты
256 ответов, полученные через модули
257 ngx_http_proxy_module и ngx_http_memcached_module.
258 </listitem>
259
260 </list>
261
262 </listitem>
263
264 <listitem>
265 <emphasis>set</emphasis> — команда присваивает значение переменной.
266
267 <list type="bullet">
268 <listitem>
269 <emphasis>var</emphasis> — имя переменной.
270 </listitem>
271
272 <listitem>
273 <emphasis>value</emphasis> — значение переменной. Если в присваиваемом значении
274 есть переменные, то производится подстановка их значений.
275 </listitem>
276 </list>
277
278 </listitem>
279
280 </list>
281 </para>
282
283 </section>
284
285
286 <section name="Встроенные переменные" id="variables">
287
288 <para>
289 Модуль ngx_http_ssi_module поддерживает две встроенные переменные:
290 <list type="bullet">
291
292 <listitem>
293 $date_local, эта переменная равна текущему времени в локальной временной зоне.
294 Формат даты задаётся командой config с параметром timefmt.
295 </listitem>
296
297 <listitem>
298 $date_gmt, эта переменная равна текущему времени в GMT.
299 Формат даты задаётся командой config с параметром timefmt.
300 </listitem>
301
302 </list>
303 </para>
304
305 </section>
306
307 </module>