Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 466 lines (348 sloc) 11.348 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
166 This function is convenient when getting \r\n terminated lines
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
193 This function will parse the query part of the URL which the client GETs
194 It will return a {Key, Value} list of the items supplied in the query
195 part of the URL. This only works with GET requests.
196
197
198 .TP
c4523b3 @klacke ""
authored
199 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
200 This function will parse the POST data as supplied from the browser.
201 It will return a {Key, Value} list of the items set by the browser.
202
c4523b3 @klacke ""
authored
203
204 .TP
205 \fBparse_multipart_post(Arg)\fR
206
abc3a43 @klacke documented yaws_api
authored
207 If the browser has set the Content-Type header to the value
208 "multipart/form-data", which is the case when the browser
209 wants to upload a file to the server the following happens:
210
211
212 If the function returns \fB{result, Res}\fR no more data
213 will come from the browser.
214
215 If the function returns \fB{cont, Cont, Res}\fR the browser
216 will supply more data. (The file was to big to come in one read)
217
218 This indicates that there is more data to come and the out/1 function
219 should return {get_more, Cont, User_state} where User_state might
220 usefully be a File Descriptor.
221
222
223 The Res value is a list of either:
224 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
225
226
227 Example usage could be:
228 \fI
229 .nf
230 <erl>
231
232 out(A) ->
c4523b3 @klacke ""
authored
233 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
234 {cont, Cont, Res} ->
235 St = handle_res(A, Res),
236 {get_more, Cont, St};
237 {result, Res} ->
238 handle_res(A, Res),
239 {html, f("<pre>Done </pre>",[])}
240 end.
241
242 handle_res(A, [{head, Name}|T]) ->
243 io:format("head:~p~n",[Name]),
244 handle_res(A, T);
245 handle_res(A, [{part_body, Data}|T]) ->
246 io:format("part_body:~p~n",[Data]),
247 handle_res(A, T);
248 handle_res(A, [{body, Data}|T]) ->
249 io:format("body:~p~n",[Data]),
250 handle_res(A, T);
251 handle_res(A, []) ->
252 io:format("End_res~n").
253
254 </erl>
255 .fi
256 \fR
257
258
259
260 .TP
87b1456 @klacke wrote the shopppingcart example
authored
261 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
262 Create a new cookie based session, the yaws system will set the
87b1456 @klacke wrote the shopppingcart example
authored
263 cookie. The new randomgenerated cookie is returned from this
264 function. The Opaque argument will typically contain user data
265 such as username and password
abc3a43 @klacke documented yaws_api
authored
266
267 .TP
87b1456 @klacke wrote the shopppingcart example
authored
268 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
269
270 .TP
271 \fBprint_cookie_sessions() \fR
272
87b1456 @klacke wrote the shopppingcart example
authored
273
274 .TP
275 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
276
abc3a43 @klacke documented yaws_api
authored
277 .TP
87b1456 @klacke wrote the shopppingcart example
authored
278 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
279
280
50a7ab2 @klacke added support/docs for embedded mode
authored
281 .TP
282 \fBsetconf(Gconf, Groups)\fR
283 This function is intended for embedded mode in yaws. It makes it possible
284 to load a yaws configuration from another data source than /etc/yaws.conf, such
285 as a database.
286 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
287 start with an empty default configuration, and wait for some other
288 program to execute a \fIsetconf/2\fR
289 The Gconf is a \fI#gconf{}\fR record and the Group variable is
290 a list of lists of \fI#sconf{}\fR records. Each sublist must
291 contain \fI#sconf{}\fR records with the same IP/Port listen address.
292
abc3a43 @klacke documented yaws_api
authored
293
2b9f008 @klacke ""
authored
294
295 .TP
296 \fBurl_decode(Str)\fR
297 Decode url-encoded string. A URL ncoded string is a string where
298 all alfa numeric characters and the the character _ are preserved
299 and all other characters are encode as "%XY" where X and Y are the
300 hex values of the least respective most significat 4 bits in the 8 bit
301 character.
302
303 .TP
304 \fBurl_encode(Str)\fR
305 Url-encodes a string. All URLs in HTML documents must be URL encoded.
306
307
814eb04 @klacke ""
authored
308 .TP
8d5aa60 @klacke ""
authored
309 \fBreformat_header(H)\fR
814eb04 @klacke ""
authored
310 Returns a list of reformated header values from a #header{}
311 record. The return list is suitable for retransmit.
312
2b9f008 @klacke ""
authored
313
8da2b3a @klacke parse_url
authored
314 .TP
315 \fBparse_url(Str)\fR
316 Parse URL in a string, returns a #url record
317
318 .TP
319 \fVformat_url(UrlRecord)\fR
320 Takes a #url record a formats the Url as a string
321
322
323
abc3a43 @klacke documented yaws_api
authored
324 .SH RETURN VALUES from out/1
325 .PP
326 The out/1 function can return different values to control the behavior
327 of the server.
328
329 .TP
330 \fB{html, DeepList}\fB
331 This assumes that DeepList is formatted HTML code.
332 The code will be inserted in the page.
333
334 .TP
335 \fB{ehtml, Term}\fR
336 This will transform the erlang term Term into a
337 stream of HTML content. The basic syntax of Term
338 is
339
340 \fI
341 .nf
342 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
343 binary() | character()
8d5aa60 @klacke ""
authored
344 Tag = atom()
abc3a43 @klacke documented yaws_api
authored
345 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored
346 Key = atom()
abc3a43 @klacke documented yaws_api
authored
347 Value = string()
348 Body = EHTML
349 .fi
350 \fR
351
352
353 For example, \fI{p, [], "Howdy"}\fR expand into
354 "<p>Howdy</p> and
355
356 \fI
357 .nf
358 {form, [{action, "a.yaws"}],
359 {input, [{type,text}]}}
360
361 .fi
362 \fR
363
364 expands into
365
366 \fI
367 .nf
368 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
369 <input type="text">
370 </form>
abc3a43 @klacke documented yaws_api
authored
371 .fi
372 \fR
373
374 It may be more convenient to generate erlang tuples
375 than plain html code.
376
377 .TP
378 \fB{content, MimeType, Content}\fR
379 This function will make the web server generate
380 different content than HTML. This return value is only allowed
381 in a yaws file which has only one <erl> </erl> part and no
382 html parts at all.
383
384
385 .TP
386 \fB{streamcontent, MimeType, FirstChunk}\fR
387 This return value plays the same role as the \fIcontent\fR return
388 value above.
389 However it makes it possible to stream data to the client
390 if the yaws code doesn't have access to all the data in one go. (Typically
391 if a file is very large or if data arrives from back end servers on the network.
392
393 .TP
394 \fB{header, H}\fR
395 Accumulates a HTTP header. Used by for example the \fBsetcookie/2-6\fR
b349dac @klacke ""
authored
396 function.
abc3a43 @klacke documented yaws_api
authored
397
398 .TP
399 \fB{allheaders, HeaderList}\fB
400 Will clear all previously accumulated headers and replace them.
401
402
403 .TP
404 \fB{status, Code}\fR
405 Will set another HTTP status code than 200.
406
407
408 .TP
409 \fBbreak\fR
410 Will stop processing of any consecutive chunks of erl or html code
411 in the yaws file.
412
413 .TP
414 \fBok\fR
415 Do nothing.
416
417
418 .TP
419 \fB{redirect, Url}\fR
420 Erase all previous headers and accumulate a single
421 Location header. Set the status code.
422
423 .TP
424 \fB{redirect_local, Path}\fR
425 Does a redirect to the same Scheme://Host:Port/Path as we
426 currently are executing in.
427
428
429
430
431 .TP
432 \fB{get_more, Cont, State}\fR
433 When we are receiving large POSTs we can return this value
434 and be invoked again when more Data arrives.
435
436
437 .TP
c837288 @klacke page retval
authored
438 \fB{page, Page}\fR
439 Make Yaws return a different page than the one being
440 requested.
441
442
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
443 .TP
444 \fB{page, {Options, Page}}\fR
445 Like the above, but supplying an additional deep list of options. For
446 now, the only type of option is \fI{header, H}\fR with the effect of
447 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
448
c837288 @klacke page retval
authored
449
450 .TP
abc3a43 @klacke documented yaws_api
authored
451 \fB[ListOfValues]\fR
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
452 It is possible to return a deep list of the above defined
453 return values. Any occurrence of \fIstream_content\fR, \fIget_more\fR
454 or \fIpage\fR in this list is legal only if it is the last position of
455 the list.
abc3a43 @klacke documented yaws_api
authored
456
457
458
459
460 .SH AUTHOR
461 Written by Claes Wikstrom
462 .SH "SEE ALSO"
463 .BR yaws.conf (5)
464 .BR erl (1)
465
Something went wrong with that request. Please try again.