0n4u/doc/actions.tex

\section{Actions}

\paragraph{}
{\bf \#action} is the basic record for all actions. It means that each action
has {\bf \#action} as its ancestor.

\vspace{1\baselineskip}
\begin{lstlisting}
    #action { ancestor,
              target,
              module,
              actions,
              source=[] }.
\end{lstlisting}
\vspace{1\baselineskip}

{\bf target} specifies an element where this action will arise.

\subsection{JavaScript DSL {\bf \#jq}}
JavaScript query selector action mimics JavaScript calls and assignments.
Specific action may be performed depending on filling{\bf property} or {\bf method} fields.

\vspace{1\baselineskip}
\begin{lstlisting}
    -record(jq, {?ACTION_BASE(action_jq),
            property,
            method,
            args=[],
            right }).
\end{lstlisting}
\vspace{1\baselineskip}

Here is an example of method calls:
\begin{lstlisting}
    wf:wire(#jq{target=n2ostatus,method=[show,select]}).
\end{lstlisting}
unfolded to calls:
\begin{lstlisting}
    document.querySelector('#n2ostatus').show();
    document.querySelector('#n2ostatus').select();
\end{lstlisting}
\vspace{1\baselineskip}

And here is example of property chained assignments:
\begin{lstlisting}
    wf:wire(#jq{target=history,property=scrollTop,
        right=#jq{target=history,property=scrollHeight}}).
\end{lstlisting}
which transforms to:
\begin{lstlisting}
    document.querySelector('#history').scrollTop =
        document.querySelector('#history').scrollHeight;
\end{lstlisting}
\vspace{1\baselineskip}
Part of N2O API is implemented using \#jq actions (updates and redirect).
This action is introduced as transitional in order to move
from Nitrogen DSL to using pure JavaScript transformations.

\subsection*{Event Actions}
Objects passed over WebSockets channel from server to client are called {\bf actions}.
Objects passed over the same channel from client to server are called {\bf events}. However
events themselves are bound to HTML elements with {\bf addEventListener} and in order to perform these bindings,
actions should be sent first. Such actions are called {\bf event actions}. There are three types of event actions.

\subsection{Page Events {\bf \#event}}
Page events are regular events routed to the calling module. Postback field is used as the main
routing argument for {\bf event} module function. By providing {\bf source} elements list you specify
HTML controls values sent to the server and accessed with {\bf wf:q} accessor from the page context.
Page events are normally generated by active elements like {\bf \#button}, {\bf \#link},
{\bf \#textbox}, {\bf \#dropdown}, {\bf \#select}, {\bf \#radio} and others elements
contain postback field.

\paragraph{}
Control events are used to solve the need of element writers. When you develop your
own control elements, you usually want events to be routed not to page but to element module.
Control events were introduced for this purpose.

\subsection{API Events {\bf \#api}}
When you need to call Erlang function from JavaScript directly you should use API events.
API events are routed to page module with {\bf api\_event/3} function. API events were
used in {\bf AVZ} authorization library. Here is an example of how JSON login could be
implemented using {\bf api\_event}:

\vspace{1\baselineskip}
\begin{lstlisting}
    api_event(appLogin, Args, Term) ->
        Struct = n2o_json:decode(Args),
        wf:info(?MODULE, "Granted Access"),
        wf:redirect("/account").
\end{lstlisting}
\vspace{1\baselineskip}
And from JavaScript you call it like this:
\vspace{1\baselineskip}
\begin{lstlisting}
    document.appLogin(JSON.stringify(response));
\end{lstlisting}
\vspace{1\baselineskip}
All API events are bound to root of the HTML document.


\subsection{Message Box {\bf \#alert}}
Message box {\bf alert} is a very simple dialog that could be used for client debugging.
You can use {\bf console.log} along with alerts.

\vspace{1\baselineskip}
\begin{lstlisting}
    event({debug,Var}) ->
        wf:wire(#alert{text="Debug: " ++ wf:to_list(Var)}),
\end{lstlisting}

\subsection{Confirmation Box {\bf \#confirm}}
You can use confirmation boxes for simple approval with JavaScript {\bf confirm} dialogs.
You should extend this action in order to build custom dialogs. Confirmation box is just an example of how to
organize this type of logic.

\vspace{1\baselineskip}
\begin{lstlisting}
    event(confirm) ->
        wf:wire(#confirm{text="Are you happy?",postback=continue}),

    event(continue) -> wf:info(?MODULE, "Yes, you're right!", []);
\end{lstlisting}
\vspace{1\baselineskip}