Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 416 lines (311 sloc) 9.674 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
c4523b3 @klacke ""
authored
193 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
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
c4523b3 @klacke ""
authored
197
198 .TP
199 \fBparse_multipart_post(Arg)\fR
200
abc3a43 @klacke documented yaws_api
authored
201 If the browser has set the Content-Type header to the value
202 "multipart/form-data", which is the case when the browser
203 wants to upload a file to the server the following happens:
204
205
206 If the function returns \fB{result, Res}\fR no more data
207 will come from the browser.
208
209 If the function returns \fB{cont, Cont, Res}\fR the browser
210 will supply more data. (The file was to big to come in one read)
211
212 This indicates that there is more data to come and the out/1 function
213 should return {get_more, Cont, User_state} where User_state might
214 usefully be a File Descriptor.
215
216
217 The Res value is a list of either:
218 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
219
220
221 Example usage could be:
222 \fI
223 .nf
224 <erl>
225
226 out(A) ->
c4523b3 @klacke ""
authored
227 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
228 {cont, Cont, Res} ->
229 St = handle_res(A, Res),
230 {get_more, Cont, St};
231 {result, Res} ->
232 handle_res(A, Res),
233 {html, f("<pre>Done </pre>",[])}
234 end.
235
236 handle_res(A, [{head, Name}|T]) ->
237 io:format("head:~p~n",[Name]),
238 handle_res(A, T);
239 handle_res(A, [{part_body, Data}|T]) ->
240 io:format("part_body:~p~n",[Data]),
241 handle_res(A, T);
242 handle_res(A, [{body, Data}|T]) ->
243 io:format("body:~p~n",[Data]),
244 handle_res(A, T);
245 handle_res(A, []) ->
246 io:format("End_res~n").
247
248 </erl>
249 .fi
250 \fR
251
252
253
254
255 .TP
87b1456 @klacke wrote the shopppingcart example
authored
256 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
257 Create a new cookie based session, the yaws system will set the
87b1456 @klacke wrote the shopppingcart example
authored
258 cookie. The new randomgenerated cookie is returned from this
259 function. The Opaque argument will typically contain user data
260 such as username and password
abc3a43 @klacke documented yaws_api
authored
261
262 .TP
87b1456 @klacke wrote the shopppingcart example
authored
263 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
264
265 .TP
266 \fBprint_cookie_sessions() \fR
267
87b1456 @klacke wrote the shopppingcart example
authored
268
269 .TP
270 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
271
abc3a43 @klacke documented yaws_api
authored
272 .TP
87b1456 @klacke wrote the shopppingcart example
authored
273 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
274
275
50a7ab2 @klacke added support/docs for embedded mode
authored
276 .TP
277 \fBsetconf(Gconf, Groups)\fR
278 This function is intended for embedded mode in yaws. It makes it possible
279 to load a yaws configuration from another data source than /etc/yaws.conf, such
280 as a database.
281 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
282 start with an empty default configuration, and wait for some other
283 program to execute a \fIsetconf/2\fR
284 The Gconf is a \fI#gconf{}\fR record and the Group variable is
285 a list of lists of \fI#sconf{}\fR records. Each sublist must
286 contain \fI#sconf{}\fR records with the same IP/Port listen address.
287
abc3a43 @klacke documented yaws_api
authored
288
289 .SH RETURN VALUES from out/1
290 .PP
291 The out/1 function can return different values to control the behavior
292 of the server.
293
294 .TP
295 \fB{html, DeepList}\fB
296 This assumes that DeepList is formatted HTML code.
297 The code will be inserted in the page.
298
299 .TP
300 \fB{ehtml, Term}\fR
301 This will transform the erlang term Term into a
302 stream of HTML content. The basic syntax of Term
303 is
304
305 \fI
306 .nf
307 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
308 binary() | character()
309 Tag = atom()
310 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
311 Key = atom()
312 Value = string()
313 Body = EHTML
314 .fi
315 \fR
316
317
318 For example, \fI{p, [], "Howdy"}\fR expand into
319 "<p>Howdy</p> and
320
321 \fI
322 .nf
323 {form, [{action, "a.yaws"}],
324 {input, [{type,text}]}}
325
326 .fi
327 \fR
328
329 expands into
330
331 \fI
332 .nf
333 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
334 <input type="text">
335 </form>
abc3a43 @klacke documented yaws_api
authored
336 .fi
337 \fR
338
339 It may be more convenient to generate erlang tuples
340 than plain html code.
341
342 .TP
343 \fB{content, MimeType, Content}\fR
344 This function will make the web server generate
345 different content than HTML. This return value is only allowed
346 in a yaws file which has only one <erl> </erl> part and no
347 html parts at all.
348
349
350 .TP
351 \fB{streamcontent, MimeType, FirstChunk}\fR
352 This return value plays the same role as the \fIcontent\fR return
353 value above.
354 However it makes it possible to stream data to the client
355 if the yaws code doesn't have access to all the data in one go. (Typically
356 if a file is very large or if data arrives from back end servers on the network.
357
358 .TP
359 \fB{header, H}\fR
360 Accumulates a HTTP header. Used by for example the \fBsetcookie/2-6\fR
361 function.
362
363 .TP
364 \fB{allheaders, HeaderList}\fB
365 Will clear all previously accumulated headers and replace them.
366
367
368 .TP
369 \fB{status, Code}\fR
370 Will set another HTTP status code than 200.
371
372
373 .TP
374 \fBbreak\fR
375 Will stop processing of any consecutive chunks of erl or html code
376 in the yaws file.
377
378 .TP
379 \fBok\fR
380 Do nothing.
381
382
383 .TP
384 \fB{redirect, Url}\fR
385 Erase all previous headers and accumulate a single
386 Location header. Set the status code.
387
388 .TP
389 \fB{redirect_local, Path}\fR
390 Does a redirect to the same Scheme://Host:Port/Path as we
391 currently are executing in.
392
393
394
395
396 .TP
397 \fB{get_more, Cont, State}\fR
398 When we are receiving large POSTs we can return this value
399 and be invoked again when more Data arrives.
400
401
402 .TP
403 \fB[ListOfValues]\fR
404 It is possible to return a list of the above defined
405 return values.
406
407
408
409
410 .SH AUTHOR
411 Written by Claes Wikstrom
412 .SH "SEE ALSO"
413 .BR yaws.conf (5)
414 .BR erl (1)
415
Something went wrong with that request. Please try again.