Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 521 lines (393 sloc) 13.123 kB
abc3a43 @klacke documented yaws_api
authored
1 .TH YAWS_API "1" "" "" "User API"
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
8 .\" Add any additional description here
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, {
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 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 leading up to the querey
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
61 %% http://some.host/a/b/c.yaws/d/e
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
122 \fBhtmlize(Binary)\fR
123 Htmlize a binary object.
124
125 .TP
126 \fBhtmlize_l(DeepList)\fR
127 Htmlize any deep list of chars and binaries.
128
129 .TP
130 \fBsetcookie(Name, Value, [Path, [ Expire, [Domain , [Secure]]]])\fR
131 Sets a cookie to the browser.
132
133 .TP
134 \fBfind_cookie_val(Cookie, Header)\fR
135 This function can be used to search for a cookie that was previously
136 set by \fBsetcookie/2-6\fR. For example if we set a cookie
137 as \fByaws_api:setcookie("sid",SomeRandomSid) \fR, then on subsequent requests
138 from the browser we can call:
139 \fBfind_cookie("sid",(Arg#arg.headers)#headers.cookie)\fR
140
141 The function returns [] if no cookie was found, otherwise the actual cookie
142 is returned as a string.
143
144
145 .TP
146 \fBredirect(Url\fR
147 This function generates a redirect to the browser.
148 It will clear any previously set headers. So to generate
149 a redirect \fBand\fR set a cookie, we need to set the cookie after
150 the redirect as in:
151 \fI
152 .nf
153 out(Arg) ->
154 ... do some stuff
155
156 Ret = [{redirect, "http://www.somewhere.com"},
157 setcookie("sid", Random)
158 ].
159
160 .fi
161 \fR
162
163
164 .TP
165 \fBget_line(String)\fR
d02b965 @klacke qnx port + docs overhaul by cschatz@networkadvantage.biz
authored
166 This function is convenient when getting \\r\\n terminated lines
abc3a43 @klacke documented yaws_api
authored
167 from a stream of data. It returns:
168
169 \fB{line, Line, Tail}\fR or \fB{lastline, Line, Tail}\fR
170
171 The function handles multilines as defined in e.g. SMTP or HTTP
172
173 .TP
174 \fBmime_type(FileName)\fR
175 Returns the mime type as defined by the extension of FileName
176
177 .TP
178 \fBstream_chunk_deliver(YawsPid, Data)\fR
179 When a yaws function needs to deliver chunks of data which it gets
180 from a process. The other process can call this function to deliver
181 these chunks. It requires the \fBout/1\fR function to return the
182 value \fB{streamcontent, MimeType, FirstChunk}\fR to work.
183
184
185 .TP
186 \fBstream_chunk_end(YawsPid)\fR
187 When the process discussed above is done delivering data, it must call
188 this function to let the yaws content delivering process finish up
189 the HTTP transaction.
190
191 .TP
192 \fBparse_query(Arg)\fR
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
193 This function will parse the query part of the URL.
abc3a43 @klacke documented yaws_api
authored
194 It will return a {Key, Value} list of the items supplied in the query
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
195 part of the URL.
196
197 .TP
198 \fBqueryvar(Arg, VarName)\fR
199 This function is automatically included from yaws_api in all
200 .yaws pages. It is used to search for a variable in the
201 querypart of the url. Returns {ok, Val} or undefined.
abc3a43 @klacke documented yaws_api
authored
202
203
204 .TP
c4523b3 @klacke ""
authored
205 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
206 This function will parse the POST data as supplied from the browser.
207 It will return a {Key, Value} list of the items set by the browser.
208
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
209 .TP
210 \fBpostvar(Arg, VarName)\fR
211 This function is automatically included from yaws_api in all
212 .yaws pages. It is used to search for a variable in the
213 POSTed data from the client. Returns {ok, Val} or undefined.
214
c4523b3 @klacke ""
authored
215
216 .TP
217 \fBparse_multipart_post(Arg)\fR
218
abc3a43 @klacke documented yaws_api
authored
219 If the browser has set the Content-Type header to the value
220 "multipart/form-data", which is the case when the browser
221 wants to upload a file to the server the following happens:
222
223
224 If the function returns \fB{result, Res}\fR no more data
225 will come from the browser.
226
227 If the function returns \fB{cont, Cont, Res}\fR the browser
228 will supply more data. (The file was to big to come in one read)
229
230 This indicates that there is more data to come and the out/1 function
231 should return {get_more, Cont, User_state} where User_state might
232 usefully be a File Descriptor.
233
234
235 The Res value is a list of either:
236 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
237
238
239 Example usage could be:
240 \fI
241 .nf
242 <erl>
243
244 out(A) ->
c4523b3 @klacke ""
authored
245 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
246 {cont, Cont, Res} ->
247 St = handle_res(A, Res),
248 {get_more, Cont, St};
249 {result, Res} ->
250 handle_res(A, Res),
251 {html, f("<pre>Done </pre>",[])}
252 end.
253
254 handle_res(A, [{head, Name}|T]) ->
255 io:format("head:~p~n",[Name]),
256 handle_res(A, T);
257 handle_res(A, [{part_body, Data}|T]) ->
258 io:format("part_body:~p~n",[Data]),
259 handle_res(A, T);
260 handle_res(A, [{body, Data}|T]) ->
261 io:format("body:~p~n",[Data]),
262 handle_res(A, T);
263 handle_res(A, []) ->
264 io:format("End_res~n").
265
266 </erl>
267 .fi
268 \fR
269
270
271
272 .TP
87b1456 @klacke wrote the shopppingcart example
authored
273 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
274 Create a new cookie based session, the yaws system will set the
87b1456 @klacke wrote the shopppingcart example
authored
275 cookie. The new randomgenerated cookie is returned from this
276 function. The Opaque argument will typically contain user data
277 such as username and password
abc3a43 @klacke documented yaws_api
authored
278
279 .TP
87b1456 @klacke wrote the shopppingcart example
authored
280 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
281
282 .TP
283 \fBprint_cookie_sessions() \fR
284
87b1456 @klacke wrote the shopppingcart example
authored
285
286 .TP
287 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
288
abc3a43 @klacke documented yaws_api
authored
289 .TP
87b1456 @klacke wrote the shopppingcart example
authored
290 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
291
292
50a7ab2 @klacke added support/docs for embedded mode
authored
293 .TP
294 \fBsetconf(Gconf, Groups)\fR
295 This function is intended for embedded mode in yaws. It makes it possible
296 to load a yaws configuration from another data source than /etc/yaws.conf, such
297 as a database.
298 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
299 start with an empty default configuration, and wait for some other
300 program to execute a \fIsetconf/2\fR
301 The Gconf is a \fI#gconf{}\fR record and the Group variable is
302 a list of lists of \fI#sconf{}\fR records. Each sublist must
303 contain \fI#sconf{}\fR records with the same IP/Port listen address.
304
abc3a43 @klacke documented yaws_api
authored
305
2b9f008 @klacke ""
authored
306
307 .TP
308 \fBurl_decode(Str)\fR
309 Decode url-encoded string. A URL ncoded string is a string where
310 all alfa numeric characters and the the character _ are preserved
311 and all other characters are encode as "%XY" where X and Y are the
312 hex values of the least respective most significat 4 bits in the 8 bit
313 character.
314
315 .TP
316 \fBurl_encode(Str)\fR
317 Url-encodes a string. All URLs in HTML documents must be URL encoded.
318
319
814eb04 @klacke ""
authored
320 .TP
8d5aa60 @klacke ""
authored
321 \fBreformat_header(H)\fR
814eb04 @klacke ""
authored
322 Returns a list of reformated header values from a #header{}
323 record. The return list is suitable for retransmit.
324
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored
325 .TP
326 \fBrequest_url(ARG)\fR
327 Return the url as requested by the client. Return value
328 is a #url{} record as defined in yaws_api.hrl
329
2b9f008 @klacke ""
authored
330
8da2b3a @klacke parse_url
authored
331 .TP
332 \fBparse_url(Str)\fR
333 Parse URL in a string, returns a #url record
334
335 .TP
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
336 \fBformat_url(UrlRecord)\fR
8da2b3a @klacke parse_url
authored
337 Takes a #url record a formats the Url as a string
338
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
339 .TP
340 \fBcall_cgi(Arg, Scriptfilename)\fR
341 Calls an executable CGI script,
342 given by its full path. Used to make `.yaws' wrappers for CGI
343 programs. This function usually returns \fIstreamcontent\fR.
344
345 .TP
346 \fBcall_cgi(Arg, Exefilename, Scriptfilename)\fR
347 Like before, but
348 calls \fIExefilename\fR to handle the script. The file name of the
349 script is handed to the executable via a CGI meta variable.
8da2b3a @klacke parse_url
authored
350
351
abc3a43 @klacke documented yaws_api
authored
352 .SH RETURN VALUES from out/1
353 .PP
354 The out/1 function can return different values to control the behavior
355 of the server.
356
357 .TP
358 \fB{html, DeepList}\fB
359 This assumes that DeepList is formatted HTML code.
360 The code will be inserted in the page.
361
362 .TP
363 \fB{ehtml, Term}\fR
364 This will transform the erlang term Term into a
365 stream of HTML content. The basic syntax of Term
366 is
367
368 \fI
369 .nf
370 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
371 binary() | character()
8d5aa60 @klacke ""
authored
372 Tag = atom()
abc3a43 @klacke documented yaws_api
authored
373 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored
374 Key = atom()
abc3a43 @klacke documented yaws_api
authored
375 Value = string()
376 Body = EHTML
377 .fi
378 \fR
379
380
381 For example, \fI{p, [], "Howdy"}\fR expand into
382 "<p>Howdy</p> and
383
384 \fI
385 .nf
386 {form, [{action, "a.yaws"}],
387 {input, [{type,text}]}}
388
389 .fi
390 \fR
391
392 expands into
393
394 \fI
395 .nf
396 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
397 <input type="text">
398 </form>
abc3a43 @klacke documented yaws_api
authored
399 .fi
400 \fR
401
402 It may be more convenient to generate erlang tuples
403 than plain html code.
404
405 .TP
406 \fB{content, MimeType, Content}\fR
407 This function will make the web server generate
408 different content than HTML. This return value is only allowed
409 in a yaws file which has only one <erl> </erl> part and no
410 html parts at all.
411
412
413 .TP
414 \fB{streamcontent, MimeType, FirstChunk}\fR
415 This return value plays the same role as the \fIcontent\fR return
416 value above.
417 However it makes it possible to stream data to the client
418 if the yaws code doesn't have access to all the data in one go. (Typically
419 if a file is very large or if data arrives from back end servers on the network.
420
421 .TP
422 \fB{header, H}\fR
423 Accumulates a HTTP header. Used by for example the \fBsetcookie/2-6\fR
b349dac @klacke ""
authored
424 function.
abc3a43 @klacke documented yaws_api
authored
425
426 .TP
427 \fB{allheaders, HeaderList}\fB
428 Will clear all previously accumulated headers and replace them.
429
430
431 .TP
432 \fB{status, Code}\fR
433 Will set another HTTP status code than 200.
434
435
436 .TP
437 \fBbreak\fR
438 Will stop processing of any consecutive chunks of erl or html code
439 in the yaws file.
440
441 .TP
442 \fBok\fR
443 Do nothing.
444
445
446 .TP
447 \fB{redirect, Url}\fR
448 Erase all previous headers and accumulate a single
449 Location header. Set the status code.
450
451 .TP
452 \fB{redirect_local, Path}\fR
453 Does a redirect to the same Scheme://Host:Port/Path as we
454 currently are executing in.
455
456 .TP
457 \fB{get_more, Cont, State}\fR
458 When we are receiving large POSTs we can return this value
459 and be invoked again when more Data arrives.
460
461
462 .TP
c837288 @klacke page retval
authored
463 \fB{page, Page}\fR
464 Make Yaws return a different page than the one being
465 requested.
466
467
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
468 .TP
469 \fB{page, {Options, Page}}\fR
470 Like the above, but supplying an additional deep list of options. For
471 now, the only type of option is \fI{header, H}\fR with the effect of
472 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
473
c837288 @klacke page retval
authored
474
475 .TP
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
476 \fB{ssi, File, Delimiter, Bindings}\fR
477 Server side include File and macro expansion in File.
478 Each occurence of a string, say "xyz", inside File which
479 is inside Delimters is replaced with the corresponsing
480 value in Bindings.
481
482 Example:
483 Delimiter = %%
484
485 File contains the string .... %%xyz%% .....
486
487 Bindings contain the tuple {"xyz", "Dingbat"}
488
489 The occurence of %%xyz%% in File will be replaced with "Dingbat"
490 in the Server side included output.
491
492 The {ssi, File, Delimiter, Bindings} statement can also
493 occur inside a deep ehtml structure.
494
495
496 .TP
379666b @klacke documented jockes new bindings feature
authored
497 \fB{bindings, [{Key1, Value2}, {Key2, Value2} .....]}\fR
498 Establish variable bindings that can be used in the page.
499
500 All bindings can then be used in the rest of yaws code
501 (in HTML source and within erl tags).
502 In HTML source %%Key%% is expanded to Value and within erl
503 tags yaws_api:get_binding(Key) can be used to extract Value.
504
505 .TP
abc3a43 @klacke documented yaws_api
authored
506 \fB[ListOfValues]\fR
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
507 It is possible to return a deep list of the above defined
508 return values. Any occurrence of \fIstream_content\fR, \fIget_more\fR
509 or \fIpage\fR in this list is legal only if it is the last position of
510 the list.
abc3a43 @klacke documented yaws_api
authored
511
512
513
514
515 .SH AUTHOR
516 Written by Claes Wikstrom
517 .SH "SEE ALSO"
518 .BR yaws.conf (5)
519 .BR erl (1)
520
Something went wrong with that request. Please try again.