Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 986 lines (772 sloc) 29.535 kb
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
1 .TH YAWS_API "5" "" "" "User API" -*- nroff -*-
abc3a43 @klacke documented yaws_api
authored
2 .SH NAME
3 yaws_api \- api available to yaws web server programmers
4 .SH SYNOPSIS
5 .B yaws_api:Function(...)
6
7 .SH DESCRIPTION
e2f272a @klacke explicit support for content_length
authored
8
abc3a43 @klacke documented yaws_api
authored
9 .PP
e263363 @klacke speling
authored
10 This is the api available to yaws web server programmers. The Erlang
abc3a43 @klacke documented yaws_api
authored
11 module yaws_api contains a wide variety of functions that can
12 be used inside yaws pages.
13
14 .PP
15 Each chunk of yaws code is executed while the yaws page is
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
16 being delivered from the server. We give a very simple example here
e263363 @klacke speling
authored
17 to show the basic idea. Imagine the following HTML code:
abc3a43 @klacke documented yaws_api
authored
18
19 \fI
20 .nf
21 <html>
22 <body>
23
24 <h1> Header 1</h1>
25
26 <erl>
27 out(Arg) ->
28 {html, "<p> Insert this text into the document"}.
29 </erl>
30
31 </body>
32 </html>
33
34 .fi
35 \fR
36
37
38 .PP
39 The \fBout(Arg)\fR function is supplied one argument, an #arg{} structure.
40 We have the following relevant record definitions:
41
42 \fI
43 .nf
44
45 -record(arg, {
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
46 clisock, % the socket leading to the peer client
47 client_ip_port, % {ClientIp, ClientPort} tuple
48 headers, % headers
49 req, % request
50 clidata, % The client data (as a binary in POST requests)
51 server_path, % The normalized server path
52 % (pre-querystring part of URI)
53 querydata, % For URIs of the form ...?querydata
54 % equiv of cgi QUERY_STRING
55 appmoddata, % (deprecated - use pathinfo instead) the remainder
56 % of the path leading up to the query
57 docroot, % Physical base location of data for this request
58 docroot_mount, % virtual directory e.g /myapp/ that the docroot
59 % refers to.
60 fullpath, % full deep path to yaws file
61 cont, % Continuation for chunked multipart uploads
62 state, % State for use by users of the out/1 callback
63 pid, % pid of the yaws worker process
64 opaque, % useful to pass static data
65 appmod_prepath, % (deprecated - use prepath instead) path in front
66 % of: <appmod><appmoddata>
67 prepath, % Path prior to 'dynamic' segment of URI.
68 % ie http://some.host/<prepath>/<script-point>/d/e
69 % where <script-point> is an appmod mount point,
70 % or .yaws,.php,.cgi,.fcgi etc script file.
71 pathinfo % Set to '/d/e' when calling c.yaws for the request
72 % http://some.host/a/b/c.yaws/d/e
73 % equiv of cgi PATH_INFO
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
74 }).
abc3a43 @klacke documented yaws_api
authored
75 .fi
76 \fR
77
78 The headers argument is also a record:
79 \fI
80 .nf
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
81
abc3a43 @klacke documented yaws_api
authored
82 -record(headers, {
8d5aa60 @klacke ""
authored
83 connection,
84 accept,
85 host,
86 if_modified_since,
87 if_match,
88 if_none_match,
89 if_range,
90 if_unmodified_since,
91 range,
92 referer,
93 user_agent,
94 accept_ranges,
95 cookie = [],
96 keep_alive,
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
97 location,
8d5aa60 @klacke ""
authored
98 content_length,
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
99 content_type,
100 content_encoding,
8d5aa60 @klacke ""
authored
101 authorization,
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
102 transfer_encoding,
103 x_forwarded_for,
104 other = [] % misc other headers
8d5aa60 @klacke ""
authored
105 }).
abc3a43 @klacke documented yaws_api
authored
106 .fi
107 \fR
108
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
109 .PP
110 The \fBout/1\fR function can use the Arg to generate any content
abc3a43 @klacke documented yaws_api
authored
111 it likes. We have the following functions to aid that generation.
112
113
114 .SH API
115
116 .TP
117 \fBssi(DocRoot, ListOfFiles)\fR
118 Server side include. Just include the files as is in the document. The files
119 will \fBnot\fR be parsed and searched for <erl> tags.
120
121
122 .TP
123 \fBpre_ssi_files(DocRoot, ListOfFiles) ->
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
124 Server side include of pre-indented code. The data in Files
abc3a43 @klacke documented yaws_api
authored
125 will be included but contained in a <pre> tag. The data will be
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
126 htmlized.
abc3a43 @klacke documented yaws_api
authored
127
128 .TP
129 \fBpre_ssi_string(String)\fR
130 Include htmlized content from String.
131
132
133 .TP
134 \fBf(Fmt, Args)\fR
135 The equivalent of io_lib:format/2. This function is automatically
136 -included in all erlang code which is a part of a yaws page.
137
138 .TP
c5ebd38 @klacke added pam support + prepare for 1.58
authored
139 \fBhtmlize(Binary | List | Char)\fR
140 Htmlize an IO list object.
abc3a43 @klacke documented yaws_api
authored
141
142 .TP
00c152b @saleyn Added RFC6265 compliant variant of setcookie.
saleyn authored
143 \fBset_cookie(Name, Value, Options])\fR
144 Sets a cookie to the browser. Options are:
145 \fI
146 .nf
147
148 {expires, UtcTime} - Cookie expiration time, where UtcTime is
149 a tuple returned by calendar:universal_time/0.
150 {max_age, Age} - Defines the lifetime of the cookie, in seconds,
151 where age is an integer >= 0.
152 {path, Path} - Path is a string that specifies the subset of URLs to
153 which this cookie applies.
154 {domain, Domain} - Domain is a string that specifies the domain for which
155 the cookie is valid.
156 {comment, Comment} - Comment is a string that doccuments the server's
157 intended use of the cookie.
158 secure - Directs the user agent to use only secure means to
159 contact the origin server whenever it sends back this
160 cookie.
161 http_only - Restricts cookie access from other non-HTTP APIs.
162 .fi
163 \fR
164
165 .TP
abc3a43 @klacke documented yaws_api
authored
166 \fBsetcookie(Name, Value, [Path, [ Expire, [Domain , [Secure]]]])\fR
00c152b @saleyn Added RFC6265 compliant variant of setcookie.
saleyn authored
167 Sets a cookie to the browser. This function is deprecated by set_cookie/3.
abc3a43 @klacke documented yaws_api
authored
168
169 .TP
170 \fBfind_cookie_val(Cookie, Header)\fR
171 This function can be used to search for a cookie that was previously
172 set by \fBsetcookie/2-6\fR. For example if we set a cookie
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
173 as \fByaws_api:setcookie("sid",SomeRandomSid)\fR, then on subsequent requests
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
174 from the browser we can call:
abc3a43 @klacke documented yaws_api
authored
175 \fBfind_cookie("sid",(Arg#arg.headers)#headers.cookie)\fR
176
177 The function returns [] if no cookie was found, otherwise the actual cookie
178 is returned as a string.
179
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
180 .TP
181 \fBparse_set_cookie(Str)\fR
ba07506 Refactor Set-Cookie/Cookie header parsing to follow RFC6265
Christopher Faulet authored
182 This function parses the value of a \fBSet-Cookie\fR header, following the
183 RFC6265. Because old RFCs (2109 and 2965) are still used, it is backward
184 compatible. So this function returns a \fI#setcookie{}\fR record when only one
185 cookie is found. If multiple cookies are set in a single \fBSet-Cookie\fR
186 header, it returns a list of \fI#setcookie{}\fR records. If no cookie was found
187 or if an error occurred, it returns [].
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
188
189 \fI#setcookie{}\fR record is defined in \fIyaws_api.hrl\fR:
190 \fI
191 .nf
192
ba07506 Refactor Set-Cookie/Cookie header parsing to follow RFC6265
Christopher Faulet authored
193 -record(setcookie, {key,
194 value,
195 quoted = false,
196 domain,
197 max_age,
198 expires,
199 path,
200 secure = false,
201 http_only = false,
202 extensions = []}).
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
203 .fi
204 \fR
205
206 .TP
207 \fBparse_cookie(Str)\fR
ba07506 Refactor Set-Cookie/Cookie header parsing to follow RFC6265
Christopher Faulet authored
208 This function parses the value of \fBCookie\fR header, following the RFC6265. It
209 returns a list of \fI#cookie{}\fR records. If no cookie was found or if an error
210 occurred, it returns [].
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
211
212 \fI#cookie{}\fR record is defined in \fIyaws_api.hrl\fR:
213 \fI
214 .nf
215
ba07506 Refactor Set-Cookie/Cookie header parsing to follow RFC6265
Christopher Faulet authored
216 -record(cookie, {key,
217 value,
218 quoted = false}).
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
219 .fi
220 \fR
221
222 .TP
ba07506 Refactor Set-Cookie/Cookie header parsing to follow RFC6265
Christopher Faulet authored
223 \fBformat_set_cookie(SetCookie)\fR
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
224 Build a cookie string from a \fI#setcookie{}\fR record like returned by
225 \fBparse_set_cookie/1\fR.
226
227 .TP
ba07506 Refactor Set-Cookie/Cookie header parsing to follow RFC6265
Christopher Faulet authored
228 \fBformat_cookie(Cookie | [Cookie])\fR
229 Build a cookie string from a \fI#cookie{}\fR record (or a list or records) like
230 returned by \fBparse_cookie/1\fR.
abc3a43 @klacke documented yaws_api
authored
231
232 .TP
3a8e071 @capflam Fix parse_set_cookie/1 and format_set_cookie/1 functions
capflam authored
233 \fBredirect(Url)\fR
abc3a43 @klacke documented yaws_api
authored
234 This function generates a redirect to the browser.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
235 It will clear any previously set headers. So to generate
236 a redirect \fBand\fR set a cookie, we need to set the cookie after
abc3a43 @klacke documented yaws_api
authored
237 the redirect as in:
238 \fI
239 .nf
240 out(Arg) ->
241 ... do some stuff
242
243 Ret = [{redirect, "http://www.somewhere.com"},
244 setcookie("sid", Random)
245 ].
246
247 .fi
248 \fR
249
250
251 .TP
883fa5a @klacke added redirect_self to yaws_api
authored
252 \fBredirect_self(Arg)\fR
253 If we want to issue a redirect to ourselves, this function
254 is useful. It returns a record \fI#redir_self{}\fR defined in
255 \fIyaws_api.hrl\fR. The record contains fields to construct
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
256 a URL to ourselves.
883fa5a @klacke added redirect_self to yaws_api
authored
257 \fI
258 .nf
259
260 -record(redir_self, {
1e7a122 @vinoski some man page cleanup/repair
vinoski authored
261 host, % string() - our own host
262 scheme, % http | https
263 scheme_str, % "https://" | "http://"
264 port, % integer() - our own port
265 port_str % "" | ":<int>" - the optional port part
266 % to append to the url
883fa5a @klacke added redirect_self to yaws_api
authored
267 }).
3dee1a5 Update documentation and manpages accordingly
Christopher Faulet authored
268 .fi
883fa5a @klacke added redirect_self to yaws_api
authored
269
270
271 .TP
abc3a43 @klacke documented yaws_api
authored
272 \fBget_line(String)\fR
d02b965 @klacke qnx port + docs overhaul by cschatz@networkadvantage.biz
authored
273 This function is convenient when getting \\r\\n terminated lines
abc3a43 @klacke documented yaws_api
authored
274 from a stream of data. It returns:
275
276 \fB{line, Line, Tail}\fR or \fB{lastline, Line, Tail}\fR
277
278 The function handles multilines as defined in e.g. SMTP or HTTP
279
280 .TP
89a64ef Make the mime types mappings configurable
Christopher Faulet authored
281 \fBmime_type(Scope, FileName)\fR
282 Returns the MIME type as defined by the extension of \fIFileName\fR. \fIScope\fR
283 can have following values:
284
285 .RS 12
286 \fBglobal\fR - returns the result obtained from the global context.
287 .br
288 \fB#sconf{} | {ServerName, Port}\fR - returns the result obtained from the
289 virtual server's context. If no MIME type is found in this scope, it falls back
290 on the global one.
291 .RE
292
293 .TP
abc3a43 @klacke documented yaws_api
authored
294 \fBmime_type(FileName)\fR
89a64ef Make the mime types mappings configurable
Christopher Faulet authored
295 Tries to determine the right \fIScope\fR before calling mime_type/2.
296
abc3a43 @klacke documented yaws_api
authored
297
298 .TP
299 \fBstream_chunk_deliver(YawsPid, Data)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
300 When a yaws function needs to deliver chunks of data which it gets
abc3a43 @klacke documented yaws_api
authored
301 from a process. The other process can call this function to deliver
302 these chunks. It requires the \fBout/1\fR function to return the
303 value \fB{streamcontent, MimeType, FirstChunk}\fR to work.
404aec1 @sgolovan fix syntax and spelling errors in man pages
sgolovan authored
304 YawsPid is the process identifier of the yaws process delivering the
305 original .yaws file. That is self() in the yaws code.
ebb94d8 @klacke 1.54
authored
306 The Pid must typically be passed (somehow) to the producer of the stream.
abc3a43 @klacke documented yaws_api
authored
307
a39fab8 @klacke added example docs on how to stream data
authored
308 .TP
309 \fBstream_chunk_deliver_blocking(YawsPid, Data)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
310 A synchronous version of the above function. This synchronous version
311 must always be used when the producer of the stream is faster than the
312 consumer. This is usually the case since the client is the WWW browser.
abc3a43 @klacke documented yaws_api
authored
313
314 .TP
315 \fBstream_chunk_end(YawsPid)\fR
316 When the process discussed above is done delivering data, it must call
317 this function to let the yaws content delivering process finish up
318 the HTTP transaction.
319
320 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
321 \fBstream_process_deliver(Socket, IoList)\fR
322 Yaws allows application processes to deliver data directly to the
323 client. The application tells yaws about such a process by returning
324 \fB{streamcontent_from_pid, MimeType, Pid}\fR from its \fBout/1\fR
325 function. In this case, \fIPid\fR uses the
326 \fBstream_process_deliver/2\fR function to deliver data to the
327 client. The application gets \fISocket\fR from \fIArg#arg.clisock\fR,
328 and \fIIoList\fR is the data to be sent to the client.
329
330 .TP
331 \fBstream_process_deliver_chunk(Socket, IoList)\fR
332 Same as above but delivers \fIIoList\fR using HTTP chunked transfer
333 format. \fIIoList\fR must have a size greater than zero. The
334 application process delivering the data will have had to have make
335 sure that the HTTP headers of the response indicate chunked transfer
336 mode, either by ensuring no Content-Length header is set or by
337 specifically setting the Transfer-Encoding header to chunked.
338
339 .TP
340 \fBstream_process_deliver_final_chunk(Socket, IoList)\fR
341 If the application process delivering data to the client uses chunked
342 transfer mode, it must call this to deliver the final chunk of the
343 transfer. This tells yaws to create a special final chunk in the
344 format required by the HTTP specification (RFC 2616). \fIIoList\fR may
345 be empty, but if its size is greater than zero, that data will be
346 sent as a separate chunk before the final chunk.
347
348 .TP
349 \fBstream_process_end(Socket, YawsPid)\fR
350 Application processes delivering data directly to clients must call
351 this function to inform yaws that they've finished using
352 \fISocket\fR. The \fIYawsPid\fR argument will have been passed to the
353 process earlier when yaws sent it a message telling it to proceed with
5da72a3 @vinoski Allow "stream processes" to close the client socket
vinoski authored
354 data delivery. Yaws expects \fISocket\fR to be open.
355
356 .TP
357 \fBstream_process_end(closed, YawsPid)\fR
358 Same as the previous function but the application calls this if it
359 closes the client socket as part of its data delivery process. This
360 allows yaws to continue without assuming the socket is still open and
361 encountering errors due to that assumption. The \fIYawsPid\fR argument
362 will have been passed to the application process earlier when yaws
363 sent it a message telling it to proceed with data delivery.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
364
365 .TP
abc3a43 @klacke documented yaws_api
authored
366 \fBparse_query(Arg)\fR
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
367 This function will parse the query part of the URL.
abc3a43 @klacke documented yaws_api
authored
368 It will return a {Key, Value} list of the items supplied in the query
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
369 part of the URL.
370
371 .TP
372 \fBqueryvar(Arg, VarName)\fR
373 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
374 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
375 querypart of the url. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk/ya...
authored
376 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
377 return \fI{Val1, ....}\fR.
abc3a43 @klacke documented yaws_api
authored
378
379
380 .TP
c4523b3 @klacke ""
authored
381 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
382 This function will parse the POST data as supplied from the browser.
383 It will return a {Key, Value} list of the items set by the browser.
384
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
385 .TP
386 \fBpostvar(Arg, VarName)\fR
387 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
388 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
389 POSTed data from the client. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk/ya...
authored
390 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
391 return \fI{Val1, ....}\fR.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
392
c9778e0 @klacke added support for 2 additional configure
authored
393 .TP
394 \fBgetvar(Arg, VarName)\fR
395 This function looks at the HTTP request method from the
396 client and invokes postvar/2 if it is a POST from the client
397 and queryvar/2 if it is a GET request from the client.
398
c4523b3 @klacke ""
authored
399
400 .TP
401 \fBparse_multipart_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
402 If the browser has set the Content-Type header to the value
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
403 "multipart/form-data", which is the case when the browser
abc3a43 @klacke documented yaws_api
authored
404 wants to upload a file to the server the following happens:
405
406 If the function returns \fB{result, Res}\fR no more data
407 will come from the browser.
408
409 If the function returns \fB{cont, Cont, Res}\fR the browser
410 will supply more data. (The file was to big to come in one read)
411
412 This indicates that there is more data to come and the out/1 function
413 should return {get_more, Cont, User_state} where User_state might
414 usefully be a File Descriptor.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
415 The Res value is a list of either:
af3e2ca Fix bugs in yaws_api:parse_multipart_post/1,2 for chunked requests
Christopher Faulet authored
416 \fB{head, {Name, Headers}}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
417
418 The function returns \fB{error, Reason}\fR when an error occurred during the
419 parsing.
abc3a43 @klacke documented yaws_api
authored
420
421
422 Example usage could be:
423 \fI
424 .nf
425 <erl>
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
426
abc3a43 @klacke documented yaws_api
authored
427 out(A) ->
c4523b3 @klacke ""
authored
428 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
429 {cont, Cont, Res} ->
430 St = handle_res(A, Res),
431 {get_more, Cont, St};
432 {result, Res} ->
433 handle_res(A, Res),
af3e2ca Fix bugs in yaws_api:parse_multipart_post/1,2 for chunked requests
Christopher Faulet authored
434 {html, f("<pre>Done </pre>",[])};
435 {error, Reason} ->
436 {html, f("An error occured: ~p", [Reason])}
abc3a43 @klacke documented yaws_api
authored
437 end.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
438
af3e2ca Fix bugs in yaws_api:parse_multipart_post/1,2 for chunked requests
Christopher Faulet authored
439 handle_res(A, [{head, {Name, _Hdrs}}|T]) ->
abc3a43 @klacke documented yaws_api
authored
440 io:format("head:~p~n",[Name]),
441 handle_res(A, T);
442 handle_res(A, [{part_body, Data}|T]) ->
443 io:format("part_body:~p~n",[Data]),
444 handle_res(A, T);
445 handle_res(A, [{body, Data}|T]) ->
446 io:format("body:~p~n",[Data]),
447 handle_res(A, T);
448 handle_res(A, []) ->
449 io:format("End_res~n").
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
450
abc3a43 @klacke documented yaws_api
authored
451 </erl>
452 .fi
453 \fR
454
455
456
457 .TP
87b1456 @klacke wrote the shopppingcart example
authored
458 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
459 Create a new cookie based session, the yaws system will set the
e263363 @klacke speling
authored
460 cookie. The new random generated cookie is returned from this
87b1456 @klacke wrote the shopppingcart example
authored
461 function. The Opaque argument will typically contain user data
e263363 @klacke speling
authored
462 such as user name and password
abc3a43 @klacke documented yaws_api
authored
463
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
464 .TP
465 \fBnew_cookie_session(Opaque, TTL)\fR
466 As above, but allows to set a session specific time-out value,
6964fff @klacke modified patch by Robert David to add a hook to yaws session server when...
authored
467 overriding the system specified time-out value.
468
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
469 .TP
6964fff @klacke modified patch by Robert David to add a hook to yaws session server when...
authored
470 \fBnew_cookie_session(Opaque, TTL, CleanupPid)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
471 As above, but also sends a message
6964fff @klacke modified patch by Robert David to add a hook to yaws session server when...
authored
472 \fI{yaws_session_end, Reason, Cookie, Opaque}\fR to the provided CleanuPid where
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
473 Reason can be either of \fItimeout\fR or \fInormal\fR. The \fICookie\fR
6964fff @klacke modified patch by Robert David to add a hook to yaws session server when...
authored
474 is the HTTP cookie as returned by \fInew_session()\fR and the Opaque
475 is the user provided Opaque parameter to \fInew_session()\fR.
476 The purpose of the feature is to cleanup resources assigned to the session.
477
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
478
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
479 .TP
87b1456 @klacke wrote the shopppingcart example
authored
480 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
481
482 .TP
483 \fBprint_cookie_sessions() \fR
484
87b1456 @klacke wrote the shopppingcart example
authored
485
486 .TP
487 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
488
abc3a43 @klacke documented yaws_api
authored
489 .TP
87b1456 @klacke wrote the shopppingcart example
authored
490 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
491
492
50a7ab2 @klacke added support/docs for embedded mode
authored
493 .TP
494 \fBsetconf(Gconf, Groups)\fR
495 This function is intended for embedded mode in yaws. It makes it possible
496 to load a yaws configuration from another data source than /etc/yaws.conf, such
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
497 as a database.
50a7ab2 @klacke added support/docs for embedded mode
authored
498 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
499 start with an empty default configuration, and wait for some other
500 program to execute a \fIsetconf/2\fR
501 The Gconf is a \fI#gconf{}\fR record and the Group variable is
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
502 a list of lists of \fI#sconf{}\fR records. Each sublist must
50a7ab2 @klacke added support/docs for embedded mode
authored
503 contain \fI#sconf{}\fR records with the same IP/Port listen address.
e263363 @klacke speling
authored
504 To create a suitable initial #gconf{} record see the code in
505 yaws_config:make_default_gconf/2. Especially the \fIyaws_dir\fR parameter
506 is important to get right.
abc3a43 @klacke documented yaws_api
authored
507
2b9f008 @klacke ""
authored
508
509 .TP
510 \fBurl_decode(Str)\fR
e263363 @klacke speling
authored
511 Decode url-encoded string. A URL encoded string is a string where
2b9f008 @klacke ""
authored
512 all alfa numeric characters and the the character _ are preserved
513 and all other characters are encode as "%XY" where X and Y are the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
514 hex values of the least respective most significant 4 bits in the 8 bit
2b9f008 @klacke ""
authored
515 character.
516
517 .TP
518 \fBurl_encode(Str)\fR
519 Url-encodes a string. All URLs in HTML documents must be URL encoded.
520
5b34d48 @vinoski wrap SSL sockets in tuple
vinoski authored
521 .TP
522 \fBget_sslsocket(Socket)\fR
523 Returns a socket for SSL sockets or the atom \fIundefined\fR for non-SSL
524 sockets. Useful for applications that have to deal with both SSL and
525 non-SSL sockets.
2b9f008 @klacke ""
authored
526
814eb04 @klacke ""
authored
527 .TP
8d5aa60 @klacke ""
authored
528 \fBreformat_header(H)\fR
8dd9f23 @vinoski add doc for new functions for manipulating #headers{} records
vinoski authored
529 Returns a list of reformatted header values from a #headers{}
814eb04 @klacke ""
authored
530 record. The return list is suitable for retransmit.
531
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id suppo...
authored
532 .TP
b415950 @vinoski document the new yaws_api:reformat_header/2 function
vinoski authored
533 \fBreformat_header(H, FormatFun)\fR
534 Returns a list of reformatted header values from a #headers{} record, with
535 each element of the list formatted via a call to \fIFormatFun\fR. This
536 enables converting #headers{} records into various lists of headers and
537 their values.
538
539 .TP
8dd9f23 @vinoski add doc for new functions for manipulating #headers{} records
vinoski authored
540 \fBset_header(Headers, {Header, Value})\fR
541 Sets header \fIHeader\fR with value \fIValue\fR in the #headers{} record
542 \fIHeaders\fR, and returns a new #headers{} record. Using the atom
543 \fIundefined\fR for \fIValue\fR effectively deletes the header, same as
544 \fIdelete_header/2\fR.
545
546 .TP
547 \fBset_header(Headers, Header, Value)\fR
548 Sets header \fIHeader\fR with value \fIValue\fR in the #headers{} record
549 \fIHeaders\fR, and returns a new #headers{} record. Using the atom
550 \fIundefined\fR for \fIValue\fR effectively deletes the header, same as
551 \fIdelete_header/2\fR.
552
553 .TP
554 \fBget_header(Headers, Header)\fR
555 Gets the value of header \fIHeader\fR from the #headers{} record
556 \fIHeaders\fR and returns it. If the header isn't set, the atom
557 \fIundefined\fR is returned.
558
559 .TP
560 \fBdelete_header(Headers, Header)\fR
561 Deletes any value set for header \fIHeader\fR in the #headers{} record
562 \fIHeaders\fR, and returns a new #headers{} record.
563
564 .TP
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id suppo...
authored
565 \fBrequest_url(ARG)\fR
566 Return the url as requested by the client. Return value
567 is a #url{} record as defined in yaws_api.hrl
568
2b9f008 @klacke ""
authored
569
8da2b3a @klacke parse_url
authored
570 .TP
571 \fBparse_url(Str)\fR
572 Parse URL in a string, returns a #url record
573
574 .TP
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
575 \fBformat_url(UrlRecord)\fR
8da2b3a @klacke parse_url
authored
576 Takes a #url record a formats the Url as a string
577
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
578 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
579 \fBcall_cgi(Arg, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
580 Calls an executable CGI script,
581 given by its full path. Used to make `.yaws' wrappers for CGI
582 programs. This function usually returns \fIstreamcontent\fR.
583
584 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
585 \fBcall_cgi(Arg, Exefilename, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
586 Like before, but
587 calls \fIExefilename\fR to handle the script. The file name of the
588 script is handed to the executable via a CGI meta variable.
8da2b3a @klacke parse_url
authored
589
f3deff2 @klacke added a dir_listing function in yaws_api
authored
590 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
591 \fBcall_fcgi_responder(Arg)\fR
2fa66b0 @klacke cgi support
authored
592 Calls a FastCGI responder.
593 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
594 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored
595 Used to make `.yaws' wrappers for FastCGI responders.
596 Returns the same return values as out/1 (see below).
597
598 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
599 \fBcall_fcgi_responder(Arg, Options)\fR
2fa66b0 @klacke cgi support
authored
600 Same as above, but Options overrides the defaults from the server
601 configuration:
602
603 \fI
604 .nf
605 Options = [Option]
606 Option -- one of the following:
607 .fi
608 \fR
609
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
610 \fB{app_server_host, string() | ip_address()}\fR
2fa66b0 @klacke cgi support
authored
611 The hostname or the IP address of the FastCGI application server.
612
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
613 \fB{app_server_port, 0..65535}\fR
2fa66b0 @klacke cgi support
authored
614 The TCP port number of the FastCGI application server.
615
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
616 \fB{path_info, string()}\fR
2fa66b0 @klacke cgi support
authored
617 Override default pathinfo in Arg#arg.pathinfo.
618
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
619 \fB{extra_env, ExtraEnv}\fR
2fa66b0 @klacke cgi support
authored
620 Override default pathinfo in Arg#arg.pathinfo.
621
622 \fI
623 .nf
624 ExtraEnv = [Var]
625 Var = {Name, Value}
626 Name = string()
627 Value = string()
628 .fi
629 \fR
630
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
631 \fB{trace_protocol, boolean()}\fR
2fa66b0 @klacke cgi support
authored
632 Enable or disable tracing of FastCGI protocol messages as info
633 log messages.
634
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
635 \fB{log_app_error, boolean()}\fR
2fa66b0 @klacke cgi support
authored
636 Enable or disable logging of application error messages: output
637 to stderr and non-zero exit value.
638
639 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up indentat...
vinoski authored
640 \fBcall_fcgi_authorizer(Arg) -> {allowed, Out} | {denied, Out}\fR
2fa66b0 @klacke cgi support
authored
641 Calls a FastCGI authorizer.
642 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
643 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored
644 Used to make `.yaws' wrappers for FastCGI authorizers.
645 Variables contains the values of the variables returned by the FastCGI
646 application server in the "Variable-XXX: YYY" headers.
647
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up indentat...
vinoski authored
648 If access is denied, Out contains the complete response returned by
649 the FastCGI application server. This response is typically returned
650 as-is to the HTTP client.
651
652 If access is allowed, Out contains the response returned by the
653 FastCGI application server minus the body (i.e. minus the content)
654 which should be ignored per the FastCGI specification. This response
655 is typically not returned to the HTTP client. The calling application
656 module may wish to inspect the response, for example by extracting
657 variables (see fcgi_extract_variables below) or by inspecting the
658 headers returned by the FastCGI application server.
659
2fa66b0 @klacke cgi support
authored
660 \fI
661 .nf
662 Out -- See return values for out/1 below
663 .fi
664 \fR
665
666 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up indentat...
vinoski authored
667 \fBcall_fcgi_authorizer(Arg, Options) -> {allowed, Out} | {denied, Out}\fR
2fa66b0 @klacke cgi support
authored
668 Same as above, but Options overrides the defaults from the server
669 configuration. See call_fcgi_responder/2 above for a description
670 of Options.
671
672 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up indentat...
vinoski authored
673 \fBfcgi_extract_variables(Out) -> [{Name, Value}]\fR
674 Extracts the environment variables from a FastCGI authorizer response
675 by looking for headers of the form "Variable-Name: Value".
676
677 \fI
678 .nf
679 Name = string() -- The name of the variable (the "Variable-" prefix
680 has already been removed).
681 Value = string() -- The value of the variable.
682 .fi
683 \fR
684
685 .TP
f3deff2 @klacke added a dir_listing function in yaws_api
authored
686 \fBdir_listing(Arg)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
687 Perform a directory listing. Can be used in special directories
f3deff2 @klacke added a dir_listing function in yaws_api
authored
688 when we don't want to turn on dir listings for the entire server.
689 Always returns ok.
8da2b3a @klacke parse_url
authored
690
abc3a43 @klacke documented yaws_api
authored
691 .SH RETURN VALUES from out/1
692 .PP
693 The out/1 function can return different values to control the behavior
694 of the server.
695
696 .TP
697 \fB{html, DeepList}\fB
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
698 This assumes that DeepList is formatted HTML code.
abc3a43 @klacke documented yaws_api
authored
699 The code will be inserted in the page.
700
701 .TP
04970fa exhtml cleanup
Claes Wikstrom authored
702 \fB{ehtml|exhtml, Term}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
703 This will transform the erlang term Term into a
89a64ef Make the mime types mappings configurable
Christopher Faulet authored
704 stream of HTML content. The exhtml variant transforms into
04970fa exhtml cleanup
Claes Wikstrom authored
705 strict XHTML code. The basic syntax of Term
abc3a43 @klacke documented yaws_api
authored
706 is
707
708 \fI
709 .nf
710 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
711 binary() | character()
8d5aa60 @klacke ""
authored
712 Tag = atom()
abc3a43 @klacke documented yaws_api
authored
713 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored
714 Key = atom()
abc3a43 @klacke documented yaws_api
authored
715 Value = string()
716 Body = EHTML
717 .fi
718 \fR
719
720
ebb94d8 @klacke 1.54
authored
721 For example, \fI{p, [], "Howdy"}\fR expands into
3dee1a5 Update documentation and manpages accordingly
Christopher Faulet authored
722 "<p>Howdy</p>" and
abc3a43 @klacke documented yaws_api
authored
723
724 \fI
725 .nf
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
726 {form, [{action, "a.yaws"}],
abc3a43 @klacke documented yaws_api
authored
727 {input, [{type,text}]}}
728
729 .fi
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
730 \fR
abc3a43 @klacke documented yaws_api
authored
731
732 expands into
733
734 \fI
735 .nf
736 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
737 <input type="text">
738 </form>
abc3a43 @klacke documented yaws_api
authored
739 .fi
740 \fR
741
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
742 It may be more convenient to generate erlang tuples
abc3a43 @klacke documented yaws_api
authored
743 than plain html code.
744
745 .TP
746 \fB{content, MimeType, Content}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
747 This function will make the web server generate
abc3a43 @klacke documented yaws_api
authored
748 different content than HTML. This return value is only allowed
749 in a yaws file which has only one <erl> </erl> part and no
750 html parts at all.
751
752
753 .TP
754 \fB{streamcontent, MimeType, FirstChunk}\fR
755 This return value plays the same role as the \fIcontent\fR return
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
756 value above.
e2f272a @klacke explicit support for content_length
authored
757
abc3a43 @klacke documented yaws_api
authored
758 However it makes it possible to stream data to the client
759 if the yaws code doesn't have access to all the data in one go. (Typically
760 if a file is very large or if data arrives from back end servers on the network.
761
762 .TP
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
763 \fB{streamcontent_with_timeout, MimeType, FirstChunk, Timeout}\fR
404aec1 @sgolovan fix syntax and spelling errors in man pages
sgolovan authored
764 Similar to above, but with an explicit timeout. The default timeout
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
765 is 30 secs. I.e if the application fails to deliver data to the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
766 Yaws process, the streaming will stop. This is often not the
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
767 desired behaviour in Comet/Ajax applications. It's possible to
768 provide 'infinity' as timeout.
769
770 .TP
3dee1a5 Update documentation and manpages accordingly
Christopher Faulet authored
771 \fB{streamcontent_from_pid, MimeType, Pid}\fR
772 This return value is similar to the \fIstreamcontent\fR return value above.
773
774 However it makes it possible to stream data to the client directly from an
775 application process to the socket. This approach can be useful for applications
776 that employ long-polling (Comet) techniques, for example, and for applications
777 wanting to avoid buffering data or avoid HTTP chunked mode transfer for streamed
778 data.
779
780 .TP
781 \fB{streamcontent_with_size, Sz, MimeType, FirstChunk}\fR
782 This return value is similar to the \fIstreamcontent\fR return value above.
783
784 However it makes it possible to stream data to the client by setting the content
785 length of the response. As the opposite of other ways to stream data, in this
786 case, the response is not chunked encoded.
787
788
789 .TP
abc3a43 @klacke documented yaws_api
authored
790 \fB{header, H}\fR
e2f272a @klacke explicit support for content_length
authored
791 Accumulates a HTTP header. The trailing CRNL which is supposed
ebb94d8 @klacke 1.54
authored
792 to end all HTTP headers must NOT be added. It is added by the server.
e2f272a @klacke explicit support for content_length
authored
793 The following list of headers are given special treatment.
794
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
795 \fI{connection, What}\fR
e2f272a @klacke explicit support for content_length
authored
796
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
797 This sets the Connection: header. If \fIWhat\fR is the special value
e2f272a @klacke explicit support for content_length
authored
798 \fI"close"\fR, the connection will be closed once the yaws page is delivered
799 to the client.
800
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
801 \fI{server, What}\fR
802
803 Sets the Server: header. By setting this header, the server's signature will be
804 dynamically overloaded.
805
e2f272a @klacke explicit support for content_length
authored
806 \fI{location, Url}\fR
807
808 Sets the Location: header. This header is typically combined with
809 the \fI{status, 302}\fR return value.
810
811 \fI{cache_control, What}\fR
812
813 Sets the Cache-Control: header.
814
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
815 \fI{expires, What}\fR
816
817 Sets the Expires: header.
818
819 \fI{date, What}\fR
820
821 Sets the Date: header.
822
823 \fI{allow, What}\fR
824
825 Sets the Allow: header.
826
827 \fI{last_modified, What}\fR
828
829 Sets the Last-Modified: header.
830
831 \fI{etag, What}\fR
832
833 Sets the Etag: header.
834
e2f272a @klacke explicit support for content_length
authored
835 \fI{set_cookie, Cookie}\fR
836
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
837 Prepends a Set-Cookie: header to the list of previously
e2f272a @klacke explicit support for content_length
authored
838 set Set-Cookie: headers.
839
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
840 \fI{content_range, What}\fR
841
842 Sets the Content-Range: header.
843
e2f272a @klacke explicit support for content_length
authored
844 \fI{content_type, MimeType}\fR
845
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
846 Sets the Content-Type: header.
847
848 \fI{content_encoding, What}\fR
849
850 Sets the Content-Encoding: header. If this header is defined, no deflate is
851 performed by Yaws. So you can compress data by yourself.
e2f272a @klacke explicit support for content_length
authored
852
853 \fI{content_length, Len}\fR
854
855 Normally yaws will ship Yaws pages using Transfer-Encoding: chunked. This
856 is because we generally can't know how long a yaws page will be. If we for
857 some reason want to force a Content-Length: header (and we actually do
858 know the length of the content, we can force yaws to not ship the
859 page chunked.
860
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
861 \fI{transfer_encoding, What}\fR
e2f272a @klacke explicit support for content_length
authored
862
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
863 Sets the Transfer-Encoding: header.
864
865 \fI{www_authenticate, What}\fR
866
867 Sets the WWW-Authenticate: header.
e2f272a @klacke explicit support for content_length
authored
868
869
e61b0e3 Manage all 'special' headers of #headers{} and #outh{} records
Christopher Faulet authored
870 All other headers must be added using the normal HTTP syntax.
871 Example:
e2f272a @klacke explicit support for content_length
authored
872
8dd9f23 @vinoski add doc for new functions for manipulating #headers{} records
vinoski authored
873 \fI{header, {"My-X-Header", "gadong"}}\fR or \fI{header, "My-X-Header: gadong"}\fR
e2f272a @klacke explicit support for content_length
authored
874
8dd9f23 @vinoski add doc for new functions for manipulating #headers{} records
vinoski authored
875 .TP
876 \fB{header, {HeaderName, erase}}\fR
877 Clears the header named \fIHeaderName\fR from the accumulated headers.
abc3a43 @klacke documented yaws_api
authored
878
879 .TP
8dd9f23 @vinoski add doc for new functions for manipulating #headers{} records
vinoski authored
880 \fB{allheaders, HeaderList}\fR
abc3a43 @klacke documented yaws_api
authored
881 Will clear all previously accumulated headers and replace them.
882
883
884 .TP
885 \fB{status, Code}\fR
886 Will set another HTTP status code than 200.
887
888
889 .TP
890 \fBbreak\fR
891 Will stop processing of any consecutive chunks of erl or html code
892 in the yaws file.
893
894 .TP
895 \fBok\fR
896 Do nothing.
897
f163227 Fix issue #88
Christopher Faulet authored
898 .TP
899 \fBflush\fR
900 Flush remaining data sent by the client.
901
abc3a43 @klacke documented yaws_api
authored
902
903 .TP
904 \fB{redirect, Url}\fR
905 Erase all previous headers and accumulate a single
906 Location header. Set the status code.
907
908 .TP
909 \fB{redirect_local, Path}\fR
910 Does a redirect to the same Scheme://Host:Port/Path as we
911 currently are executing in.
912
913 .TP
914 \fB{get_more, Cont, State}\fR
915 When we are receiving large POSTs we can return this value
916 and be invoked again when more Data arrives.
917
918
919 .TP
c837288 @klacke page retval
authored
920 \fB{page, Page}\fR
921 Make Yaws return a different page than the one being
922 requested.
923
924
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
925 .TP
926 \fB{page, {Options, Page}}\fR
927 Like the above, but supplying an additional deep list of options. For
928 now, the only type of option is \fI{header, H}\fR with the effect of
929 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
930
c837288 @klacke page retval
authored
931
932 .TP
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
933 \fB{ssi, File, Delimiter, Bindings}\fR
934 Server side include File and macro expansion in File.
e263363 @klacke speling
authored
935 Each occurrence of a string, say "xyz", inside File which
936 is inside Delimiters is replaced with the corresponding
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
937 value in Bindings.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
938
939 Example:
940 Delimiter = %%
941
942 File contains the string .... %%xyz%% .....
943
944 Bindings contain the tuple {"xyz", "Dingbat"}
945
e263363 @klacke speling
authored
946 The occurrence of %%xyz%% in File will be replaced with "Dingbat"
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
947 in the Server side included output.
948
949 The {ssi, File, Delimiter, Bindings} statement can also
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
950 occur inside a deep ehtml structure.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
951
952
953 .TP
379666b @klacke documented jockes new bindings feature
authored
954 \fB{bindings, [{Key1, Value2}, {Key2, Value2} .....]}\fR
955 Establish variable bindings that can be used in the page.
956
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
957 All bindings can then be used in the rest of yaws code
958 (in HTML source and within erl tags).
959 In HTML source %%Key%% is expanded to Value and within erl
ab5edc6 @klacke *** empty log message ***
authored
960 tags \fIyaws_api:binding(Key)\fR can be used to extract Value
961 and \fIyaws_api:binding_exists(Key)\fR can be used to check for
e263363 @klacke speling
authored
962 the existence of a binding.
df96b15 @klacke New feature yssi, yaws include
authored
963
964 .TP
965 \fB{yssi, YawsFile}\fR
966 Include a yaws file. Compile it and expand as if it had
967 occured inline.
968
379666b @klacke documented jockes new bindings feature
authored
969 .TP
abc3a43 @klacke documented yaws_api
authored
970 \fB[ListOfValues]\fR
3dee1a5 Update documentation and manpages accordingly
Christopher Faulet authored
971 It is possible to return a deep list of the above defined return values. Any
972 occurrence of \fIstreamcontent\fR, \fIstreamcontent_with_timeout\fR,
973 \fIstreamcontent_with_size\fR, \fIstreamcontent_from_pid\fR, \fIget_more\fR,
974 \fIpage\fR or \fIbreak\fR in this list is legal only if it is the last position
975 of the list. If not, remaining values in the list are ignored.
abc3a43 @klacke documented yaws_api
authored
976
977
978
979
980 .SH AUTHOR
981 Written by Claes Wikstrom
982 .SH "SEE ALSO"
983 .BR yaws.conf (5)
984 .BR erl (1)
985
Something went wrong with that request. Please try again.