Provided by: yaws_1.57-1_i386 bug

NAME

       yaws_api - api available to yaws web server programmers

SYNOPSIS

       yaws_api:Function(...)

DESCRIPTION

       This  is  the  api available to yaws web server programmers. The erlang
       module yaws_api contains a wide variety of functions that can  be  used
       inside yaws pages.

       Each  chunk  of  yaws  code  is  executed  while the yaws page is being
       delivered from the server. We give a very simple example here  to  show
       the basic idea. Imagine the following html code:

       <html>
       <body>

       <h1> Header 1</h1>

       <erl>
       out(Arg) ->
           {html, "<p> Insert this text into the document"}.
       </erl>

       </body>
       </html>

       The  out(Arg)  function  is supplied one argument, an #arg{} structure.
       We have the following relevant record definitions:

       -record(arg, {
              clisock,        %% the socket leading to the peer client
              headers,        %% headers
              req,            %% request
              clidata,        %% The client data (as a binary in POST requests)
              server_path,    %% The normalized server path
              querydata,      %% Was the URL on the form of ...?query (GET reqs)
              appmoddata,     %% the remainder of the path up to the query
              docroot,        %% wheres the data
              fullpath,       %% full path to yaws file
              cont,          %% Continuation for chunked multipart uploads
              state,          %% State for use by users of the out/1 callback
              pid,            %% pid of the yaws worker process
              opaque,         %% useful to pass static data
              appmod_prepath, %% path in front of: <appmod><appmoddata>
              pathinfo        %% Set to d/e when calling c.yaws for the request
                                 %% http://some.host/a/b/c.yaws/d/e
             }).

       The headers argument is also a record:

       -record(headers, {
                 connection,
                 accept,
                 host,
                 if_modified_since,
                 if_match,
                 if_none_match,
                 if_range,
                 if_unmodified_since,
                 range,
                 referer,
                 user_agent,
                 accept_ranges,
                 cookie = [],
                 keep_alive,
                 content_length,
                 authorization,
                 other = []   %% misc other headers
                }).

       it likes. We have the following functions to aid that generation.

API

       ssi(DocRoot, ListOfFiles)
              Server side include.  Just  include  the  files  as  is  in  the
              document.  The  files  will not be parsed and searched for <erl>
              tags.

       pre_ssi_files(DocRoot, ListOfFiles) ->
              Server side include of pre indented code.   The  data  in  Files
              will  be included but contained in a <pre> tag. The data will be
              htmlized.

       pre_ssi_string(String)
              Include htmlized content from String.

       f(Fmt, Args)
              The   equivalent   of   io_lib:format/2.   This   function    is
              automatically  -included in all erlang code which is a part of a
              yaws page.

       htmlize(Binary)
              Htmlize a binary object.

       htmlize_l(DeepList)
              Htmlize any deep list of chars and binaries.

       setcookie(Name, Value, [Path, [ Expire, [Domain , [Secure]]]])
              Sets a cookie to the browser.

       find_cookie_val(Cookie, Header)
              This function can be used  to  search  for  a  cookie  that  was
              previously  set by setcookie/2-6. For example if we set a cookie
              as yaws_api:setcookie("sid",SomeRandomSid) , then on  subsequent
              requests      from      the     browser     we     can     call:
              find_cookie("sid",(Arg#arg.headers)#headers.cookie)

              The function returns [] if no cookie was  found,  otherwise  the
              actual cookie is returned as a string.

       redirect(Url
              This  function  generates  a  redirect  to the browser.  It will
              clear any previously set headers. So to generate a redirect  and
              set  a  cookie,  we need to set the cookie after the redirect as
              in:
              out(Arg) ->
                ... do some stuff

                Ret = [{redirect, "http://www.somewhere.com"},
                        setcookie("sid", Random)
                      ].

       get_line(String)
              This function is convenient when getting \r\n  terminated  lines
              from a stream of data. It returns:

              {line, Line, Tail} or {lastline, Line, Tail}

              The function handles multilines as defined in e.g. SMTP or HTTP

       mime_type(FileName)
              Returns the mime type as defined by the extension of FileName

       stream_chunk_deliver(YawsPid, Data)
              When  a  yaws  function needs to deliver chunks of data which it
              gets from a process. The other process can call this function to
              deliver  these  chunks. It requires the out/1 function to return
              the  value  {streamcontent,  MimeType,  FirstChunk}   to   work.
              YawsPid is the process identifier of the yaws process delivering
              the original The Pid must typically be passed (somehow)  to  the
              producer of the stream.

       stream_chunk_deliver_blocking(YawsPid, Data)
              A  syncronous  verion  of  the  above  function. This syncronous
              version must always be used when the producer of the  stream  is
              faster  than  the  consumer.  This is usually the case since the
              client is the WWW browser.

       stream_chunk_end(YawsPid)
              When the process discussed above is  done  delivering  data,  it
              must  call  this  function  to  let  the yaws content delivering
              process finish up the HTTP transaction.

       parse_query(Arg)
              This function will parse the query part of  the  URL.   It  will
              return  a  {Key,  Value} list of the items supplied in the query
              part of the URL.

       queryvar(Arg, VarName)
              This function is automatically included from yaws_api in all
               .yaws pages. It is  used  to  search  for  a  variable  in  the
              querypart of the url. Returns {ok, Val} or undefined.

       parse_post(Arg)
              This  function  will  parse  the  POST data as supplied from the
              browser.  It will return a {Key, Value} list of the items set by
              the browser.

       postvar(Arg, VarName)
              This function is automatically included from yaws_api in all
               .yaws  pages. It is used to search for a variable in the POSTed
              data from the client. Returns {ok, Val} or undefined.

       parse_multipart_post(Arg)

              If the browser has set the  Content-Type  header  to  the  value
              "multipart/form-data",  which is the case when the browser wants
              to upload a file to the server the following happens:

              If the function returns {result, Res} no  more  data  will  come
              from the browser.

              If  the  function  returns  {cont,  Cont,  Res} the browser will
              supply more data. (The file was to big to come in one read)

              This indicates that there is more data to  come  and  the  out/1
              function   should  return  {get_more,  Cont,  User_state}  where
              User_state might usefully be a File Descriptor.

              The  Res  value  is  a  list  of  either:  {header,  Header}   |
              {part_body, Binary} | {body, Binary}

              Example usage could be:
               <erl>

               out(A) ->
                      case yaws_api:parse_multipart_post(A) of
                           {cont, Cont, Res} ->
                                  St = handle_res(A, Res),
                                  {get_more, Cont, St};
                           {result, Res} ->
                                  handle_res(A, Res),
                                  {html, f("<pre>Done </pre>",[])}
                      end.

               handle_res(A, [{head, Name}|T]) ->
                    io:format("head:~p~n",[Name]),
                    handle_res(A, T);
               handle_res(A, [{part_body, Data}|T]) ->
                    io:format("part_body:~p~n",[Data]),
                    handle_res(A, T);
               handle_res(A, [{body, Data}|T]) ->
                    io:format("body:~p~n",[Data]),
                    handle_res(A, T);
               handle_res(A, []) ->
                    io:format("End_res~n").

               </erl>

       new_cookie_session(Opaque)
              Create  a new cookie based session, the yaws system will set the
              cookie. The new randomgenerated cookie  is  returned  from  this
              function.  The  Opaque argument will typically contain user data
              such as username and password

       new_cookie_session(Opaque, TTL)
              As above, but allows to set a session specific  time-out  value,
              overriding teh system specified time-out value.

       cookieval_to_opaque(CookieVal)

       print_cookie_sessions()

       replace_cookie_session(Cookie, NewOpaque)

       delete_cookie_session(Cookie)

       setconf(Gconf, Groups)
              This function is intended for embedded mode in yaws. It makes it
              possible to load a yaws configuration from another  data  source
              than  /etc/yaws.conf,  such  as  a database.  If yaws is started
              with the environment {embedded, true}, yaws will start  with  an
              empty  default configuration, and wait for some other program to
              execute a setconf/2 The Gconf is a #gconf{} record and the Group
              variable  is  a  list of lists of #sconf{} records. Each sublist
              must contain #sconf{}  records  with  the  same  IP/Port  listen
              address.

       url_decode(Str)
              Decode url-encoded string. A URL ncoded string is a string where
              all  alfa  numeric  characters  and  the  the  character  _  are
              preserved  and  all other characters are encode as "%XY" where X
              and Y are the hex values of the least respective most significat
              4 bits in the 8 bit character.

       url_encode(Str)
              Url-encodes  a  string.  All  URLs in HTML documents must be URL
              encoded.

       reformat_header(H)
              Returns a list of reformated  header  values  from  a  #header{}
              record. The return list is suitable for retransmit.

       request_url(ARG)
              Return  the  url  as  requested by the client. Return value is a
              #url{} record as defined in yaws_api.hrl

       parse_url(Str)
              Parse URL in a string, returns a #url record

       format_url(UrlRecord)
              Takes a #url record a formats the Url as a string

       call_cgi(Arg, Scriptfilename)
              Calls an executable CGI script, given by its full path.  Used to
              make  ‘.yaws’  wrappers for CGI programs.  This function usually
              returns streamcontent.

       call_cgi(Arg, Exefilename, Scriptfilename)
              Like before, but calls Exefilename to handle  the  script.   The
              file  name  of  the script is handed to the executable via a CGI
              meta variable.

RETURN VALUES from out/1

       The out/1 function can return different values to control the  behavior
       of the server.

       {html, DeepList}
              This  assumes  that  DeepList  is formatted HTML code.  The code
              will be inserted in the page.

       {ehtml, Term}
              This will transform the erlang term Term into a stream  of  HTML
              content. The basic syntax of Term is

              EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
                      binary() | character()
              Tag      = atom()
              Attrs = [{Key, Value}]  or {EventTag, {jscall, FunName, [Args]}}
              Key      = atom()
              Value = string()
              Body  = EHTML

              For example, {p, [], "Howdy"} expands into "<p>Howdy</p> and

              {form, [{action, "a.yaws"}],
                 {input, [{type,text}]}}

              expands into

              <form action="a.yaws"
                <input type="text">
              </form>

              It  may  be more convenient to generate erlang tuples than plain
              html code.

       {content, MimeType, Content}
              This function  will  make  the  web  server  generate  different
              content  than  HTML. This return value is only allowed in a yaws
              file which has only one <erl> </erl> part and no html  parts  at
              all.

       {streamcontent, MimeType, FirstChunk}
              This  return  value  plays  the  same role as the content return
              value above.

              However it makes it possible to stream data to the client if the
              yaws  code  doesn’t  have  access  to  all  the  data in one go.
              (Typically if a file is very large or if data arrives from  back
              end servers on the network.

       {header, H}
              Accumulates  a  HTTP header. The trailing CRNL which is supposed
              to end all HTTP headers must NOT be added. It is  added  by  the
              server.   The  following  list  of  headers  are  given  special
              treatment.

              {connection, What}

              This sets the connection header. If What is  the  special  value
              "close",  the  connection  will  be closed once the yaws page is
              delivered to the client.

              {location, Url}

              Sets the Location: header. This  header  is  typically  combined
              with the {status, 302} return value.

              {cache_control, What}

              Sets the Cache-Control: header.

              {set_cookie, Cookie}

              Prepends  a  a  Set-Cookie:  header to the list of previousy set
              Set-Cookie: headers.

              {content_type, MimeType}

              Sets the Content-Type header.

              {content_length, Len}

              Normally yaws will  ship  Yaws  pages  using  Transfer-Encoding:
              chunked. This is because we generally can’t know how long a yaws
              page will be. If we for some reason want  to  force  a  Content-
              Length:  header  (and  we  actually  do  know  the length of the
              content, we can force yaws to not ship the page chunked.

              All other headers must be added using the  normal  HTTP  syntax.
              Example:

              {header, "My-X-Header: gadong"}

       {allheaders, HeaderList}
              Will  clear all previously accumulated headers and replace them.

       {status, Code}
              Will set another HTTP status code than 200.

       break  Will stop processing of any consecutive chunks of  erl  or  html
              code in the yaws file.

       ok     Do nothing.

       {redirect, Url}
              Erase  all  previous  headers  and  accumulate a single Location
              header. Set the status code.

       {redirect_local, Path}
              Does a  redirect  to  the  same  Scheme://Host:Port/Path  as  we
              currently are executing in.

       {get_more, Cont, State}
              When  we  are receiving large POSTs we can return this value and
              be invoked again when more Data arrives.

       {page, Page}
              Make Yaws return a different page than the one being  requested.

       {page, {Options, Page}}
              Like  the  above,  but  supplying  an  additional  deep  list of
              options.  For now, the only type of option is {header,  H}  with
              the effect of accumulating the HTTP header H for page Page.

       {ssi, File, Delimiter, Bindings}
              Server  side  include  File  and  macro expansion in File.  Each
              occurence of a string, say "xyz", inside File  which  is  inside
              Delimters  is replaced with the corresponsing value in Bindings.

              Example: Delimiter = %%

              File contains the string .... %%xyz%%  .....

              Bindings contain the tuple {"xyz", "Dingbat"}

              The occurence of %%xyz%% in File will be replaced with "Dingbat"
              in the Server side included output.

              The  {ssi,  File,  Delimiter, Bindings} statement can also occur
              inside a deep ehtml structure.

       {bindings, [{Key1, Value2}, {Key2, Value2} .....]}
              Establish variable bindings that can be used in the page.

              All bindings can then be used in the rest of yaws code (in  HTML
              source and within erl tags).  In HTML source %%Key%% is expanded
              to Value and within erl tags  yaws_api:get_binding(Key)  can  be
              used to extract Value.

       {yssi, YawsFile}
              Include  a yaws file. Compile it and expand as if it had occured
              inline.

       [ListOfValues]
              It is possible to return a deep list of the above defined return
              values.   Any  occurrence of stream_content, get_more or page in
              this list is legal only if it is the last position of the  list.

AUTHOR

       Written by Claes Wikstrom

SEE ALSO

       yaws.conf(5) erl(1)

                                                                   YAWS_API(5)