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