Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 393 lines (293 sloc) 8.877 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, {
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 }).
57 .fi
58 \fR
59
60 The headers argument is also a record:
61 \fI
62 .nf
63
64 -record(headers, {
65 connection,
66 accept,
67 host,
68 if_modified_since,
69 if_match,
70 if_none_match,
71 if_range,
72 if_unmodified_since,
73 range,
74 referer,
75 user_agent,
76 accept_ranges,
77 cookie = [],
78 keep_alive,
79 content_length,
80 authorization,
81 other = [] %% misc other headers
82 }).
83
84 .fi
85 \fR
86
87 .PP The \fBout/1\fR function can use the Arg to generate any content
88 it likes. We have the following functions to aid that generation.
89
90
91 .SH API
92
93 .TP
94 \fBssi(DocRoot, ListOfFiles)\fR
95 Server side include. Just include the files as is in the document. The files
96 will \fBnot\fR be parsed and searched for <erl> tags.
97
98
99 .TP
100 \fBpre_ssi_files(DocRoot, ListOfFiles) ->
101 Server side include of pre indented code. The data in Files
102 will be included but contained in a <pre> tag. The data will be
103 htmlized.
104
105 .TP
106 \fBpre_ssi_string(String)\fR
107 Include htmlized content from String.
108
109
110 .TP
111 \fBf(Fmt, Args)\fR
112 The equivalent of io_lib:format/2. This function is automatically
113 -included in all erlang code which is a part of a yaws page.
114
115 .TP
116 \fBhtmlize(Binary)\fR
117 Htmlize a binary object.
118
119 .TP
120 \fBhtmlize_l(DeepList)\fR
121 Htmlize any deep list of chars and binaries.
122
123 .TP
124 \fBsetcookie(Name, Value, [Path, [ Expire, [Domain , [Secure]]]])\fR
125 Sets a cookie to the browser.
126
127 .TP
128 \fBfind_cookie_val(Cookie, Header)\fR
129 This function can be used to search for a cookie that was previously
130 set by \fBsetcookie/2-6\fR. For example if we set a cookie
131 as \fByaws_api:setcookie("sid",SomeRandomSid) \fR, then on subsequent requests
132 from the browser we can call:
133 \fBfind_cookie("sid",(Arg#arg.headers)#headers.cookie)\fR
134
135 The function returns [] if no cookie was found, otherwise the actual cookie
136 is returned as a string.
137
138
139 .TP
140 \fBredirect(Url\fR
141 This function generates a redirect to the browser.
142 It will clear any previously set headers. So to generate
143 a redirect \fBand\fR set a cookie, we need to set the cookie after
144 the redirect as in:
145 \fI
146 .nf
147 out(Arg) ->
148 ... do some stuff
149
150 Ret = [{redirect, "http://www.somewhere.com"},
151 setcookie("sid", Random)
152 ].
153
154 .fi
155 \fR
156
157
158 .TP
159 \fBget_line(String)\fR
160 This function is convenient when getting \r\n terminated lines
161 from a stream of data. It returns:
162
163 \fB{line, Line, Tail}\fR or \fB{lastline, Line, Tail}\fR
164
165 The function handles multilines as defined in e.g. SMTP or HTTP
166
167 .TP
168 \fBmime_type(FileName)\fR
169 Returns the mime type as defined by the extension of FileName
170
171 .TP
172 \fBstream_chunk_deliver(YawsPid, Data)\fR
173 When a yaws function needs to deliver chunks of data which it gets
174 from a process. The other process can call this function to deliver
175 these chunks. It requires the \fBout/1\fR function to return the
176 value \fB{streamcontent, MimeType, FirstChunk}\fR to work.
177
178
179 .TP
180 \fBstream_chunk_end(YawsPid)\fR
181 When the process discussed above is done delivering data, it must call
182 this function to let the yaws content delivering process finish up
183 the HTTP transaction.
184
185 .TP
186 \fBparse_query(Arg)\fR
187 This function will parse the query part of the URL which the client GETs
188 It will return a {Key, Value} list of the items supplied in the query
189 part of the URL. This only works with GET requests.
190
191
192 .TP
193 \fBparse_post_data(Arg)\fR
194 This function will parse the POST data as supplied from the browser.
195 It will return a {Key, Value} list of the items set by the browser.
196
197 If the browser has set the Content-Type header to the value
198 "multipart/form-data", which is the case when the browser
199 wants to upload a file to the server the following happens:
200
201
202 If the function returns \fB{result, Res}\fR no more data
203 will come from the browser.
204
205 If the function returns \fB{cont, Cont, Res}\fR the browser
206 will supply more data. (The file was to big to come in one read)
207
208 This indicates that there is more data to come and the out/1 function
209 should return {get_more, Cont, User_state} where User_state might
210 usefully be a File Descriptor.
211
212
213 The Res value is a list of either:
214 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
215
216
217 Example usage could be:
218 \fI
219 .nf
220 <erl>
221
222 out(A) ->
223 case yaws_api:parse_post_data(A) of
224 {cont, Cont, Res} ->
225 St = handle_res(A, Res),
226 {get_more, Cont, St};
227 {result, Res} ->
228 handle_res(A, Res),
229 {html, f("<pre>Done </pre>",[])}
230 end.
231
232 handle_res(A, [{head, Name}|T]) ->
233 io:format("head:~p~n",[Name]),
234 handle_res(A, T);
235 handle_res(A, [{part_body, Data}|T]) ->
236 io:format("part_body:~p~n",[Data]),
237 handle_res(A, T);
238 handle_res(A, [{body, Data}|T]) ->
239 io:format("body:~p~n",[Data]),
240 handle_res(A, T);
241 handle_res(A, []) ->
242 io:format("End_res~n").
243
244 </erl>
245 .fi
246 \fR
247
248
249
250
251 .TP
252 \fBnew_cookie_session(User, Passwd, Opaque)\fR
253 Create a new cookie based session, the yaws system will set the
254 cookie.
255
256 .TP
257 \fBcookieval_to_session(CookieVal)\fR
258
259 .TP
260 \fBprint_cookie_sessions() \fR
261
262 .TP
263 \fBreplace_cookie_session(Session, User)\fR
264
265
266
267 .SH RETURN VALUES from out/1
268 .PP
269 The out/1 function can return different values to control the behavior
270 of the server.
271
272 .TP
273 \fB{html, DeepList}\fB
274 This assumes that DeepList is formatted HTML code.
275 The code will be inserted in the page.
276
277 .TP
278 \fB{ehtml, Term}\fR
279 This will transform the erlang term Term into a
280 stream of HTML content. The basic syntax of Term
281 is
282
283 \fI
284 .nf
285 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
286 binary() | character()
287 Tag = atom()
288 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
289 Key = atom()
290 Value = string()
291 Body = EHTML
292 .fi
293 \fR
294
295
296 For example, \fI{p, [], "Howdy"}\fR expand into
297 "<p>Howdy</p> and
298
299 \fI
300 .nf
301 {form, [{action, "a.yaws"}],
302 {input, [{type,text}]}}
303
304 .fi
305 \fR
306
307 expands into
308
309 \fI
310 .nf
311 <form action="a.yaws"
312 <input type="text">>
313 .fi
314 \fR
315
316 It may be more convenient to generate erlang tuples
317 than plain html code.
318
319 .TP
320 \fB{content, MimeType, Content}\fR
321 This function will make the web server generate
322 different content than HTML. This return value is only allowed
323 in a yaws file which has only one <erl> </erl> part and no
324 html parts at all.
325
326
327 .TP
328 \fB{streamcontent, MimeType, FirstChunk}\fR
329 This return value plays the same role as the \fIcontent\fR return
330 value above.
331 However it makes it possible to stream data to the client
332 if the yaws code doesn't have access to all the data in one go. (Typically
333 if a file is very large or if data arrives from back end servers on the network.
334
335 .TP
336 \fB{header, H}\fR
337 Accumulates a HTTP header. Used by for example the \fBsetcookie/2-6\fR
338 function.
339
340 .TP
341 \fB{allheaders, HeaderList}\fB
342 Will clear all previously accumulated headers and replace them.
343
344
345 .TP
346 \fB{status, Code}\fR
347 Will set another HTTP status code than 200.
348
349
350 .TP
351 \fBbreak\fR
352 Will stop processing of any consecutive chunks of erl or html code
353 in the yaws file.
354
355 .TP
356 \fBok\fR
357 Do nothing.
358
359
360 .TP
361 \fB{redirect, Url}\fR
362 Erase all previous headers and accumulate a single
363 Location header. Set the status code.
364
365 .TP
366 \fB{redirect_local, Path}\fR
367 Does a redirect to the same Scheme://Host:Port/Path as we
368 currently are executing in.
369
370
371
372
373 .TP
374 \fB{get_more, Cont, State}\fR
375 When we are receiving large POSTs we can return this value
376 and be invoked again when more Data arrives.
377
378
379 .TP
380 \fB[ListOfValues]\fR
381 It is possible to return a list of the above defined
382 return values.
383
384
385
386
387 .SH AUTHOR
388 Written by Claes Wikstrom
389 .SH "SEE ALSO"
390 .BR yaws.conf (5)
391 .BR erl (1)
392
Something went wrong with that request. Please try again.