% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(http/js_write): Utilities for including JavaScript}

\label{sec:jswrite}

This library is a supplement to \file{library(http/html_write)} for producing
JavaScript fragments. Its main role is to be able to call JavaScript
functions with valid arguments constructed from Prolog data. For
example, suppose you want to call a JavaScript functions to process a
list of names represented as Prolog atoms. This can be done using the
call below, while without this library you would have to be careful to
properly escape special characters.

\begin{code}
numbers_script(Names) -->
    html(script(type('text/javascript'),
         [ \js_call('ProcessNumbers'(Names)
         ]),
\end{code}

The accepted arguments are described with \dcgref{js_expression}{1}.\vspace{0.7cm}

\begin{description}
    \dcg[det]{js_script}{1}{+Content}
Generate a JavaScript \const{script} element with the given content.

    \predicate[det]{javascript}{4}{+Content, +Vars, +VarDict, -DOM}
Quasi quotation parser for JavaScript that allows for embedding
Prolog variables to substitude \textit{identifiers} in the JavaScript
snippet. Parameterizing a JavaScript string is achieved using
the JavaScript \verb$+$ operator, which results in concatenation at
the client side.

\begin{code}
    ...,
    js_script({|javascript(Id, Config)||
                $(document).ready(function() {
                   $("#"+Id).tagit(Config);
                 });
               |}),
    ...
\end{code}

The current implementation tokenizes the JavaScript input and
yields syntax errors on unterminated comments, strings, etc. No
further parsing is implemented, which makes it possible to
produce syntactically incorrect and partial JavaScript. Future
versions are likely to include a full parser, generating syntax
errors.

The parser produces a term \verb$\List$, which is suitable for
\dcgref{js_script}{1} and \dcgref{html}{1}. Embedded variables are mapped to
\verb$\js_expression(Var)$, while the remaining text is mapped to
atoms.

\begin{tags}
    \tag{To be done}
Implement a full JavaScript parser. Users should \textit{not}
rely on the ability to generate partial JavaScript
snippets.
\end{tags}

    \dcg[det]{js_call}{1}{+Term}
Emit a call to a Javascript function. The Prolog functor is the
name of the function. The arguments are converted from Prolog to
JavaScript using \dcgref{js_arg_list}{1}. Please not that Prolog functors can
be quoted atom and thus the following is legal:

\begin{code}
    ...
    html(script(type('text/javascript'),
         [ \js_call('x.y.z'(hello, 42))
         ]),
\end{code}

    \dcg[det]{js_new}{2}{+Id, +Term}
Emit a call to a Javascript object declaration. This is the same
as:

\begin{code}
['var ', Id, ' = new ', \js_call(Term)]
\end{code}

    \dcg[det]{js_arg_list}{1}{+Expressions:list}
Write javascript (function) arguments. This writes "(", Arg,
..., ")". See \dcgref{js_expression}{1} for valid argument values.

    \dcg[det]{js_expression}{1}{+Expression}
Emit a single JSON argument. \arg{Expression} is one of:

\begin{description}
    \item[Variable] 
Emitted as Javascript \const{null}
    \item[List] 
Produces a Javascript list, where each element is processed
by this library.
    \item[\const{object(Attributes)}] 
Where Attributes is a Key-Value list where each pair can be
written as Key-Value, Key=Value or Key(Value), accomodating
all common constructs for this used in Prolog.
\$ \{ K:V, ... \}
Same as \verb$object(Attributes)$, providing a more JavaScript-like
syntax. This may be useful if the object appears literally
in the source-code, but is generally less friendlyto produce
as a result from a computation.
    \item[Dict] 
Emit a dict as a JSON object using \predref{json_write_dict}{3}.
    \item[\const{json(Term)}] 
Emits a term using \predref{json_write}{3}.
    \item[@(Atom)] 
Emits these constants without quotes. Normally used for the
symbols \const{true}, \const{false} and \const{null}, but can also be use for
emitting JavaScript symbols (i.e. function- or variable
names).
    \item[Number] 
Emited literally
    \item[\const{symbol(Atom)}] 
Synonym for @(Atom). Deprecated.
    \item[Atom or String] 
Emitted as quoted JavaScript string.
\end{description}

    \dcg[semidet]{js_arg}{1}{+Expression}
Same as \dcgref{js_expression}{1}, but fails if \arg{Expression} is invalid,
where \dcgref{js_expression}{1} raises an error.

\begin{tags}
    \tag{deprecated}
New code should use \dcgref{js_expression}{1}.
\end{tags}
\end{description}