\documentclass{article}
\usepackage{ulem}
\pagestyle{headings}
\begin{document}
\part{ Documentation of Horde Ajax Applications mostly from poking around existing examples.}
The Horde Ajax framework facilitates creating javascript-heavy single page applications but is also useful in other contexts.\newline
It contains of a horde-wide server-side entry point ajax.php and per-application definitions which handlers are used.\newline
On the client side, HordeCore\footnote{http://example.com/index.php?page=HordeCore}.js provides the tools to call these endpoints and automatically add security tokens to the request.

\section{ Convention}
\$app (lowercase, for example "passwd")\newline
\$App (First Uppercase, for example "Passwd")

\section{ Javascript libraries used}
JavaScript for "dynamic" and "traditional" mode uses PrototypeJS\footnote{http://api.prototypejs.org/}\newline
JavaScript for "smartmobile" mode uses jQuery Mobile\footnote{http://jquerymobile.com/}

\subsection{ Using jquery alongside prototype}
This is generally not accepted upstream.\newline
jQuery can be made coexist with dynamic/traditional mode's PrototypeJS

For non-upstream custom code:

\begin{verbatim}

var $j = jQuery.noConflict();
$j(document).ready(
/* Do jquery stuff here. $.* is prototype, $j.* is jQuery. Some plugins may not like this, but DataTables, JQuery UI and mainstream stuff work */
);
\end{verbatim}

\section{ Files and Classes of a Horde Ajax Application}
\subsection{ Horde\_Ajax\_Application class}
Bare Minimum for a Horde Ajax Application (on top of a skeleton Horde\_Registry\_Application):\newline
A File \$app/lib/Ajax/Application.php with a class

\begin{verbatim}

<?php
// phpdoc omitted
class $App_Ajax_Application extends Horde_Core_Ajax_Application {}
?>
\end{verbatim}

Horde\_Core\_Ajax\_Application documentation\footnote{http://dev.horde.org/api/master/lib/Core/classes/Horde\_Core\_Ajax\_Application.html}

\subsection{ Making an ajax call to Horde}
Implement \$App\_Ajax\_Application and load at least one handler class \$App\_Ajax\_Application\_Handler in the \_init function.\newline
https://github.com/horde/kronolith/blob/master/lib/Ajax/Application.php\footnote{https://github.com/horde/kronolith/blob/master/lib/Ajax/Application.php}\newline
https://github.com/horde/kronolith/blob/master/lib/Ajax/Application/Handler.php\footnote{https://github.com/horde/kronolith/blob/master/lib/Ajax/Application/Handler.php}

Call HordeCore\footnote{http://example.com/index.php?page=HordeCore}.doAction(action, params, opts) from JS:\newline
action is corresponding to one method name in one of the loaded handlers.\newline
options is a json object with parameters.

doAction takes care of authentication details transparently.

Real Life Example:\newline
https://github.com/horde/kronolith/blob/master/js/kronolith.js\#L296\footnote{https://github.com/horde/kronolith/blob/master/js/kronolith.js\#L296}\newline
\begin{verbatim}

  HordeCore.doAction('searchEvents', {
                cals: Object.toJSON(cals),
                query: query,
                time: this.search
}, {
 callback: function(r) {

}
\end{verbatim}

The handlers have no parameters. They expect named parameters in \$this->vars->\$name corresponding to the params in the doAction call's second argument.

Return values: \newline
Normally, you would return an array structure of serializable data. It will automatically be sent to browser as a json structure. You can also return a string (like HTML) or a Horde\_Core\_Ajax\_Response object for more advanced use cases.

\subsection{ Application-specific javascript code}
Most apps which sport completely distinct dynamic and traditional views (kronolith, hermes) also have \$app/js/\$app.js

\begin{verbatim}

var $AppCore = {
/* What is strictly required here? */
}
document.observe('dom:loaded', $AppCore.onDomLoad.bind(AppCore));
// more observers as needed
\end{verbatim}

\subsection{ View Selection}
Common, but not strictly required:

Logic in \$app/index.php to decide if traditional, ajax or other modes should be loaded.

TODO: Example

\subsection{ Horde Ajax Request Service}
The Horde Base App provides a common receiver for ajax requests by Ajax\_Applications.\newline
It only works for AUTHENTICATED user requests.

Fails silently for malformed requests and unauthenticated users\newline
It loads the app, passes the call's variables to \$App\_Ajax\_Application and runs the ->doAction() method on this class.\newline
Finally it returns a Response.

The default response type is JSON

TODO: Does this only work for pretty URL rewriting mode?

TODO: pretty example

horde/services/ajax.php\newline
\begin{verbatim}

**
 * Processes an AJAX request and returns a JSON encoded result.
 *
 * Path Info:
 * ----------
 * http://example.com/horde/services/ajax.php/APP/ACTION
 *
 * 'APP' - (string) The application name.
 * 'ACTION' - (string) The AJAX action identifier.
 *
 * Reserved 'ACTION' strings:
 * 'logOut' - Logs user out of Horde.
 *
 * Copyright 2010-2012 Horde LLC (http://www.horde.org/)
 *
 * See the enclosed file COPYING for license information (GPL). If you
 * did not receive this file, see http://www.horde.org/licenses/gpl.
 *
 * @author  Michael Slusarz <slusarz@horde.org>
 * @package Horde
 */
\end{verbatim}

\subsection{ \$App\_Ajax\_Application\_Handler}
A Handler inherits from Horde\_Core\_Ajax\_Application\_Handler and can manage external/public (unauthenticated??) calls\newline
extends Horde\_Core\_Ajax\_Application\_Handler

Seems like the difference between Horde 5 and Horde 4 is that each action has its own Handler class rather than a methods in the \$App\_Ajax\_Application class?

\section{ Client side js infrastructure}
important hordecore.js HordeCore\footnote{http://example.com/index.php?page=HordeCore} class methods:

\begin{itemize}
\item{doAction(action, params, opts) - client side method for ajax requests against Horde\_Ajax\_Application}
\item{submitForm(form, opts) - ajax request to submit a form}
\end{itemize}
Depending on the presentation type (Dynamic, Smartmobile), the PageOutput php helper\footnote{http://example.com/index.php?page=Doc/Dev/PageOutput} injects some default javascript environment.

\begin{itemize}
\item{HordeCore\footnote{http://example.com/index.php?page=HordeCore}.conf provides configurable or runtime-generated information}
\item{HordeCore\footnote{http://example.com/index.php?page=HordeCore}.conf.TOKEN is the request token to identify the client session when calling the Ajax framework for more data}
\item{HordeCore\footnote{http://example.com/index.php?page=HordeCore}.conf.URI\_AJAX is the URL to the Ajax service endpoint for the current app}
\item{HordeCore\footnote{http://example.com/index.php?page=HordeCore}.text provides a hash of messages translated to the current environment}
\end{itemize}
\subsection{ Growler: Status messages}
The Growler allows putting volatile status messages to the screen and the message log

\begin{itemize}
\item{HordeCore\footnote{http://example.com/index.php?page=HordeCore}.notify(message, type) }
\end{itemize}
Supported types are: horde.success, horde.error, horde.message, horde.warning

If you need to provide dynamic initialization data specific to your app, use the PageOutput addInlineJsVars method\footnote{http://example.com/index.php?page=Doc/Dev/PageOutput} in your application page.

\section{ The big picture}
\begin{itemize}
\item{When do I use a service/ajax.php handler as opposed to a rampage.php Controller ?}
\item{Imples seem to be used to return snippets? "Don't use imples; they are archaic and can generally be rewritten using the Ajax framework instead"}
\end{itemize}
\section{ Single Page Applications (Hermes, Imp, Kronolith)}
Single Page Applications generally try to keep the user in one location. Different "pages" of the app are simulated by using hash anchors appended to the url: http://www.horde.org/application/index.php\#newCalendar\footnote{http://www.horde.org/application/index.php\#newCalendar}

The javascript of the application responds to these URLs by unhiding the appropriate part of the HTML and filling it with data, possibly collected via AJAX calls to the Horde server application. As long as the browser does not reload, application state is present in the local javascript/dom. The local javascript application sends messages to the server and receives answers - for example "delete item FOO - OK" or "send me the current item list - Here is the list".

In Kronolith and Hermes,\newline
Static snippets of HTML like dialogs (without the data) are called slices - they live in /template/ and have a .inc filename extension.

A function go(fullloc, data) allows to change into different screens.

\end{document}
