<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_ssi_module"
        link="/ru/docs/http/ngx_http_ssi_module.html"
        lang="ru"
        rev="12">

<section id="summary">

<para>
Модуль <literal>ngx_http_ssi_module</literal> — это фильтр,
обрабатывающий команды SSI (Server Side Includes) в проходящих
через него ответах.
На данный момент список поддерживаемых команд SSI неполон.
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
location / {
    ssi on;
    ...
}
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="ssi">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>

<para>
Разрешает или запрещает обработку команд SSI в ответах.
</para>

</directive>


<directive name="ssi_last_modified">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.5.1</appeared-in>

<para>
Позволяет сохранить поле заголовка <header>Last-Modified</header>
исходного ответа во время обработки SSI
для лучшего кэширования ответов.
</para>

<para>
По умолчанию поле заголовка удаляется, так как содержимое ответа
изменяется во время обработки и может содержать динамически созданные
элементы или части, которые изменились независимо от исходного ответа.
</para>

</directive>


<directive name="ssi_min_file_chunk">
<syntax><literal>размер</literal></syntax>
<default>1k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт минимальный <value>размер</value> частей ответа, хранящихся
на диске, начиная с которого имеет смысл посылать их с помощью
<link doc="ngx_http_core_module.xml" id="sendfile"/>.
</para>

</directive>


<directive name="ssi_silent_errors">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает не выводить строку
“<literal>[an error occurred while processing the directive]</literal>”,
если во время обработки SSI произошла ошибка.
</para>

</directive>


<directive name="ssi_types">
<syntax><value>mime-тип</value> ...</syntax>
<default>text/html</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает обработку команд SSI в ответах с указанными MIME-типами
в дополнение к “<literal>text/html</literal>”.
Специальное значение “<literal>*</literal>” соответствует любому MIME-типу
(0.8.29).
</para>

</directive>


<directive name="ssi_value_length">
<syntax><value>длина</value></syntax>
<default>256</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт максимальную длину значений параметров в SSI-командах.
</para>

</directive>

</section>


<section id="commands" name="Команды SSI">

<para>
Общий формат команд SSI такой:
<example>
&lt;!--# команда параметр1=значение1 параметр2=значение2 ... --&gt;
</example>
</para>

<para>
Поддерживаются следующие команды:
<list type="tag">

<tag-name><literal>block</literal></tag-name>
<tag-desc>
Описывает блок, который можно использовать
как заглушку в команде <literal>include</literal>.
Внутри блока могут быть другие команды SSI.
Параметр команды:

<list type="tag">
<tag-name><literal>name</literal></tag-name>
<tag-desc>
имя блока.
</tag-desc>
</list>

Пример:
<example>
&lt;!--# block name="one" --&gt;
заглушка
&lt;!--# endblock --&gt;
</example>

</tag-desc>


<tag-name><literal>config</literal></tag-name>
<tag-desc>
Задаёт некоторые параметры, используемые при обработке SSI, а именно:

<list type="tag">
<tag-name><literal>errmsg</literal></tag-name>
<tag-desc>
строка, выводящаяся при ошибке во время обработки SSI.
По умолчанию выводится такая строка:
<example>
[an error occurred while processing the directive]
</example>
</tag-desc>

<tag-name><literal>timefmt</literal></tag-name>
<tag-desc>
строка формата, передаваемая функции <c-func>strftime</c-func>
для вывода даты и времени.
По умолчанию используется такой формат:
<example>
"%A, %d-%b-%Y %H:%M:%S %Z"
</example>
Для вывода времени в секундах подходит формат
“<literal>%s</literal>”.
</tag-desc>
</list>

</tag-desc>


<tag-name><literal>echo</literal></tag-name>
<tag-desc>
Выводит значение переменной.
Параметры команды:

<list type="tag">
<tag-name><literal>var</literal></tag-name>
<tag-desc>
имя переменной.
</tag-desc>

<tag-name><literal>encoding</literal></tag-name>
<tag-desc>
способ кодирования.
Возможны три значения — <literal>none</literal>, <literal>url</literal> и
<literal>entity</literal>.
По умолчанию используется <literal>entity</literal>.
</tag-desc>

<tag-name><literal>default</literal></tag-name>
<tag-desc>
нестандартный параметр, задающий строку, которая выводится,
если переменная не определена.
По умолчанию выводится строка
“<literal>(none)</literal>”.
Команда
<example>
&lt;!--# echo var="name" default="<emphasis>нет</emphasis>" --&gt;
</example>
заменяет такую последовательность команд:
<example>
&lt;!--# if expr="$name" --&gt;&lt;!--# echo var="name" --&gt;&lt;!--#
       else --&gt;<emphasis>нет</emphasis>&lt;!--# endif --&gt;
</example>
</tag-desc>
</list>

</tag-desc>


<tag-name><literal>if</literal></tag-name>
<tag-desc>
Выполняет условное включение.
Поддерживаются следующие команды:
<example>
&lt;!--# if expr="..." --&gt;
...
&lt;!--# elif expr="..." --&gt;
...
&lt;!--# else --&gt;
...
&lt;!--# endif --&gt;
</example>
На данный момент поддерживается только один уровень вложенности.
Параметр команды:

<list type="tag">
<tag-name><literal>expr</literal></tag-name>
<tag-desc>
выражение.
В выражении может быть:

<list type="bullet">

<listitem>
проверка существования переменной:
<example>
&lt;!--# if expr="$name" --&gt;
</example>
</listitem>

<listitem>
сравнение переменной с текстом:
<example>
&lt;!--# if expr="$name = <value>text</value>" --&gt;
&lt;!--# if expr="$name != <value>text</value>" --&gt;
</example>
</listitem>

<listitem>
сравнение переменной с регулярным выражением:
<example>
&lt;!--# if expr="$name = /<value>text</value>/" --&gt;
&lt;!--# if expr="$name != /<value>text</value>/" --&gt;
</example>
</listitem>
</list>

Если в <value>text</value> встречаются переменные,
то производится подстановка их значений.
В регулярном выражении можно задать позиционные и именованные выделения,
а затем использовать их через переменные, например:
<example>
&lt;!--# if expr="$name = /(.+)@(?P&lt;domain&gt;.+)/" --&gt;
    &lt;!--# echo var="1" --&gt;
    &lt;!--# echo var="domain" --&gt;
&lt;!--# endif --&gt;
</example>
</tag-desc>
</list>

</tag-desc>


<tag-name><literal>include</literal></tag-name>
<tag-desc>
Включает в ответ результат другого запроса.
Параметры команды:

<list type="tag">
<tag-name><literal>file</literal></tag-name>
<tag-desc>
задаёт включаемый файл, например:
<example>
&lt;!--# include file="footer.html" --&gt;
</example>
</tag-desc>

<tag-name><literal>virtual</literal></tag-name>
<tag-desc>
задаёт включаемый запрос, например:
<example>
&lt;!--# include virtual="/remote/body.php?argument=value" --&gt;
</example>
Несколько запросов, указанных на одной странице и обрабатываемых
проксируемыми или FastCGI/uwsgi/SCGI/gRPC-серверами, работают параллельно.
Если нужна последовательная обработка, следует воспользоваться параметром
<literal>wait</literal>.
</tag-desc>

<tag-name><literal>stub</literal></tag-name>
<tag-desc>
нестандартный параметр, задающий имя блока,
содержимое которого будет выведено, если тело ответа на включаемый запрос
пустое или если при исполнении запроса произошла ошибка, например:
<example>
&lt;!--# block name="one" --&gt;&amp;nbsp;&lt;!--# endblock --&gt;
&lt;!--# include virtual="/remote/body.php?argument=value" stub="one" --&gt;
</example>
Содержимое замещающего блока обрабатывается в контексте включаемого запроса.
</tag-desc>

<tag-name><literal>wait</literal></tag-name>
<tag-desc>
нестандартный параметр, указывающий, нужно ли ждать
полного исполнения данного запроса, прежде чем продолжать выполнение
SSI, например:
<example>
&lt;!--# include virtual="/remote/body.php?argument=value" wait="yes" --&gt;
</example>
</tag-desc>

<tag-name id="ssi_include_set"><literal>set</literal></tag-name>
<tag-desc>
нестандартный параметр, указывающий, что удачный
результат выполнения запроса нужно записать в заданную переменную,
например:
<example>
&lt;!--# include virtual="/remote/body.php?argument=value" set="one" --&gt;
</example>
Максимальный размер ответа задаётся директивой
<link doc="ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
(1.13.10):
<example>
location /remote/ {
    subrequest_output_buffer_size 64k;
    ...
}
</example>
До версии 1.13.10 в переменные можно было записать только результаты
ответов, полученные через модули
<link doc="ngx_http_proxy_module.xml">ngx_http_proxy_module</link>,
<link doc="ngx_http_memcached_module.xml">ngx_http_memcached_module</link>,
<link doc="ngx_http_fastcgi_module.xml">ngx_http_fastcgi_module</link> (1.5.6),
<link doc="ngx_http_uwsgi_module.xml">ngx_http_uwsgi_module</link> (1.5.6)
и <link doc="ngx_http_scgi_module.xml">ngx_http_scgi_module</link> (1.5.6).
Максимальный размер ответа задавался при помощи директив
<link doc="ngx_http_proxy_module.xml" id="proxy_buffer_size"/>,
<link doc="ngx_http_memcached_module.xml" id="memcached_buffer_size"/>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_buffer_size"/>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_buffer_size"/>
и <link doc="ngx_http_scgi_module.xml" id="scgi_buffer_size"/>.
</tag-desc>

</list>

</tag-desc>


<tag-name><literal>set</literal></tag-name>
<tag-desc>
Присваивает значение переменной.
Параметры команды:

<list type="tag">
<tag-name><literal>var</literal></tag-name>
<tag-desc>
имя переменной.
</tag-desc>

<tag-name><literal>value</literal></tag-name>
<tag-desc>
значение переменной.
Если в присваиваемом значении есть переменные,
то производится подстановка их значений.
</tag-desc>
</list>

</tag-desc>

</list>
</para>

</section>


<section id="variables" name="Встроенные переменные">

<para>
Модуль <literal>ngx_http_ssi_module</literal> поддерживает
две встроенные переменные:
<list type="tag">

<tag-name id="var_date_local"><var>$date_local</var></tag-name>
<tag-desc>
текущее время в локальной временной зоне.
Формат задаётся командой <literal>config</literal>
с параметром <literal>timefmt</literal>.
</tag-desc>

<tag-name id="var_date_gmt"><var>$date_gmt</var></tag-name>
<tag-desc>
текущее время в GMT.
Формат задаётся командой <literal>config</literal>
с параметром <literal>timefmt</literal>.
</tag-desc>

</list>
</para>

</section>

</module>