<?xml version="1.0"?>

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

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

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

<section id="summary">

<para>
Модуль <literal>ngx_http_xslt_module</literal> (0.7.8+) — это фильтр,
преобразующий XML-ответ с помощью одного или нескольких XSLT-шаблонов.
</para>

<para>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
<literal>--with-http_xslt_module</literal>.
<note>
Для сборки и работы этого модуля нужны библиотеки
<link url="http://xmlsoft.org">libxml2</link> и
<link url="http://xmlsoft.org/XSLT/">libxslt</link>.
</note>
</para>

</section>


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

<para>
<example>
location / {
    xml_entities    /site/dtd/entities.dtd;
    xslt_stylesheet /site/xslt/one.xslt param=value;
    xslt_stylesheet /site/xslt/two.xslt;
}
</example>
</para>

</section>


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

<directive name="xml_entities">
<syntax><value>путь</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт файл DTD, в котором описаны символьные сущности.
Этот файл компилируется на стадии конфигурации.
По техническим причинам модуль не имеет возможности
использовать внешнее подмножество, заданное в обрабатываемом XML,
поэтому оно игнорируется, а вместо него используется специально заданный файл.
В этом файле не нужно описывать структуру XML, достаточно только объявления
необходимых символьных сущностей, например:
<example>
&lt;!ENTITY nbsp "&amp;#xa0;"&gt;
</example>
</para>

</directive>


<directive name="xslt_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>
исходного ответа во время XSLT-преобразований
для лучшего кэширования ответов.
</para>

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

</directive>


<directive name="xslt_param">
<syntax><value>параметр</value> <value>значение</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.18</appeared-in>

<para>
Задаёт параметры для XSLT-шаблонов.
Значение рассматривается как выражение XPath.
В значении можно использовать переменные.
Если нужно передать в шаблон строковое значение,
можно воспользоваться директивой <link id="xslt_string_param"/>.
</para>

<para>
Директив <literal>xslt_param</literal> может быть несколько.
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы <literal>xslt_param</literal>
и <link id="xslt_string_param"/>.
</para>

</directive>


<directive name="xslt_string_param">
<syntax><value>параметр</value> <value>значение</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.18</appeared-in>

<para>
Задаёт строковые параметры для XSLT-шаблонов.
Выражения XPath в значении параметра не интерпретируются.
В значении можно использовать переменные.
</para>

<para>
Директив <literal>xslt_string_param</literal> может быть несколько.
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы <link id="xslt_param"/>
и <literal>xslt_string_param</literal>.
</para>

</directive>


<directive name="xslt_stylesheet">
<syntax>
    <value>шаблон</value>
    [<value>параметр</value>=<value>значение</value> ...]</syntax>
<default/>
<context>location</context>

<para>
Задаёт XSLT-шаблон и необязательные параметры для этого шаблона.
Шаблон компилируется на стадии конфигурации.
</para>

<para>
Параметры можно задавать как по отдельности, так и группировать
в одной строке, разделяя символом “<literal>:</literal>”.
Если же в самих параметрах встречается символ “<literal>:</literal>”,
то его нужно экранировать в виде “<literal>%3A</literal>”.
Кроме того, <command>libxslt</command> требует,
чтобы параметры, содержащие не только алфавитно-цифровые символы,
были заключены в одинарные или двойные кавычки, например:
<example>
param1='http%3A//www.example.com':param2=value2
</example>
</para>

<para>
В описании параметров можно использовать переменные, например,
целая строка параметров может быть взята из одной переменной:
<example>
location / {
    xslt_stylesheet /site/xslt/one.xslt
                    $arg_xslt_params
                    param1='$value1':param2=value2
                    param3=value3;
}
</example>
</para>

<para>
Можно указать несколько шаблонов — в этом случае они
будут применяться последовательно в порядке их описания.
</para>

</directive>


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

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

</directive>

</section>

</module>