api.tex

\section{API}

\subsection{Update DOM \bf{wf:update}}
You can update part of the page or DOM element with a given
element or even raw HTML. You can also use {\bf \#dtl}
or {\bf \#eex} template elements for HTML generation to
replace DOM. Here is an example of simple {\bf \#span} element
with an HTML counterpart:

\vspace{1\baselineskip}
\begin{lstlisting}
    wf:update(history,[#span{body="Hello"}]).
\end{lstlisting}
\vspace{1\baselineskip}

It generates DOM update script and sends it to
WebSocket channel for evaluation:

\vspace{1\baselineskip}
\begin{lstlisting}
    document.querySelector('#history')
            .outerHTML = '<span>Hello</span>';
\end{lstlisting}
\vspace{1\baselineskip}

Companions are also provided for updating head and tail
of the elements list: {\bf wf:insert\_top/2} and
{\bf wf:insert\_bottom/2}. These are translated to appropriate
JavaScript methods {\bf insertBefore} and {\bf appendChild} during rendering.

\vspace{1\baselineskip}
\begin{lstlisting}
    wf:insert_top(history,
        #panel{id=banner, body= [
            #span{ id=text,
                   body = wf:f("User ~s logged in.",[wf:user()]) },
            #button{id=logout, body="Logout", postback=logout },
            #br{} ]}),
\end{lstlisting}
\vspace{1\baselineskip}

Remember to envelop all elements in common root element before inserts.

\paragraph{}
For relative updates use {\bf wf:insert\_before/2} and {\bf wf:insert\_after/2}.
To remove an element use {\bf wf:remove/2}.
Updates are covered in detail in {\bf Section 7}.

\paragraph{\bf Element Naming}
You can specify element's id with Erlang atoms,
lists or binaries. During rendering the value will be converted
with {\bf wf:to\_list}. Conversion will be consistent only if you use atoms.
Otherwise you need to care about illegal symbols for element accessors.

\paragraph{}
During page updates you can create additional elements with
runtime generated event handlers, perform HTML rendering for
template elements or even use distributed map/reduce to calculate view.
You have to be aware that heavy operations will consume
more power in the browser, but you can save it by rendering
HTML on server-side. All DOM updates API works both using
JavaScript/OTP and server pages.

\paragraph{}
List of elements you can use is given in {\bf Section 7}. You can also create
your own elements with a custom render function.

\subsection{Wire JavaScript \bf{wf:wire}}
Just like HTML is generated from Elements, Actions are rendered into
JavaScript to handle events raised in the browser. Actions are always
transformed into JavaScript and sent through WebSockets pipe.

\subsection*{Direct Wiring}
There are two types of actions. First class are direct JavaScript
strings provided directly as Erlang lists or via JavaScript/OTP
transformations.

\vspace{1\baselineskip}
\begin{lstlisting}
    wf:wire("window.location='http://synrc.com'").
\end{lstlisting}

\subsection*{Actions Render}
Second class actions are in fact Erlang records
rendered during page load, server events or client events.

\vspace{1\baselineskip}
\begin{lstlisting}
    wf:wire(#alert{text="Hello!"}).
\end{lstlisting}
\vspace{1\baselineskip}

However basic N2O actions that are part of N2O API, {\bf wf:update} and {\bf wf:redirect},
are implemented as Erlang records as given in the example. If you need deferred
rendering of JavaScript, you can use Erlang records instead of direct wiring with
Erlang lists or JavaScript/OTP.

\paragraph{}
Any action, wired with {\bf wf:wire}, is enveloped in {\bf \#wire\{actions=[]\}},
which is also an action capable of polymorphic rendering of custom or built-in actions, specified in the list.
Following nested action embedding is also valid:

\vspace{1\baselineskip}
\begin{lstlisting}
    wf:wire(#wire{actions=[#alert{text="N2O"}]}).
\end{lstlisting}
\vspace{1\baselineskip}

\subsection{Async Processes {\bf wf:async} and {\bf wf:flush}}
These create Erlang processes, which communicate with the primary page
process by sending messages. {\bf wf:flush} should be called to redirect all updates and
wire actions to the page process.
Usually you send messages to Async processes over N2O
message bus, but you can use any of these options.

\vspace{1\baselineskip}
\begin{lstlisting}
    body() ->
        {ok,Pid} = wf:async("looper",fun() -> loop(0) end),
      [ #span   { id=counter },
        #button { id=sendButton, body="Send", postback={inc,Pid} } ].

    event({inc,Pid}) -> wf:reg(room), Pid ! inc.

    loop(Counter) ->
        Body = wf:to_list(Counter),
        receive inc -> 
             wf:update(counter, #span { id=counter, body=Body }),
             wf:flush(room) end, loop(Counter+1).
\end{lstlisting}

\paragraph{\bf Process Naming.} The name of async process is globally unique. There are two
versions, {\bf wf:async/1} and {\bf wf:async/2}. In the given example
the name of async process is specified as ``looper'', otherwise,
if the first parameter was not specified, the default name ``comet'' will be used.

\subsection{Message Bus {\bf wf:reg} and {\bf wf:send}}
N2O uses GProc process registry for managing async processes pools.
It is used as a PubSub message bus for N2O communications, but later you can switch to robust RabbitMQ.
You can associate a process with the pool with {\bf wf:reg} and send a message to the pool with {\bf wf:send}.

\vspace{1\baselineskip}
\begin{lstlisting}
    loop() ->
        receive M ->
            wf:info(?MODULE, "P: ~p, M: ~p",[self(),M]) end, loop().
\end{lstlisting}

Now you can test it

\begin{lstlisting}
    > spawn(fun() -> wf:reg(topic), loop() end).
    > spawn(fun() -> wf:reg(topic), loop() end).
    > wf:send(topic,"Hello").
\end{lstlisting}

It should print in REPL something like:

\begin{lstlisting}
    > [info] P: <0.2012.0>, M: "Hello"
    > [info] P: <0.2015.0>, M: "Hello"
\end{lstlisting}

\subsection{Parse URL and Context parameters {\bf wf:q} and {\bf wf:qs}}
These are used to extract URL parameters or read from the process context. {\bf wf:q} extracts variables
from the context stored by controls postbacks. {\bf wf:qs} extracts variables from HTTP forms.

\subsection{Render {\bf wf:render}}
Render elements or actions with common render.

\subsection{Redirects {\bf wf:redirect}}
Redirects are implemented not with HTTP headers, but with JavaScript action modifying {\bf window.location}.
This saves login context information which is sent in the first packet upon establishing a WebSocket connection.

\subsection{Session Information {\bf wf:session}}
Store any session information in ETS tables. Use {\bf wf:user}, {\bf wf:role} for
login and authorization. Consult {\bf AVZ} library documentation.

\subsection{Bridge information {\bf wf:header} and {\bf wf:cookie}}
You can read and issue cookie and headers information using internal Web-Server routines.
You can also read peer IP with {\bf wf:peer}. Usually you do Bridge operations
inside handlers or endpoints.

\begin{lstlisting}
    wf:cookies_req(?REQ),
    wf:cookie_req(Name,Value,Path,TTL,Req)
\end{lstlisting}

You can set cookies for the page using public cookies API during initial page rendering.

\begin{lstlisting}
    body() -> wf:cookie("user","Joe"), [].
\end{lstlisting}

You should use wiring inside WebSocket events:

\begin{lstlisting}
    event(_) ->
        wf:wire(wf:f("document.cookie='~s=~s'",["user","Joe"])).
\end{lstlisting}