Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_js_module.xml @ 1840:15632fc2d548

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented http and stream nginScript modules.
author Yaroslav Zhuravlev <yar@nginx.com>
date Fri, 18 Nov 2016 17:51:14 +0300
parents
children f56626ce9c40
comparison
equal deleted inserted replaced
1839:4035f9146bbf 1840:15632fc2d548
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Module ngx_http_js_module"
10 link="/en/docs/http/ngx_http_js_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_http_js_module</literal> module is used to implement
18 location and variable handlers in JavaScript.
19 </para>
20
21 <para>
22 This module is not built by default, it should be compiled with
23 nginx JavaScript module using the
24 <literal>--add_module</literal> configuration parameter:
25 <example>
26 ./configure --add-module=<value>path-to-njs</value>/nginx
27 </example>
28 The <link url="http://hg.nginx.org/njs">repository</link>
29 with nginx JavaScript module can be cloned with the following command
30 (requires <link url="https://www.mercurial-scm.org">Mercurial</link> client):
31 <example>
32 hg clone http://hg.nginx.org/njs
33 </example>
34 This module can also be built as
35 <link doc="../ngx_core_module.xml" id="load_module">dynamic</link>:
36 <example>
37 ./configure --add-dynamic_module=<value>path-to-njs</value>/nginx
38 </example>
39 </para>
40
41 </section>
42
43
44 <section id="issues" name="Known Issues">
45
46 <para>
47 The module is experimental, caveat emptor applies.
48 </para>
49
50 </section>
51
52
53 <section id="example" name="Example Configuration">
54
55 <para>
56 <example>
57 js_include http.js;
58
59 server {
60 listen 8000;
61
62 location / {
63 js_set $foo foo;
64 add_header X-Foo $foo;
65 js_content baz;
66 }
67
68 location /summary {
69 js_set $summary summary;
70 return 200 $summary;
71 }
72 }
73 </example>
74 </para>
75
76 <para>
77 The <path>http.js</path> file:
78 <example>
79 function foo(req, res) {
80 req.log("hello from foo() handler");
81 return "foo";
82 }
83
84 function summary(req, res) {
85 var a, s, h;
86
87 s = "JS summary\n\n";
88
89 s += "Method: " + req.method + "\n";
90 s += "HTTP version: " + req.httpVersion + "\n";
91 s += "Host: " + req.headers.host + "\n";
92 s += "Remote Address: " + req.remoteAddress + "\n";
93 s += "URI: " + req.uri + "\n";
94
95 s += "Headers:\n";
96 for (h in req.headers) {
97 s += " header '" + h + "' is '" + req.headers[h] + "'\n";
98 }
99
100 s += "Args:\n";
101 for (a in req.args) {
102 s += " arg '" + a + "' is '" + req.args[a] + "'\n";
103 }
104
105 return s;
106 }
107
108 function baz(req, res) {
109 res.headers.foo = 1234;
110 res.status = 200;
111 res.contentType = "text/plain; charset=utf-8";
112 res.contentLength = 15;
113 res.sendHeader();
114 res.send("nginx");
115 res.send("java");
116 res.send("script");
117
118 res.finish();
119 }
120 </example>
121 </para>
122
123 </section>
124
125
126 <section id="directives" name="Directives">
127
128 <directive name="js_include">
129 <syntax><value>file</value></syntax>
130 <default/>
131 <context>http</context>
132 <context>server</context>
133 <context>location</context>
134
135 <para>
136 Specifies a file that implements location and variable handlers in JavaScript.
137 </para>
138
139 </directive>
140
141
142 <directive name="js_content">
143 <syntax><value>function</value></syntax>
144 <default/>
145 <context>location</context>
146 <context>limit_except</context>
147
148 <para>
149 Sets a JavaScript function as a location content handler.
150 </para>
151
152 </directive>
153
154
155 <directive name="js_set">
156 <syntax>
157 <value>$variable</value> <value>function</value></syntax>
158 <default/>
159 <context>http</context>
160 <context>server</context>
161 <context>location</context>
162
163 <para>
164 Sets a JavaScript function for the specified variable.
165 </para>
166
167 </directive>
168
169 </section>
170
171
172 <section id="arguments" name="Request and Response Arguments">
173 <para>
174 Each HTTP JavaScript handler receives two arguments, request and response.
175 </para>
176
177 <para>
178 The request object has the following properties:
179 <list type="tag">
180
181 <tag-name><literal>uri</literal></tag-name>
182 <tag-desc>
183 current URI in a request, read-only
184 </tag-desc>
185
186 <tag-name><literal>method</literal></tag-name>
187 <tag-desc>
188 request method, read-only
189 </tag-desc>
190
191 <tag-name><literal>httpVersion</literal></tag-name>
192 <tag-desc>
193 HTTP version, read-only
194 </tag-desc>
195
196 <tag-name><literal>remoteAddress</literal></tag-name>
197 <tag-desc>
198 client address, read-only
199 </tag-desc>
200
201 <tag-name><literal>headers{}</literal></tag-name>
202 <tag-desc>
203 request headers object, read-only.
204 <para>
205 For example, the <literal>Header-Name</literal> header
206 can be accessed with the syntax <literal>headers['Header-Name']</literal>
207 or <literal>headers.Header_name</literal>
208 </para>
209 </tag-desc>
210
211 <tag-name><literal>args{}</literal></tag-name>
212 <tag-desc>
213 request arguments object, read-only
214 </tag-desc>
215
216 <tag-name><literal>variables{}</literal></tag-name>
217 <tag-desc>
218 nginx variables object, read-only
219 </tag-desc>
220
221 <tag-name><literal>log(<value>string</value>)</literal></tag-name>
222 <tag-desc>
223 writes a <literal>string</literal> to the error log
224 </tag-desc>
225 </list>
226 </para>
227
228 <para>
229 The response object has the following properties:
230 <list type="tag">
231
232 <tag-name><literal>status</literal></tag-name>
233 <tag-desc>
234 response status, writable
235 </tag-desc>
236
237 <tag-name><literal>headers{}</literal></tag-name>
238 <tag-desc>
239 response headers object
240 </tag-desc>
241
242 <tag-name><literal>contentType</literal></tag-name>
243 <tag-desc>
244 the response <header>Content-Type</header> header field value, writable
245 </tag-desc>
246
247 <tag-name><literal>contentLength</literal></tag-name>
248 <tag-desc>
249 the response <header>Content-Length</header> header field value, writable
250 </tag-desc>
251 </list>
252 </para>
253
254 <para>
255 The response object has the following methods:
256 <list type="tag">
257
258 <tag-name><literal>sendHeader()</literal></tag-name>
259 <tag-desc>
260 sends the HTTP header to the client
261 </tag-desc>
262
263 <tag-name><literal>send(<value>string</value>)</literal></tag-name>
264 <tag-desc>
265 sends a part of the response body to the client
266 </tag-desc>
267
268 <tag-name><literal>finish()</literal></tag-name>
269 <tag-desc>
270 finishes sending a response to the client
271 </tag-desc>
272 </list>
273 </para>
274
275 </section>
276
277 </module>