Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 445 lines (330 sloc) 10.587 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, {
8d5aa60 @klacke ""
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 querydata, %% Was the URL on the form of ...?query (GET reqs)
51 docroot, %% where's the data
52 fullpath, %% full path to yaws file
53 cont, %% Continuation for chunked multipart uploads
54 state, %% State for use by users of the out/1 callback
55 pid, %% pid of the yaws process
56 opaque %% useful to pass static data
57
58 }).
abc3a43 @klacke documented yaws_api
authored
59 .fi
60 \fR
61
62 The headers argument is also a record:
63 \fI
64 .nf
8d5aa60 @klacke ""
authored
65
abc3a43 @klacke documented yaws_api
authored
66 -record(headers, {
8d5aa60 @klacke ""
authored
67 connection,
68 accept,
69 host,
70 if_modified_since,
71 if_match,
72 if_none_match,
73 if_range,
74 if_unmodified_since,
75 range,
76 referer,
77 user_agent,
78 accept_ranges,
79 cookie = [],
80 keep_alive,
81 content_length,
82 authorization,
83 other = [] %% misc other headers
84 }).
abc3a43 @klacke documented yaws_api
authored
85
86 .fi
87 \fR
88
89 .PP The \fBout/1\fR function can use the Arg to generate any content
90 it likes. We have the following functions to aid that generation.
91
92
93 .SH API
94
95 .TP
96 \fBssi(DocRoot, ListOfFiles)\fR
97 Server side include. Just include the files as is in the document. The files
98 will \fBnot\fR be parsed and searched for <erl> tags.
99
100
101 .TP
102 \fBpre_ssi_files(DocRoot, ListOfFiles) ->
103 Server side include of pre indented code. The data in Files
104 will be included but contained in a <pre> tag. The data will be
105 htmlized.
106
107 .TP
108 \fBpre_ssi_string(String)\fR
109 Include htmlized content from String.
110
111
112 .TP
113 \fBf(Fmt, Args)\fR
114 The equivalent of io_lib:format/2. This function is automatically
115 -included in all erlang code which is a part of a yaws page.
116
117 .TP
118 \fBhtmlize(Binary)\fR
119 Htmlize a binary object.
120
121 .TP
122 \fBhtmlize_l(DeepList)\fR
123 Htmlize any deep list of chars and binaries.
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
162 This function is convenient when getting \r\n terminated lines
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.
179
180
181 .TP
182 \fBstream_chunk_end(YawsPid)\fR
183 When the process discussed above is done delivering data, it must call
184 this function to let the yaws content delivering process finish up
185 the HTTP transaction.
186
187 .TP
188 \fBparse_query(Arg)\fR
189 This function will parse the query part of the URL which the client GETs
190 It will return a {Key, Value} list of the items supplied in the query
191 part of the URL. This only works with GET requests.
192
193
194 .TP
c4523b3 @klacke ""
authored
195 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
196 This function will parse the POST data as supplied from the browser.
197 It will return a {Key, Value} list of the items set by the browser.
198
c4523b3 @klacke ""
authored
199
200 .TP
201 \fBparse_multipart_post(Arg)\fR
202
abc3a43 @klacke documented yaws_api
authored
203 If the browser has set the Content-Type header to the value
204 "multipart/form-data", which is the case when the browser
205 wants to upload a file to the server the following happens:
206
207
208 If the function returns \fB{result, Res}\fR no more data
209 will come from the browser.
210
211 If the function returns \fB{cont, Cont, Res}\fR the browser
212 will supply more data. (The file was to big to come in one read)
213
214 This indicates that there is more data to come and the out/1 function
215 should return {get_more, Cont, User_state} where User_state might
216 usefully be a File Descriptor.
217
218
219 The Res value is a list of either:
220 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
221
222
223 Example usage could be:
224 \fI
225 .nf
226 <erl>
227
228 out(A) ->
c4523b3 @klacke ""
authored
229 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
230 {cont, Cont, Res} ->
231 St = handle_res(A, Res),
232 {get_more, Cont, St};
233 {result, Res} ->
234 handle_res(A, Res),
235 {html, f("<pre>Done </pre>",[])}
236 end.
237
238 handle_res(A, [{head, Name}|T]) ->
239 io:format("head:~p~n",[Name]),
240 handle_res(A, T);
241 handle_res(A, [{part_body, Data}|T]) ->
242 io:format("part_body:~p~n",[Data]),
243 handle_res(A, T);
244 handle_res(A, [{body, Data}|T]) ->
245 io:format("body:~p~n",[Data]),
246 handle_res(A, T);
247 handle_res(A, []) ->
248 io:format("End_res~n").
249
250 </erl>
251 .fi
252 \fR
253
254
255
256
257 .TP
87b1456 @klacke wrote the shopppingcart example
authored
258 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
259 Create a new cookie based session, the yaws system will set the
87b1456 @klacke wrote the shopppingcart example
authored
260 cookie. The new randomgenerated cookie is returned from this
261 function. The Opaque argument will typically contain user data
262 such as username and password
abc3a43 @klacke documented yaws_api
authored
263
264 .TP
87b1456 @klacke wrote the shopppingcart example
authored
265 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
266
267 .TP
268 \fBprint_cookie_sessions() \fR
269
87b1456 @klacke wrote the shopppingcart example
authored
270
271 .TP
272 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
273
abc3a43 @klacke documented yaws_api
authored
274 .TP
87b1456 @klacke wrote the shopppingcart example
authored
275 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
276
277
50a7ab2 @klacke added support/docs for embedded mode
authored
278 .TP
279 \fBsetconf(Gconf, Groups)\fR
280 This function is intended for embedded mode in yaws. It makes it possible
281 to load a yaws configuration from another data source than /etc/yaws.conf, such
282 as a database.
283 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
284 start with an empty default configuration, and wait for some other
285 program to execute a \fIsetconf/2\fR
286 The Gconf is a \fI#gconf{}\fR record and the Group variable is
287 a list of lists of \fI#sconf{}\fR records. Each sublist must
288 contain \fI#sconf{}\fR records with the same IP/Port listen address.
289
abc3a43 @klacke documented yaws_api
authored
290
2b9f008 @klacke ""
authored
291
292 .TP
293 \fBurl_decode(Str)\fR
294 Decode url-encoded string. A URL ncoded string is a string where
295 all alfa numeric characters and the the character _ are preserved
296 and all other characters are encode as "%XY" where X and Y are the
297 hex values of the least respective most significat 4 bits in the 8 bit
298 character.
299
300 .TP
301 \fBurl_encode(Str)\fR
302 Url-encodes a string. All URLs in HTML documents must be URL encoded.
303
304
814eb04 @klacke ""
authored
305 .TP
8d5aa60 @klacke ""
authored
306 \fBreformat_header(H)\fR
814eb04 @klacke ""
authored
307 Returns a list of reformated header values from a #header{}
308 record. The return list is suitable for retransmit.
309
2b9f008 @klacke ""
authored
310
abc3a43 @klacke documented yaws_api
authored
311 .SH RETURN VALUES from out/1
312 .PP
313 The out/1 function can return different values to control the behavior
314 of the server.
315
316 .TP
317 \fB{html, DeepList}\fB
318 This assumes that DeepList is formatted HTML code.
319 The code will be inserted in the page.
320
321 .TP
322 \fB{ehtml, Term}\fR
323 This will transform the erlang term Term into a
324 stream of HTML content. The basic syntax of Term
325 is
326
327 \fI
328 .nf
329 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
330 binary() | character()
8d5aa60 @klacke ""
authored
331 Tag = atom()
abc3a43 @klacke documented yaws_api
authored
332 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored
333 Key = atom()
abc3a43 @klacke documented yaws_api
authored
334 Value = string()
335 Body = EHTML
336 .fi
337 \fR
338
339
340 For example, \fI{p, [], "Howdy"}\fR expand into
341 "<p>Howdy</p> and
342
343 \fI
344 .nf
345 {form, [{action, "a.yaws"}],
346 {input, [{type,text}]}}
347
348 .fi
349 \fR
350
351 expands into
352
353 \fI
354 .nf
355 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
356 <input type="text">
357 </form>
abc3a43 @klacke documented yaws_api
authored
358 .fi
359 \fR
360
361 It may be more convenient to generate erlang tuples
362 than plain html code.
363
364 .TP
365 \fB{content, MimeType, Content}\fR
366 This function will make the web server generate
367 different content than HTML. This return value is only allowed
368 in a yaws file which has only one <erl> </erl> part and no
369 html parts at all.
370
371
372 .TP
373 \fB{streamcontent, MimeType, FirstChunk}\fR
374 This return value plays the same role as the \fIcontent\fR return
375 value above.
376 However it makes it possible to stream data to the client
377 if the yaws code doesn't have access to all the data in one go. (Typically
378 if a file is very large or if data arrives from back end servers on the network.
379
380 .TP
381 \fB{header, H}\fR
382 Accumulates a HTTP header. Used by for example the \fBsetcookie/2-6\fR
383 function.
384
385 .TP
386 \fB{allheaders, HeaderList}\fB
387 Will clear all previously accumulated headers and replace them.
388
389
390 .TP
391 \fB{status, Code}\fR
392 Will set another HTTP status code than 200.
393
394
395 .TP
396 \fBbreak\fR
397 Will stop processing of any consecutive chunks of erl or html code
398 in the yaws file.
399
400 .TP
401 \fBok\fR
402 Do nothing.
403
404
405 .TP
406 \fB{redirect, Url}\fR
407 Erase all previous headers and accumulate a single
408 Location header. Set the status code.
409
410 .TP
411 \fB{redirect_local, Path}\fR
412 Does a redirect to the same Scheme://Host:Port/Path as we
413 currently are executing in.
414
415
416
417
418 .TP
419 \fB{get_more, Cont, State}\fR
420 When we are receiving large POSTs we can return this value
421 and be invoked again when more Data arrives.
422
423
424 .TP
c837288 @klacke page retval
authored
425 \fB{page, Page}\fR
426 Make Yaws return a different page than the one being
427 requested.
428
429
430
431 .TP
abc3a43 @klacke documented yaws_api
authored
432 \fB[ListOfValues]\fR
433 It is possible to return a list of the above defined
434 return values.
435
436
437
438
439 .SH AUTHOR
440 Written by Claes Wikstrom
441 .SH "SEE ALSO"
442 .BR yaws.conf (5)
443 .BR erl (1)
444
Something went wrong with that request. Please try again.