Mercurial > hg > nginx-site
changeset 2530:407c5bd5bffc
Documented the js_import directive and corresponding changes.
Also the following changes:
- js_include is deprecated
- js_access, js_content, js_filter, js_preread, js_set
can now accept module.function
- Example Configuration changed for both http and stream js modules.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Wed, 22 Apr 2020 16:54:11 +0100 |
parents | 8cc141e0460f |
children | 9c8a89d3876f |
files | xml/en/docs/http/ngx_http_js_module.xml xml/en/docs/stream/ngx_stream_js_module.xml xml/ru/docs/http/ngx_http_js_module.xml xml/ru/docs/stream/ngx_stream_js_module.xml |
diffstat | 4 files changed, 281 insertions(+), 45 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_js_module.xml Tue Apr 21 17:38:08 2020 +0300 +++ b/xml/en/docs/http/ngx_http_js_module.xml Wed Apr 22 16:54:11 2020 +0100 @@ -9,7 +9,7 @@ <module name="Module ngx_http_js_module" link="/en/docs/http/ngx_http_js_module.html" lang="en" - rev="19"> + rev="20"> <section id="summary"> @@ -32,22 +32,24 @@ <section id="example" name="Example Configuration"> <para> +The example works since +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>. <example> load_module modules/ngx_http_js_module.so; ... http { - js_include http.js; + js_import http.js; - js_set $foo foo; - js_set $summary summary; + js_set $foo http.foo; + js_set $summary http.summary; server { listen 8000; location / { add_header X-Foo $foo; - js_content baz; + js_content http.baz; } location = /summary { @@ -55,7 +57,7 @@ } location = /hello { - js_content hello; + js_content http.hello; } } } @@ -110,6 +112,8 @@ function hello(r) { r.return(200, "Hello world!"); } + +export default {foo, summary, baz, hello}; </example> </para> @@ -119,13 +123,44 @@ <section id="directives" name="Directives"> <directive name="js_content"> -<syntax><value>function</value></syntax> +<syntax><value>function</value> | <value>module.function</value></syntax> <default/> <context>location</context> <context>limit_except</context> <para> Sets an njs function as a location content handler. +Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +a module function can be referenced. +</para> + +</directive> + + +<directive name="js_import"> +<syntax><value>module.js</value> | +<value>export_name from module.js</value></syntax> +<default/> +<context>http</context> +<appeared-in>0.4.0</appeared-in> + +<para> +Imports a module that implements location and variable handlers in njs. +The <literal>export_name</literal> is used as a namespace +to access module functions. +If the <literal>export_name</literal> is not specified, +the module name will be used as a namespace. +<example> +js_import http.js; +</example> +Here, the module name <literal>http</literal> is used as a namespace +while accessing exports. +If the imported module contains <literal>foo()</literal>, +<literal>http.foo</literal> is used to refer to it. +</para> + +<para> +Several <literal>js_import</literal> directives can be specified. </para> </directive> @@ -137,7 +172,25 @@ <context>http</context> <para> -Specifies a file that implements location and variable handlers in njs. +Specifies a file that implements location and variable handlers in njs: +<example> +nginx.conf: +js_include http.js; +location /version { + js_content version; +} + +http.js: +function version(r) { + r.return(200, njs.version); +} +</example> +</para> + +<para> +The directive is deprecated since +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +the <link id="js_import"/> directive should be used instead. </para> </directive> @@ -159,12 +212,15 @@ <directive name="js_set"> <syntax> -<value>$variable</value> <value>function</value></syntax> +<value>$variable</value> <value>function</value> | +<value>module.function</value></syntax> <default/> <context>http</context> <para> Sets an njs function for the specified variable. +Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +a module function can be referenced. </para> </directive>
--- a/xml/en/docs/stream/ngx_stream_js_module.xml Tue Apr 21 17:38:08 2020 +0300 +++ b/xml/en/docs/stream/ngx_stream_js_module.xml Wed Apr 22 16:54:11 2020 +0100 @@ -9,7 +9,7 @@ <module name="Module ngx_stream_js_module" link="/en/docs/stream/ngx_stream_js_module.html" lang="en" - rev="17"> + rev="18"> <section id="summary"> @@ -31,29 +31,31 @@ <section id="example" name="Example Configuration"> <para> +The example works since +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>. <example> load_module modules/ngx_stream_js_module.so; ... stream { - js_include stream.js; + js_import stream.js; - js_set $bar bar; - js_set $req_line req_line; + js_set $bar stream.bar; + js_set $req_line stream.req_line; server { listen 12345; - js_preread preread; + js_preread stream.preread; return $req_line; } server { listen 12346; - js_access access; + js_access stream.access; proxy_pass 127.0.0.1:8000; - js_filter header_inject; + js_filter stream.header_inject; } } @@ -121,6 +123,8 @@ s.allow(); } + +export default {bar, preread, req_line, access}; </example> </para> @@ -130,7 +134,7 @@ <section id="directives" name="Directives"> <directive name="js_access"> -<syntax><value>function</value></syntax> +<syntax><value>function</value> | <value>module.function</value></syntax> <default/> <context>stream</context> <context>server</context> @@ -138,19 +142,52 @@ <para> Sets an njs function which will be called at the <link doc="stream_processing.xml" id="access_phase">access</link> phase. +Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +a module function can be referenced. </para> </directive> <directive name="js_filter"> -<syntax><value>function</value></syntax> +<syntax><value>function</value> | <value>module.function</value></syntax> <default/> <context>stream</context> <context>server</context> <para> Sets a data filter. +Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +a module function can be referenced. +</para> + +</directive> + + +<directive name="js_import"> +<syntax><value>module.js</value> | +<value>export_name from module.js</value></syntax> +<default/> +<context>stream</context> +<appeared-in>0.4.0</appeared-in> + +<para> +Imports a module that implements location and variable handlers in njs. +The <literal>export_name</literal> is used as a namespace +to access module functions. +If the <literal>export_name</literal> is not specified, +the module name will be used as a namespace. +<example> +js_import stream.js; +</example> +Here, the module name <literal>stream</literal> is used as a namespace +while accessing exports. +If the imported module contains <literal>foo()</literal>, +<literal>stream.foo</literal> is used to refer to it. +</para> + +<para> +Several <literal>js_import</literal> directives can be specified. </para> </directive> @@ -162,7 +199,27 @@ <context>stream</context> <para> -Specifies a file that implements server and variable handlers in njs. +Specifies a file that implements server and variable handlers in njs: +<example> +nginx.conf: +js_include stream.js; +js_set $js_addr address; +server { + listen 127.0.0.1:12345; + return $js_addr; +} + +stream.js: +function address(s) { + return s.remoteAddress; +} +</example> +</para> + +<para> +The directive is deprecated since +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +the <link id="js_import"/> directive should be used instead. </para> </directive> @@ -183,7 +240,7 @@ <directive name="js_preread"> -<syntax><value>function</value></syntax> +<syntax><value>function</value> | <value>module.function</value></syntax> <default/> <context>stream</context> <context>server</context> @@ -191,6 +248,8 @@ <para> Sets an njs function which will be called at the <link doc="stream_processing.xml" id="preread_phase">preread</link> phase. +Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +a module function can be referenced. </para> </directive> @@ -198,12 +257,15 @@ <directive name="js_set"> <syntax> -<value>$variable</value> <value>function</value></syntax> +<value>$variable</value> <value>function</value> | +<value>module.function</value></syntax> <default/> <context>stream</context> <para> Sets an njs function for the specified variable. +Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +a module function can be referenced. </para> </directive>
--- a/xml/ru/docs/http/ngx_http_js_module.xml Tue Apr 21 17:38:08 2020 +0300 +++ b/xml/ru/docs/http/ngx_http_js_module.xml Wed Apr 22 16:54:11 2020 +0100 @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_js_module" link="/ru/docs/http/ngx_http_js_module.html" lang="ru" - rev="19"> + rev="20"> <section id="summary"> @@ -32,22 +32,24 @@ <section id="example" name="Пример конфигурации"> <para> +Пример работает начиная с версии +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>. <example> load_module modules/ngx_http_js_module.so; ... http { - js_include http.js; + js_import http.js; - js_set $foo foo; - js_set $summary summary; + js_set $foo http.foo; + js_set $summary http.summary; server { listen 8000; location / { add_header X-Foo $foo; - js_content baz; + js_content http.baz; } location = /summary { @@ -55,7 +57,7 @@ } location = /hello { - js_content hello; + js_content http.hello; } } } @@ -63,7 +65,7 @@ </para> <para> -Файл <path>http.js</path>: +The <path>http.js</path> file: <example> function foo(r) { r.log("hello from foo() handler"); @@ -110,6 +112,8 @@ function hello(r) { r.return(200, "Hello world!"); } + +export default {foo, summary, baz, hello}; </example> </para> @@ -119,13 +123,45 @@ <section id="directives" name="Директивы"> <directive name="js_content"> -<syntax><value>функция</value></syntax> +<syntax><value>функция</value> | <value>модуль.функция</value></syntax> <default/> <context>location</context> <context>limit_except</context> <para> Задаёт функцию njs в качестве обработчика содержимого location. +Начиная с версии <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> +можно ссылаться на функцию модуля. +</para> + +</directive> + + +<directive name="js_import"> +<syntax><value>модуль.js</value> | +<value>имя_экспорта из модуль.js</value></syntax> +<default/> +<context>http</context> +<appeared-in>0.4.0</appeared-in> + +<para> +Импортирует модуль, позволяющий задавать обработчики location и переменных +на njs. +<literal>Имя_экспорта</literal> является пространством имён +при доступе к функциям модуля. +Если <literal>имя_экспорта</literal> не задано, +то пространством имён будет являться имя модуля. +<example> +js_import http.js; +</example> +В примере при доступе к экспорту в качестве +пространства имён используется имя модуля <literal>http</literal>. +Если импортируемый модуль содержит <literal>foo()</literal>, +то для доступа используется <literal>http.foo</literal>. +</para> + +<para> +Директив <literal>js_import</literal> может быть несколько. </para> </directive> @@ -137,8 +173,25 @@ <context>http</context> <para> -Задаёт файл, позволяющий задавать обработчики location и переменных -на njs. +Задаёт файл, позволяющий задавать обработчики location и переменных на njs: +<example> +nginx.conf: +js_include http.js; +location /version { + js_content version; +} + +http.js: +function version(r) { + r.return(200, njs.version); +} +</example> +</para> + +<para> +Директива устарела начиная с +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +вместо неё следует использовать директиву <link id="js_import"/>. </para> </directive> @@ -160,12 +213,15 @@ <directive name="js_set"> <syntax> -<value>$переменная</value> <value>функция</value></syntax> +<value>$переменная</value> <value>функция</value> | +<value>модуль.функция</value></syntax> <default/> <context>http</context> <para> Задаёт функцию njs для указанной переменной. +Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> +можно ссылаться на функцию модуля. </para> </directive>
--- a/xml/ru/docs/stream/ngx_stream_js_module.xml Tue Apr 21 17:38:08 2020 +0300 +++ b/xml/ru/docs/stream/ngx_stream_js_module.xml Wed Apr 22 16:54:11 2020 +0100 @@ -9,7 +9,7 @@ <module name="Модуль ngx_stream_js_module" link="/ru/docs/stream/ngx_stream_js_module.html" lang="ru" - rev="17"> + rev="18"> <section id="summary"> @@ -31,29 +31,31 @@ <section id="example" name="Пример конфигурации"> <para> +Пример работает начиная с версии +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>. <example> load_module modules/ngx_stream_js_module.so; ... stream { - js_include stream.js; + js_import stream.js; - js_set $bar bar; - js_set $req_line req_line; + js_set $bar stream.bar; + js_set $req_line stream.req_line; server { listen 12345; - js_preread preread; + js_preread stream.preread; return $req_line; } server { listen 12346; - js_access access; + js_access stream.access; proxy_pass 127.0.0.1:8000; - js_filter header_inject; + js_filter stream.header_inject; } } @@ -121,6 +123,8 @@ s.allow(); } + +export default {bar, preread, req_line, access}; </example> </para> @@ -130,7 +134,7 @@ <section id="directives" name="Директивы"> <directive name="js_access"> -<syntax><value>функция</value></syntax> +<syntax><value>функция</value> | <value>модуль.функция</value></syntax> <default/> <context>stream</context> <context>server</context> @@ -138,19 +142,53 @@ <para> Задаёт функцию njs, которая будет вызываться в <link doc="stream_processing.xml" id="access_phase">access</link>-фазе. +Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> +можно ссылаться на функцию модуля. </para> </directive> <directive name="js_filter"> -<syntax><value>функция</value></syntax> +<syntax><value>функция</value> | <value>модуль.функция</value></syntax> <default/> <context>stream</context> <context>server</context> <para> Задаёт фильтр данных. +Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> +можно ссылаться на функцию модуля. +</para> + +</directive> + + +<directive name="js_import"> +<syntax><value>модуль.js</value> | +<value>имя_экспорта из модуль.js</value></syntax> +<default/> +<context>stream</context> +<appeared-in>0.4.0</appeared-in> + +<para> +Импортирует модуль, позволяющий задавать обработчики location и переменных +на njs. +<literal>Имя_экспорта</literal> является пространством имён +при доступе к функциям модуля. +Если <literal>имя_экспорта</literal> не задано, +то пространством имён будет являться имя модуля. +<example> +js_import stream.js; +</example> +В примере при доступе к экспорту в качестве +пространства имён используется имя модуля <literal>stream</literal>. +Если импортируемый модуль содержит <literal>foo()</literal>, +то для доступа используется <literal>stream.foo</literal>. +</para> + +<para> +Директив <literal>js_import</literal> может быть несколько. </para> </directive> @@ -162,15 +200,34 @@ <context>stream</context> <para> -Задаёт файл, который позволяет -задавать обработчики server и переменных на njs. +Задаёт файл, который позволяет задавать обработчики server и переменных на njs: +<example> +nginx.conf: +js_include stream.js; +js_set $js_addr address; +server { + listen 127.0.0.1:12345; + return $js_addr; +} + +stream.js: +function address(s) { + return s.remoteAddress; +} +</example> +</para> + +<para> +Директива устарела начиная с +<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, +вместо неё следует использовать директиву <link id="js_import"/>. </para> </directive> <directive name="js_preread"> -<syntax><value>функция</value></syntax> +<syntax><value>функция</value> | <value>модуль.функция</value></syntax> <default/> <context>stream</context> <context>server</context> @@ -178,6 +235,8 @@ <para> Задаёт функцию njs, которая будет вызываться в <link doc="stream_processing.xml" id="preread_phase">preread</link>-фазе. +Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> +можно ссылаться на функцию модуля. </para> </directive> @@ -199,12 +258,15 @@ <directive name="js_set"> <syntax> -<value>$переменная</value> <value>функция</value></syntax> +<value>$переменная</value> <value>функция</value> | +<value>модуль.функция</value></syntax> <default/> <context>stream</context> <para> Задаёт функцию njs для указанной переменной. +Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> +можно ссылаться на функцию модуля. </para> </directive>