Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_ssi_module.xml @ 403:60611ce5fe79
Donation added.
author | Maxim Konovalov <maxim@nginx.com> |
---|---|
date | Thu, 09 Feb 2012 06:36:23 +0000 |
parents | a56540cdcea5 |
children | 694db9597ee0 |
line wrap: on
line source
<?xml version="1.0"?> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_ssi_module" link="/en/docs/http/ngx_http_ssi_module.html" lang="en"> <section id="summary"> <para> The <literal>ngx_http_ssi_module</literal> module is a filter that processes SSI (Server Side Includes) commands in responses passing through it. Currently, the list of supported SSI commands is incomplete. </para> </section> <section id="example" name="Example Configuration"> <para> <example> location / { ssi on; ... } </example> </para> </section> <section id="directives" name="Directives"> <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 in location</context> <para> Enables or disables processing of SSI commands in responses. </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> Allows to suppress output of the string “<literal>[an error occurred while processing the directive]</literal>” if an error occurred during SSI processing. </para> </directive> <directive name="ssi_types"> <syntax><value>mime-type</value> ...</syntax> <default>text/html</default> <context>http</context> <context>server</context> <context>location</context> <para> Enables processing of SSI commands in responses with the specified MIME types in addition to “<literal>text/html</literal>”. </para> </directive> </section> <section id="commands" name="SSI Commands"> <para> SSI commands have the following generic format: <example> <!--# command parameter1=value1 parameter2=value2 ... --> </example> </para> <para> The following commands are supported: <list type="tag"> <tag-name><literal>block</literal></tag-name> <tag-desc> Defines a block that can be used as a stub in the <literal>include</literal> command. The block can contain other SSI commands. The command has the following parameter: <list type="tag"> <tag-name><literal>name</literal></tag-name> <tag-desc> block name. </tag-desc> </list> Example: <example> <!--# block name="one" --> stub <!--# endblock --> </example> </tag-desc> <tag-name><literal>config</literal></tag-name> <tag-desc> Sets some parameters used during SSI processing, namely: <list type="tag"> <tag-name><literal>errmsg</literal></tag-name> <tag-desc> a string that is output if an error occurs during SSI processing. By default, the following string is output: <example> [an error occurred while processing the directive] </example> </tag-desc> <tag-name><literal>timefmt</literal></tag-name> <tag-desc> a format string passed to the <c-func>strftime</c-func> function used to output date and time. By default, the following format is used: <example> "%A, %d-%b-%Y %H:%M:%S %Z" </example> The “<literal>%s</literal>” format is suitable to output time in seconds. </tag-desc> </list> </tag-desc> <tag-name><literal>echo</literal></tag-name> <tag-desc> Outputs the value of a variable. The command has the following parameters: <list type="tag"> <tag-name><literal>var</literal></tag-name> <tag-desc> variable name. </tag-desc> <tag-name><literal>encoding</literal></tag-name> <tag-desc> encoding method. Possible values include <literal>none</literal>, <literal>url</literal>, and <literal>entity</literal>. By default, <literal>entity</literal> is used. </tag-desc> <tag-name><literal>default</literal></tag-name> <tag-desc> non-standard parameter that sets a string to be output if a variable is undefined. By default, “<literal>none</literal>” is output. The command <example> <!--# echo var="name" default="<emphasis>no</emphasis>" --> </example> replaces the following sequence of commands: <example> <!--# if expr="$name" --><!--# echo var="name" --><!--# else --><emphasis>no</emphasis><!--# endif --> </example> </tag-desc> </list> </tag-desc> <tag-name><literal>if</literal></tag-name> <tag-desc> Performs a conditional inclusion. The following commands are supported: <example> <!--# if expr="..." --> ... <!--# elif expr="..." --> ... <!--# else --> ... <!--# endif --> </example> Only one level of nesting is currently supported. The command has the following parameter: <list type="tag"> <tag-name><literal>expr</literal></tag-name> <tag-desc> expression. An expression can be: <list type="bullet"> <listitem> variable existence check: <example> <!--# if expr="$name" --> </example> </listitem> <listitem> comparison of a variable with a text: <example> <!--# if expr="$name = <value>text</value>" --> <!--# if expr="$name != <value>text</value>" --> </example> </listitem> <listitem> comparison of a variable with a regular expression: <example> <!--# if expr="$name = /<value>text</value>/" --> <!--# if expr="$name != /<value>text</value>/" --> </example> </listitem> </list> If a <value>text</value> contains variables, their values are substituted. A regular expression can contain positional and named captures that can later be used through variables, for example: <example> <!--# if expr="$name = /(.+)@(?P<domain>.+)/" --> <!--# echo var="1" --> <!--# echo var="domain" --> <!--# endif --> </example> </tag-desc> </list> </tag-desc> <tag-name><literal>include</literal></tag-name> <tag-desc> Includes the result of another request into a response. The command has the following parameters: <list type="tag"> <tag-name><literal>file</literal></tag-name> <tag-desc> specifies an included file, for example: <example> <!--# include file="footer.html" --> </example> </tag-desc> <tag-name><literal>virtual</literal></tag-name> <tag-desc> specifies an included request, for example: <example> <!--# include virtual="/remote/body.php?argument=value" --> </example> Several requests specified on one page and processed by proxied or FastCGI servers run in parallel. If sequential processing is desired, the <literal>wait</literal> parameter should be used. </tag-desc> <tag-name><literal>stub</literal></tag-name> <tag-desc> non-standard parameter that names the block whose content will be output if an included request results in an empty body or if an error occurs during request processing, for example: <example> <!--# block name="one" -->&nbsp;<!--# endblock --> <!--# include virtual="/remote/body.php?argument=value" stub="one" --> </example> The replacement block content is processed in the included request context. </tag-desc> <tag-name><literal>wait</literal></tag-name> <tag-desc> non-standard parameter that instructs to wait for a request to fully complete before continuing with SSI processing, for example: <example> <!--# include virtual="/remote/body.php?argument=value" wait="yes" --> </example> </tag-desc> <tag-name><literal>set</literal></tag-name> <tag-desc> non-standard parameter that instructs to write a successful result of request processing to the specified variable, for example: <example> <!--# include virtual="/remote/body.php?argument=value" set="one" --> </example> It should be noted that only the results of responses obtained using the <link doc="ngx_http_proxy_module.xml">ngx_http_proxy_module</link> and <link doc="ngx_http_memcached_module.xml">ngx_http_memcached_module</link> modules can be written into variables. </tag-desc> </list> </tag-desc> <tag-name><literal>set</literal></tag-name> <tag-desc> Sets a value of a variable. The command has the following parameters: <list type="tag"> <tag-name><literal>var</literal></tag-name> <tag-desc> variable name. </tag-desc> <tag-name><literal>value</literal></tag-name> <tag-desc> variable value. If an assigned value contains variables, their values are substituted. </tag-desc> </list> </tag-desc> </list> </para> </section> <section id="variables" name="Embedded Variables"> <para> The <literal>ngx_http_ssi_module</literal> module supports two embedded variables: <list type="tag"> <tag-name><var>$date_local</var></tag-name> <tag-desc> current time in local time zone. The format is set by the <literal>config</literal> command with the <literal>timefmt</literal> parameter. </tag-desc> <tag-name><var>$date_gmt</var></tag-name> <tag-desc> current time in GMT. The format is set by the <literal>config</literal> command with the <literal>timefmt</literal> parameter. </tag-desc> </list> </para> </section> </module>