Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 709 lines (541 sloc) 19.151 kb
108bbc9 @klacke ""
authored
1 .TH YAWS_API "5" "" "" "User API"
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
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, {
0be3c7e @klacke untabified all of yaws
authored
46 clisock, %% the socket leading to the peer client
930a943 @klacke doc fixes
authored
47 client_ip_port, %% {ClientIp, ClientPort} tuple
0be3c7e @klacke untabified all of yaws
authored
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 querydata, %% Was the URL on the form of ...?query (GET reqs)
53 appmoddata, %% the remainder of the path up to the query
54 docroot, %% where's the data
55 fullpath, %% full path to yaws file
56 cont, %% Continuation for chunked multipart uploads
57 state, %% State for use by users of the out/1 callback
58 pid, %% pid of the yaws worker process
59 opaque, %% useful to pass static data
60 appmod_prepath, %% path in front of: <appmod><appmoddata>
61 pathinfo %% Set to 'd/e' when calling c.yaws for the request
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
62 %% http://some.host/a/b/c.yaws/d/e
0be3c7e @klacke untabified all of yaws
authored
63 }).
abc3a43 @klacke documented yaws_api
authored
64 .fi
65 \fR
66
67 The headers argument is also a record:
68 \fI
69 .nf
8d5aa60 @klacke ""
authored
70
abc3a43 @klacke documented yaws_api
authored
71 -record(headers, {
8d5aa60 @klacke ""
authored
72 connection,
73 accept,
74 host,
75 if_modified_since,
76 if_match,
77 if_none_match,
78 if_range,
79 if_unmodified_since,
80 range,
81 referer,
82 user_agent,
83 accept_ranges,
84 cookie = [],
85 keep_alive,
86 content_length,
87 authorization,
88 other = [] %% misc other headers
89 }).
abc3a43 @klacke documented yaws_api
authored
90
91 .fi
92 \fR
93
94 .PP The \fBout/1\fR function can use the Arg to generate any content
95 it likes. We have the following functions to aid that generation.
96
97
98 .SH API
99
100 .TP
101 \fBssi(DocRoot, ListOfFiles)\fR
102 Server side include. Just include the files as is in the document. The files
103 will \fBnot\fR be parsed and searched for <erl> tags.
104
105
106 .TP
107 \fBpre_ssi_files(DocRoot, ListOfFiles) ->
108 Server side include of pre indented code. The data in Files
109 will be included but contained in a <pre> tag. The data will be
110 htmlized.
111
112 .TP
113 \fBpre_ssi_string(String)\fR
114 Include htmlized content from String.
115
116
117 .TP
118 \fBf(Fmt, Args)\fR
119 The equivalent of io_lib:format/2. This function is automatically
120 -included in all erlang code which is a part of a yaws page.
121
122 .TP
c5ebd38 @klacke added pam support + prepare for 1.58
authored
123 \fBhtmlize(Binary | List | Char)\fR
124 Htmlize an IO list object.
abc3a43 @klacke documented yaws_api
authored
125
126 .TP
127 \fBsetcookie(Name, Value, [Path, [ Expire, [Domain , [Secure]]]])\fR
128 Sets a cookie to the browser.
129
130 .TP
131 \fBfind_cookie_val(Cookie, Header)\fR
132 This function can be used to search for a cookie that was previously
133 set by \fBsetcookie/2-6\fR. For example if we set a cookie
134 as \fByaws_api:setcookie("sid",SomeRandomSid) \fR, then on subsequent requests
135 from the browser we can call:
136 \fBfind_cookie("sid",(Arg#arg.headers)#headers.cookie)\fR
137
138 The function returns [] if no cookie was found, otherwise the actual cookie
139 is returned as a string.
140
141
142 .TP
143 \fBredirect(Url\fR
144 This function generates a redirect to the browser.
145 It will clear any previously set headers. So to generate
146 a redirect \fBand\fR set a cookie, we need to set the cookie after
147 the redirect as in:
148 \fI
149 .nf
150 out(Arg) ->
151 ... do some stuff
152
153 Ret = [{redirect, "http://www.somewhere.com"},
154 setcookie("sid", Random)
155 ].
156
157 .fi
158 \fR
159
160
161 .TP
883fa5a @klacke added redirect_self to yaws_api
authored
162 \fBredirect_self(Arg)\fR
163 If we want to issue a redirect to ourselves, this function
164 is useful. It returns a record \fI#redir_self{}\fR defined in
165 \fIyaws_api.hrl\fR. The record contains fields to construct
166 a URL to ourselves.
167 \fI
168 .nf
169
170 -record(redir_self, {
171 host, %% string() - our own host
172 scheme, %% http | https
173 scheme_str, %% "https://" | "http://"
174 port, %% integer() - our own port
175 port_str %% "" | ":<int>" - the optional port part
176 %% to append to the url
177 }).
178 .nf
179
180
181 .TP
abc3a43 @klacke documented yaws_api
authored
182 \fBget_line(String)\fR
d02b965 @klacke qnx port + docs overhaul by cschatz@networkadvantage.biz
authored
183 This function is convenient when getting \\r\\n terminated lines
abc3a43 @klacke documented yaws_api
authored
184 from a stream of data. It returns:
185
186 \fB{line, Line, Tail}\fR or \fB{lastline, Line, Tail}\fR
187
188 The function handles multilines as defined in e.g. SMTP or HTTP
189
190 .TP
191 \fBmime_type(FileName)\fR
192 Returns the mime type as defined by the extension of FileName
193
194 .TP
195 \fBstream_chunk_deliver(YawsPid, Data)\fR
196 When a yaws function needs to deliver chunks of data which it gets
197 from a process. The other process can call this function to deliver
198 these chunks. It requires the \fBout/1\fR function to return the
199 value \fB{streamcontent, MimeType, FirstChunk}\fR to work.
a39fab8 @klacke added example docs on how to stream data
authored
200 YawsPid is the process identifier of the yaws process delivering the original
ebb94d8 @klacke 1.54
authored
201 .yaws file. That is self() in the yaws code.
202 The Pid must typically be passed (somehow) to the producer of the stream.
abc3a43 @klacke documented yaws_api
authored
203
a39fab8 @klacke added example docs on how to stream data
authored
204 .TP
205 \fBstream_chunk_deliver_blocking(YawsPid, Data)\fR
e263363 @klacke speling
authored
206 A synchronous version of the above function. This syncronous version must always
ebb94d8 @klacke 1.54
authored
207 be used when the producer of the stream is faster than the consumer.
208 This is usually the case since the client is the WWW browser.
abc3a43 @klacke documented yaws_api
authored
209
210 .TP
211 \fBstream_chunk_end(YawsPid)\fR
212 When the process discussed above is done delivering data, it must call
213 this function to let the yaws content delivering process finish up
214 the HTTP transaction.
215
216 .TP
217 \fBparse_query(Arg)\fR
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
218 This function will parse the query part of the URL.
abc3a43 @klacke documented yaws_api
authored
219 It will return a {Key, Value} list of the items supplied in the query
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
220 part of the URL.
221
222 .TP
223 \fBqueryvar(Arg, VarName)\fR
224 This function is automatically included from yaws_api in all
225 .yaws pages. It is used to search for a variable in the
226 querypart of the url. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk/ya...
authored
227 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
228 return \fI{Val1, ....}\fR.
abc3a43 @klacke documented yaws_api
authored
229
230
231 .TP
c4523b3 @klacke ""
authored
232 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
233 This function will parse the POST data as supplied from the browser.
234 It will return a {Key, Value} list of the items set by the browser.
235
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
236 .TP
237 \fBpostvar(Arg, VarName)\fR
238 This function is automatically included from yaws_api in all
239 .yaws pages. It is used to search for a variable in the
240 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
241 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
242 return \fI{Val1, ....}\fR.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
243
c9778e0 @klacke added support for 2 additional configure
authored
244 .TP
245 \fBgetvar(Arg, VarName)\fR
246 This function looks at the HTTP request method from the
247 client and invokes postvar/2 if it is a POST from the client
248 and queryvar/2 if it is a GET request from the client.
249
c4523b3 @klacke ""
authored
250
251 .TP
252 \fBparse_multipart_post(Arg)\fR
253
abc3a43 @klacke documented yaws_api
authored
254 If the browser has set the Content-Type header to the value
255 "multipart/form-data", which is the case when the browser
256 wants to upload a file to the server the following happens:
257
258
259 If the function returns \fB{result, Res}\fR no more data
260 will come from the browser.
261
262 If the function returns \fB{cont, Cont, Res}\fR the browser
263 will supply more data. (The file was to big to come in one read)
264
265 This indicates that there is more data to come and the out/1 function
266 should return {get_more, Cont, User_state} where User_state might
267 usefully be a File Descriptor.
268
269
270 The Res value is a list of either:
271 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
272
273
274 Example usage could be:
275 \fI
276 .nf
277 <erl>
278
279 out(A) ->
c4523b3 @klacke ""
authored
280 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
281 {cont, Cont, Res} ->
282 St = handle_res(A, Res),
283 {get_more, Cont, St};
284 {result, Res} ->
285 handle_res(A, Res),
286 {html, f("<pre>Done </pre>",[])}
287 end.
288
289 handle_res(A, [{head, Name}|T]) ->
290 io:format("head:~p~n",[Name]),
291 handle_res(A, T);
292 handle_res(A, [{part_body, Data}|T]) ->
293 io:format("part_body:~p~n",[Data]),
294 handle_res(A, T);
295 handle_res(A, [{body, Data}|T]) ->
296 io:format("body:~p~n",[Data]),
297 handle_res(A, T);
298 handle_res(A, []) ->
299 io:format("End_res~n").
300
301 </erl>
302 .fi
303 \fR
304
305
306
307 .TP
87b1456 @klacke wrote the shopppingcart example
authored
308 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
309 Create a new cookie based session, the yaws system will set the
e263363 @klacke speling
authored
310 cookie. The new random generated cookie is returned from this
87b1456 @klacke wrote the shopppingcart example
authored
311 function. The Opaque argument will typically contain user data
e263363 @klacke speling
authored
312 such as user name and password
abc3a43 @klacke documented yaws_api
authored
313
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
314 .TP
315 \fBnew_cookie_session(Opaque, TTL)\fR
316 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
317 overriding the system specified time-out value.
318
319 .TP
320 \fBnew_cookie_session(Opaque, TTL, CleanupPid)\fR
e263363 @klacke speling
authored
321 As above, but also sends a message
6964fff @klacke modified patch by Robert David to add a hook to yaws session server when...
authored
322 \fI{yaws_session_end, Reason, Cookie, Opaque}\fR to the provided CleanuPid where
323 Reason can be either of \fItimeout\fR or \fInormal\fR. The \fICookie\fR
324 is the HTTP cookie as returned by \fInew_session()\fR and the Opaque
325 is the user provided Opaque parameter to \fInew_session()\fR.
326 The purpose of the feature is to cleanup resources assigned to the session.
327
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
328
abc3a43 @klacke documented yaws_api
authored
329 .TP
87b1456 @klacke wrote the shopppingcart example
authored
330 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
331
332 .TP
333 \fBprint_cookie_sessions() \fR
334
87b1456 @klacke wrote the shopppingcart example
authored
335
336 .TP
337 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
338
abc3a43 @klacke documented yaws_api
authored
339 .TP
87b1456 @klacke wrote the shopppingcart example
authored
340 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
341
342
50a7ab2 @klacke added support/docs for embedded mode
authored
343 .TP
344 \fBsetconf(Gconf, Groups)\fR
345 This function is intended for embedded mode in yaws. It makes it possible
346 to load a yaws configuration from another data source than /etc/yaws.conf, such
347 as a database.
348 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
349 start with an empty default configuration, and wait for some other
350 program to execute a \fIsetconf/2\fR
351 The Gconf is a \fI#gconf{}\fR record and the Group variable is
352 a list of lists of \fI#sconf{}\fR records. Each sublist must
353 contain \fI#sconf{}\fR records with the same IP/Port listen address.
e263363 @klacke speling
authored
354 To create a suitable initial #gconf{} record see the code in
355 yaws_config:make_default_gconf/2. Especially the \fIyaws_dir\fR parameter
356 is important to get right.
abc3a43 @klacke documented yaws_api
authored
357
2b9f008 @klacke ""
authored
358
359 .TP
360 \fBurl_decode(Str)\fR
e263363 @klacke speling
authored
361 Decode url-encoded string. A URL encoded string is a string where
2b9f008 @klacke ""
authored
362 all alfa numeric characters and the the character _ are preserved
363 and all other characters are encode as "%XY" where X and Y are the
e263363 @klacke speling
authored
364 hex values of the least respective most significant 4 bits in the 8 bit
2b9f008 @klacke ""
authored
365 character.
366
367 .TP
368 \fBurl_encode(Str)\fR
369 Url-encodes a string. All URLs in HTML documents must be URL encoded.
370
371
814eb04 @klacke ""
authored
372 .TP
8d5aa60 @klacke ""
authored
373 \fBreformat_header(H)\fR
e263363 @klacke speling
authored
374 Returns a list of reformatted header values from a #header{}
814eb04 @klacke ""
authored
375 record. The return list is suitable for retransmit.
376
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id suppo...
authored
377 .TP
378 \fBrequest_url(ARG)\fR
379 Return the url as requested by the client. Return value
380 is a #url{} record as defined in yaws_api.hrl
381
2b9f008 @klacke ""
authored
382
8da2b3a @klacke parse_url
authored
383 .TP
384 \fBparse_url(Str)\fR
385 Parse URL in a string, returns a #url record
386
387 .TP
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
388 \fBformat_url(UrlRecord)\fR
8da2b3a @klacke parse_url
authored
389 Takes a #url record a formats the Url as a string
390
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
391 .TP
392 \fBcall_cgi(Arg, Scriptfilename)\fR
393 Calls an executable CGI script,
394 given by its full path. Used to make `.yaws' wrappers for CGI
395 programs. This function usually returns \fIstreamcontent\fR.
396
397 .TP
398 \fBcall_cgi(Arg, Exefilename, Scriptfilename)\fR
399 Like before, but
400 calls \fIExefilename\fR to handle the script. The file name of the
401 script is handed to the executable via a CGI meta variable.
8da2b3a @klacke parse_url
authored
402
f3deff2 @klacke added a dir_listing function in yaws_api
authored
403 .TP
2fa66b0 @klacke cgi support
authored
404 \fBcall_fcgi_responder(Arg)\fR
405 Calls a FastCGI responder.
406 The address and port of the FastCGI application server are taken
407 from the server configuration (see yaws.conf).
408 Used to make `.yaws' wrappers for FastCGI responders.
409 Returns the same return values as out/1 (see below).
410
411 .TP
412 \fBcall_fcgi_responder(Arg, Options)\fR
413 Same as above, but Options overrides the defaults from the server
414 configuration:
415
416 \fI
417 .nf
418 Options = [Option]
419 Option -- one of the following:
420 .fi
421 \fR
422
423 \fB{app_server_host, string() | ip_address()}\fR
424 The hostname or the IP address of the FastCGI application server.
425
426 \fB{app_server_port, 0..65535}\fR
427 The TCP port number of the FastCGI application server.
428
429 \fB{path_info, string()}\fR
430 Override default pathinfo in Arg#arg.pathinfo.
431
432 \fB{extra_env, ExtraEnv}\fR
433 Override default pathinfo in Arg#arg.pathinfo.
434
435 \fI
436 .nf
437 ExtraEnv = [Var]
438 Var = {Name, Value}
439 Name = string()
440 Value = string()
441 .fi
442 \fR
443
444 \fB{trace_protocol, boolean()}\fR
445 Enable or disable tracing of FastCGI protocol messages as info
446 log messages.
447
448 \fB{log_app_error, boolean()}\fR
449 Enable or disable logging of application error messages: output
450 to stderr and non-zero exit value.
451
452 .TP
453 \fBcall_fcgi_authorizer(Arg) -> {allowed, Variables} | {denied, Out}\fR
454 Calls a FastCGI authorizer.
455 The address and port of the FastCGI application server are taken
456 from the server configuration (see yaws.conf).
457 Used to make `.yaws' wrappers for FastCGI authorizers.
458 Variables contains the values of the variables returned by the FastCGI
459 application server in the "Variable-XXX: YYY" headers.
460
461 \fI
462 .nf
463 Out -- See return values for out/1 below
464 Variables = {Name, Value}
465 Name = string()
466 Value = string()
467 .fi
468 \fR
469
470 .TP
471 \fBcall_fcgi_authorizer(Arg, Options)\fR
472 Same as above, but Options overrides the defaults from the server
473 configuration. See call_fcgi_responder/2 above for a description
474 of Options.
475
476 .TP
f3deff2 @klacke added a dir_listing function in yaws_api
authored
477 \fBdir_listing(Arg)\fR
478 Perform a directory listing. Can be used in special directories
479 when we don't want to turn on dir listings for the entire server.
480 Always returns ok.
8da2b3a @klacke parse_url
authored
481
abc3a43 @klacke documented yaws_api
authored
482 .SH RETURN VALUES from out/1
483 .PP
484 The out/1 function can return different values to control the behavior
485 of the server.
486
487 .TP
488 \fB{html, DeepList}\fB
489 This assumes that DeepList is formatted HTML code.
490 The code will be inserted in the page.
491
492 .TP
493 \fB{ehtml, Term}\fR
494 This will transform the erlang term Term into a
495 stream of HTML content. The basic syntax of Term
496 is
497
498 \fI
499 .nf
500 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
501 binary() | character()
8d5aa60 @klacke ""
authored
502 Tag = atom()
abc3a43 @klacke documented yaws_api
authored
503 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored
504 Key = atom()
abc3a43 @klacke documented yaws_api
authored
505 Value = string()
506 Body = EHTML
507 .fi
508 \fR
509
510
ebb94d8 @klacke 1.54
authored
511 For example, \fI{p, [], "Howdy"}\fR expands into
abc3a43 @klacke documented yaws_api
authored
512 "<p>Howdy</p> and
513
514 \fI
515 .nf
516 {form, [{action, "a.yaws"}],
517 {input, [{type,text}]}}
518
519 .fi
520 \fR
521
522 expands into
523
524 \fI
525 .nf
526 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
527 <input type="text">
528 </form>
abc3a43 @klacke documented yaws_api
authored
529 .fi
530 \fR
531
532 It may be more convenient to generate erlang tuples
533 than plain html code.
534
535 .TP
536 \fB{content, MimeType, Content}\fR
537 This function will make the web server generate
538 different content than HTML. This return value is only allowed
539 in a yaws file which has only one <erl> </erl> part and no
540 html parts at all.
541
542
543 .TP
544 \fB{streamcontent, MimeType, FirstChunk}\fR
545 This return value plays the same role as the \fIcontent\fR return
546 value above.
e2f272a @klacke explicit support for content_length
authored
547
abc3a43 @klacke documented yaws_api
authored
548 However it makes it possible to stream data to the client
549 if the yaws code doesn't have access to all the data in one go. (Typically
550 if a file is very large or if data arrives from back end servers on the network.
551
552 .TP
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
553 \fB{streamcontent_with_timeout, MimeType, FirstChunk, Timeout}\fR
554 Similar to above, but with an explicit timeout. The deafult timeout
555 is 30 secs. I.e if the application fails to deliver data to the
556 Yaws process, the streaming will stop. This is often not the
557 desired behaviour in Comet/Ajax applications. It's possible to
558 provide 'infinity' as timeout.
559
560 .TP
abc3a43 @klacke documented yaws_api
authored
561 \fB{header, H}\fR
e2f272a @klacke explicit support for content_length
authored
562 Accumulates a HTTP header. The trailing CRNL which is supposed
ebb94d8 @klacke 1.54
authored
563 to end all HTTP headers must NOT be added. It is added by the server.
e2f272a @klacke explicit support for content_length
authored
564 The following list of headers are given special treatment.
565
566 \fI{connection, What}\fR
567
568 This sets the connection header. If \fIWhat\fR is the special value
569 \fI"close"\fR, the connection will be closed once the yaws page is delivered
570 to the client.
571
572 \fI{location, Url}\fR
573
574 Sets the Location: header. This header is typically combined with
575 the \fI{status, 302}\fR return value.
576
577 \fI{cache_control, What}\fR
578
579 Sets the Cache-Control: header.
580
581 \fI{set_cookie, Cookie}\fR
582
e263363 @klacke speling
authored
583 Prepends a a Set-Cookie: header to the list of previously
e2f272a @klacke explicit support for content_length
authored
584 set Set-Cookie: headers.
585
586 \fI{content_type, MimeType}\fR
587
588 Sets the Content-Type header.
589
590 \fI{content_length, Len}\fR
591
592 Normally yaws will ship Yaws pages using Transfer-Encoding: chunked. This
593 is because we generally can't know how long a yaws page will be. If we for
594 some reason want to force a Content-Length: header (and we actually do
595 know the length of the content, we can force yaws to not ship the
596 page chunked.
597
598
599 All other headers must be added using the normal HTTP syntax.
600 Example:
601
602 {header, "My-X-Header: gadong"}
603
604
605
abc3a43 @klacke documented yaws_api
authored
606
607 .TP
608 \fB{allheaders, HeaderList}\fB
609 Will clear all previously accumulated headers and replace them.
610
611
612 .TP
613 \fB{status, Code}\fR
614 Will set another HTTP status code than 200.
615
616
617 .TP
618 \fBbreak\fR
619 Will stop processing of any consecutive chunks of erl or html code
620 in the yaws file.
621
622 .TP
623 \fBok\fR
624 Do nothing.
625
626
627 .TP
628 \fB{redirect, Url}\fR
629 Erase all previous headers and accumulate a single
630 Location header. Set the status code.
631
632 .TP
633 \fB{redirect_local, Path}\fR
634 Does a redirect to the same Scheme://Host:Port/Path as we
635 currently are executing in.
636
637 .TP
638 \fB{get_more, Cont, State}\fR
639 When we are receiving large POSTs we can return this value
640 and be invoked again when more Data arrives.
641
642
643 .TP
c837288 @klacke page retval
authored
644 \fB{page, Page}\fR
645 Make Yaws return a different page than the one being
646 requested.
647
648
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
649 .TP
650 \fB{page, {Options, Page}}\fR
651 Like the above, but supplying an additional deep list of options. For
652 now, the only type of option is \fI{header, H}\fR with the effect of
653 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
654
c837288 @klacke page retval
authored
655
656 .TP
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
657 \fB{ssi, File, Delimiter, Bindings}\fR
658 Server side include File and macro expansion in File.
e263363 @klacke speling
authored
659 Each occurrence of a string, say "xyz", inside File which
660 is inside Delimiters is replaced with the corresponding
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
661 value in Bindings.
662
663 Example:
664 Delimiter = %%
665
666 File contains the string .... %%xyz%% .....
667
668 Bindings contain the tuple {"xyz", "Dingbat"}
669
e263363 @klacke speling
authored
670 The occurrence of %%xyz%% in File will be replaced with "Dingbat"
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
671 in the Server side included output.
672
673 The {ssi, File, Delimiter, Bindings} statement can also
674 occur inside a deep ehtml structure.
675
676
677 .TP
379666b @klacke documented jockes new bindings feature
authored
678 \fB{bindings, [{Key1, Value2}, {Key2, Value2} .....]}\fR
679 Establish variable bindings that can be used in the page.
680
681 All bindings can then be used in the rest of yaws code
682 (in HTML source and within erl tags).
683 In HTML source %%Key%% is expanded to Value and within erl
ab5edc6 @klacke *** empty log message ***
authored
684 tags \fIyaws_api:binding(Key)\fR can be used to extract Value
685 and \fIyaws_api:binding_exists(Key)\fR can be used to check for
e263363 @klacke speling
authored
686 the existence of a binding.
df96b15 @klacke New feature yssi, yaws include
authored
687
688 .TP
689 \fB{yssi, YawsFile}\fR
690 Include a yaws file. Compile it and expand as if it had
691 occured inline.
692
379666b @klacke documented jockes new bindings feature
authored
693 .TP
abc3a43 @klacke documented yaws_api
authored
694 \fB[ListOfValues]\fR
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
695 It is possible to return a deep list of the above defined
696 return values. Any occurrence of \fIstream_content\fR, \fIget_more\fR
697 or \fIpage\fR in this list is legal only if it is the last position of
698 the list.
abc3a43 @klacke documented yaws_api
authored
699
700
701
702
703 .SH AUTHOR
704 Written by Claes Wikstrom
705 .SH "SEE ALSO"
706 .BR yaws.conf (5)
707 .BR erl (1)
708
Something went wrong with that request. Please try again.