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



\subsection{library(http/html_head): Automatic inclusion of CSS and scripts links}

\label{sec:htmlhead}

\begin{tags}
\mtag{To be done}- Possibly we should add \dcgref{img}{2} to include images from symbolic
path notation. \\- It would be nice if the HTTP file server could use our location
declarations.
\end{tags}

This library allows for abstract declaration of available CSS and
Javascript resources and their dependencies using \predref{html_resource}{2}. Based
on these declarations, html generating code can declare that it depends
on specific CSS or Javascript functionality, after which this library
ensures that the proper links appear in the HTML head. The
implementation is based on mail system implemented by \predref{html_post}{2} of
library \file{html_write.pl}.

Declarations come in two forms. First of all http locations are declared
using the \file{http_path.pl} library. Second, \predref{html_resource}{2} specifies HTML
resources to be used in the \const{head} and their dependencies. Resources are
currently limited to Javascript files (.js) and style sheets (.css). It
is trivial to add support for other material in the head. See
\dcgref{html_include}{1}.

For usage in HTML generation, there is the DCG rule \dcgref{html_requires}{1}
that demands named resources in the HTML head.

\subsubsection{About resource ordering}

\label{sec:html-resource-ordering}

All calls to \dcgref{html_requires}{1} for the page are collected and duplicates
are removed. Next, the following steps are taken:

\begin{enumerate}
    \item Add all dependencies to the set
    \item Replace multiple members by `aggregate' scripts or css files.
see \predref{use_agregates}{4}.
    \item Order all resources by demanding that their dependencies
preceede the resource itself. Note that the ordering of
resources in the dependency list is \textbf{ignored}. This implies
that if the order matters the dependency list must be split
and only the primary dependency must be added.
\end{enumerate}

\subsubsection{Debugging dependencies}

\label{sec:html-resource-debugging}

Use \Sdirective{} \verb$debug(html(script))$. to see the requested and final set of
resources. All declared resources are in \predref{html_resource}{3}. The \predref{edit}{1}
command recognises the names of HTML resources.

\subsubsection{Predicates}

\label{sec:html-resource-predicates}\vspace{0.7cm}

\begin{description}
    \predicate[det]{html_resource}{2}{+About, +Properties}
Register an HTML head resource. \arg{About} is either an atom that
specifies an HTTP location or a term Alias(Sub). This works
similar to \predref{absolute_file_name}{2}. See \qpredref{http}{location_path}{2} for
details. Recognised properties are:

\begin{description}
    \termitem{requires}{+Requirements}
Other required script and css files. If this is a plain
file name, it is interpreted relative to the declared
resource. \arg{Requirements} can be a list, which is equivalent
to multiple requires properties.
    \termitem{virtual}{+Bool}
If \const{true} (default \const{false}), do not include \arg{About} itself,
but only its dependencies. This allows for defining an
alias for one or more resources.
    \termitem{ordered}{+Bool}
Defines that the list of requirements is ordered, which
means that each requirement in the list depends on its
predecessor.
    \termitem{aggregate}{+List}
States that \arg{About} is an aggregate of the resources in
\arg{List}. This means that if both \arg{About} and one of the
elements of \arg{List} appears in the dependencies, \arg{About}
is kept and the smaller one is dropped. If there are a
number of dependencies on the small members, these are
replaced with dependency on the big (aggregate) one,
for example, to specify that a big javascript is
actually the composition of a number of smaller ones.
    \termitem{mime_type}{-Mime}
May be specified for non-virtual resources to specify
the mime-type of the resource. By default, the mime
type is derived from the file name using
\predref{file_mime_type}{2}.
\end{description}

Registering the same \arg{About} multiple times extends the properties
defined for \arg{About}. In particular, this allows for adding
additional dependencies to a (virtual) resource.

    \predicate[nondet]{html_current_resource}{1}{?About}
True when \arg{About} is a currently known resource.

    \dcg[det]{html_requires}{1}{+ResourceOrList}
Include \arg{ResourceOrList} and all dependencies derived from it and
add them to the HTML \const{head} using \predref{html_post}{2}. The actual
dependencies are computed during the HTML output phase by
\dcgref{html_insert_resource}{1}.

    \dcg[det]{html_insert_resource}{1}{+ResourceOrList}
Actually include HTML head resources. Called through
\dcgref{html_post}{2} from \dcgref{html_requires}{1} after rewrite by
\predref{html_head_expansion}{2}. We are guaranteed we will only get one
call that is passed a flat list of requested requirements. We
have three jobs:

\begin{enumerate}
    \item Figure out all indirect requirements
    \item See whether we can use any `aggregate' resources
    \item Put required resources before their requiree.
\end{enumerate}

    \dcg[semidet,multifile]{mime_include}{2}{+Mime, +Path}
Hook called to include a link to an HTML resource of type \arg{Mime}
into the HTML head. The \arg{Mime} type is computed from \arg{Path} using
\predref{file_mime_type}{2}. If the hook fails, two built-in rules for
\verb$text/css$ and \verb$text/javascript$ are tried. For example, to
include a =.pl= files as a Prolog script, use:

\begin{code}
:- multifile
    html_head:mime_include//2.

html_head:mime_include(text/'x-prolog', Path) --> !,
    html(script([ type('text/x-prolog'),
                  src(Path)
                ],  [])).
\end{code}

\end{description}