Skip to content
This repository
Newer
Older
100644 514 lines (389 sloc) 12.993 kb
abc3a435 »
2002-09-17 documented yaws_api
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, {
0d99c121 » carsten3347
2003-08-24 Changes to arg record, {page, {Options, Page}}, comment on returning a
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 }).
abc3a435 »
2002-09-17 documented yaws_api
63 .fi
64 \fR
65
66 The headers argument is also a record:
67 \fI
68 .nf
8d5aa60c »
2002-11-10 ""
69
abc3a435 »
2002-09-17 documented yaws_api
70 -record(headers, {
8d5aa60c »
2002-11-10 ""
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 }).
abc3a435 »
2002-09-17 documented yaws_api
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
d02b9655 »
2004-02-13 qnx port + docs overhaul by cschatz@networkadvantage.biz
166 This function is convenient when getting \\r\\n terminated lines
abc3a435 »
2002-09-17 documented yaws_api
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
b2d5a000 »
2003-12-17 postvar(), queryvar(), ssi docs
193 This function will parse the query part of the URL.
abc3a435 »
2002-09-17 documented yaws_api
194 It will return a {Key, Value} list of the items supplied in the query
b2d5a000 »
2003-12-17 postvar(), queryvar(), ssi docs
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.
abc3a435 »
2002-09-17 documented yaws_api
202
203
204 .TP
c4523b30 »
2002-10-18 ""
205 \fBparse_post(Arg)\fR
abc3a435 »
2002-09-17 documented yaws_api
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
b2d5a000 »
2003-12-17 postvar(), queryvar(), ssi docs
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
c4523b30 »
2002-10-18 ""
215
216 .TP
217 \fBparse_multipart_post(Arg)\fR
218
abc3a435 »
2002-09-17 documented yaws_api
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) ->
c4523b30 »
2002-10-18 ""
245 case yaws_api:parse_multipart_post(A) of
abc3a435 »
2002-09-17 documented yaws_api
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
87b14560 »
2002-10-06 wrote the shopppingcart example
273 \fBnew_cookie_session(Opaque)\fR
abc3a435 »
2002-09-17 documented yaws_api
274 Create a new cookie based session, the yaws system will set the
87b14560 »
2002-10-06 wrote the shopppingcart example
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
abc3a435 »
2002-09-17 documented yaws_api
278
279 .TP
87b14560 »
2002-10-06 wrote the shopppingcart example
280 \fBcookieval_to_opaque(CookieVal)\fR
abc3a435 »
2002-09-17 documented yaws_api
281
282 .TP
283 \fBprint_cookie_sessions() \fR
284
87b14560 »
2002-10-06 wrote the shopppingcart example
285
286 .TP
287 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
288
abc3a435 »
2002-09-17 documented yaws_api
289 .TP
87b14560 »
2002-10-06 wrote the shopppingcart example
290 \fBdelete_cookie_session(Cookie)\fR
abc3a435 »
2002-09-17 documented yaws_api
291
292
50a7ab21 »
2002-09-27 added support/docs for embedded mode
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
abc3a435 »
2002-09-17 documented yaws_api
305
2b9f0087 »
2002-11-05 ""
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
814eb043 »
2002-11-07 ""
320 .TP
8d5aa60c »
2002-11-10 ""
321 \fBreformat_header(H)\fR
814eb043 »
2002-11-07 ""
322 Returns a list of reformated header values from a #header{}
323 record. The return list is suitable for retransmit.
324
2b9f0087 »
2002-11-05 ""
325
8da2b3a7 »
2002-11-20 parse_url
326 .TP
327 \fBparse_url(Str)\fR
328 Parse URL in a string, returns a #url record
329
330 .TP
42ab9903 » carsten3347
2003-08-25 Make call_cgi available in yaws_api.
331 \fBformat_url(UrlRecord)\fR
8da2b3a7 »
2002-11-20 parse_url
332 Takes a #url record a formats the Url as a string
333
42ab9903 » carsten3347
2003-08-25 Make call_cgi available in yaws_api.
334 .TP
335 \fBcall_cgi(Arg, Scriptfilename)\fR
336 Calls an executable CGI script,
337 given by its full path. Used to make `.yaws' wrappers for CGI
338 programs. This function usually returns \fIstreamcontent\fR.
339
340 .TP
341 \fBcall_cgi(Arg, Exefilename, Scriptfilename)\fR
342 Like before, but
343 calls \fIExefilename\fR to handle the script. The file name of the
344 script is handed to the executable via a CGI meta variable.
8da2b3a7 »
2002-11-20 parse_url
345
346
abc3a435 »
2002-09-17 documented yaws_api
347 .SH RETURN VALUES from out/1
348 .PP
349 The out/1 function can return different values to control the behavior
350 of the server.
351
352 .TP
353 \fB{html, DeepList}\fB
354 This assumes that DeepList is formatted HTML code.
355 The code will be inserted in the page.
356
357 .TP
358 \fB{ehtml, Term}\fR
359 This will transform the erlang term Term into a
360 stream of HTML content. The basic syntax of Term
361 is
362
363 \fI
364 .nf
365 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
366 binary() | character()
8d5aa60c »
2002-11-10 ""
367 Tag = atom()
abc3a435 »
2002-09-17 documented yaws_api
368 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60c »
2002-11-10 ""
369 Key = atom()
abc3a435 »
2002-09-17 documented yaws_api
370 Value = string()
371 Body = EHTML
372 .fi
373 \fR
374
375
376 For example, \fI{p, [], "Howdy"}\fR expand into
377 "<p>Howdy</p> and
378
379 \fI
380 .nf
381 {form, [{action, "a.yaws"}],
382 {input, [{type,text}]}}
383
384 .fi
385 \fR
386
387 expands into
388
389 \fI
390 .nf
391 <form action="a.yaws"
df99ebe6 »
2002-09-27 *** empty log message ***
392 <input type="text">
393 </form>
abc3a435 »
2002-09-17 documented yaws_api
394 .fi
395 \fR
396
397 It may be more convenient to generate erlang tuples
398 than plain html code.
399
400 .TP
401 \fB{content, MimeType, Content}\fR
402 This function will make the web server generate
403 different content than HTML. This return value is only allowed
404 in a yaws file which has only one <erl> </erl> part and no
405 html parts at all.
406
407
408 .TP
409 \fB{streamcontent, MimeType, FirstChunk}\fR
410 This return value plays the same role as the \fIcontent\fR return
411 value above.
412 However it makes it possible to stream data to the client
413 if the yaws code doesn't have access to all the data in one go. (Typically
414 if a file is very large or if data arrives from back end servers on the network.
415
416 .TP
417 \fB{header, H}\fR
418 Accumulates a HTTP header. Used by for example the \fBsetcookie/2-6\fR
b349dacc »
2002-11-25 ""
419 function.
abc3a435 »
2002-09-17 documented yaws_api
420
421 .TP
422 \fB{allheaders, HeaderList}\fB
423 Will clear all previously accumulated headers and replace them.
424
425
426 .TP
427 \fB{status, Code}\fR
428 Will set another HTTP status code than 200.
429
430
431 .TP
432 \fBbreak\fR
433 Will stop processing of any consecutive chunks of erl or html code
434 in the yaws file.
435
436 .TP
437 \fBok\fR
438 Do nothing.
439
440
441 .TP
442 \fB{redirect, Url}\fR
443 Erase all previous headers and accumulate a single
444 Location header. Set the status code.
445
446 .TP
447 \fB{redirect_local, Path}\fR
448 Does a redirect to the same Scheme://Host:Port/Path as we
449 currently are executing in.
450
451 .TP
452 \fB{get_more, Cont, State}\fR
453 When we are receiving large POSTs we can return this value
454 and be invoked again when more Data arrives.
455
456
457 .TP
c8372880 »
2002-11-12 page retval
458 \fB{page, Page}\fR
459 Make Yaws return a different page than the one being
460 requested.
461
462
0d99c121 » carsten3347
2003-08-24 Changes to arg record, {page, {Options, Page}}, comment on returning a
463 .TP
464 \fB{page, {Options, Page}}\fR
465 Like the above, but supplying an additional deep list of options. For
466 now, the only type of option is \fI{header, H}\fR with the effect of
467 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
468
c8372880 »
2002-11-12 page retval
469
470 .TP
b2d5a000 »
2003-12-17 postvar(), queryvar(), ssi docs
471 \fB{ssi, File, Delimiter, Bindings}\fR
472 Server side include File and macro expansion in File.
473 Each occurence of a string, say "xyz", inside File which
474 is inside Delimters is replaced with the corresponsing
475 value in Bindings.
476
477 Example:
478 Delimiter = %%
479
480 File contains the string .... %%xyz%% .....
481
482 Bindings contain the tuple {"xyz", "Dingbat"}
483
484 The occurence of %%xyz%% in File will be replaced with "Dingbat"
485 in the Server side included output.
486
487 The {ssi, File, Delimiter, Bindings} statement can also
488 occur inside a deep ehtml structure.
489
490
491 .TP
379666bf »
2004-01-27 documented jockes new bindings feature
492 \fB{bindings, [{Key1, Value2}, {Key2, Value2} .....]}\fR
493 Establish variable bindings that can be used in the page.
494
495 All bindings can then be used in the rest of yaws code
496 (in HTML source and within erl tags).
497 In HTML source %%Key%% is expanded to Value and within erl
498 tags yaws_api:get_binding(Key) can be used to extract Value.
499
500 .TP
abc3a435 »
2002-09-17 documented yaws_api
501 \fB[ListOfValues]\fR
0d99c121 » carsten3347
2003-08-24 Changes to arg record, {page, {Options, Page}}, comment on returning a
502 It is possible to return a deep list of the above defined
503 return values. Any occurrence of \fIstream_content\fR, \fIget_more\fR
504 or \fIpage\fR in this list is legal only if it is the last position of
505 the list.
abc3a435 »
2002-09-17 documented yaws_api
506
507
508
509
510 .SH AUTHOR
511 Written by Claes Wikstrom
512 .SH "SEE ALSO"
513 .BR yaws.conf (5)
514 .BR erl (1)
515
Something went wrong with that request. Please try again.