+ 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.
It contains of a horde-wide server-side entry point ajax.php and per-application definitions which handlers are used.
On the client side, HordeCore.js provides the tools to call these endpoints and automatically add security tokens to the request.
++ Convention
$app (lowercase, for example "passwd")
$App (First Uppercase, for example "Passwd")
++ Javascript libraries used
!JavaScript for "dynamic" and "traditional" mode uses [http://api.prototypejs.org/ PrototypeJS]
!JavaScript for "smartmobile" mode uses [http://jquerymobile.com/ jQuery Mobile]
+++ Using jquery alongside prototype
This is generally not accepted upstream.
jQuery can be made coexist with dynamic/traditional mode's !PrototypeJS
For non-upstream custom code:
<code>
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 */
);
</code>
++ Files and Classes of a Horde Ajax Application
+++ Horde_Ajax_Application class
Bare Minimum for a Horde Ajax Application (on top of a skeleton Horde_Registry_Application):
A File $app/lib/Ajax/Application.php with a class
<code>
<?php
// phpdoc omitted
class $App_Ajax_Application extends Horde_Core_Ajax_Application {}
?>
</code>
[http://dev.horde.org/api/master/lib/Core/classes/Horde_Core_Ajax_Application.html Horde_Core_Ajax_Application documentation]
+++ Application-specific javascript code
Most apps which sport completely distinct dynamic and traditional views (kronolith, hermes) also have $app/js/$app.js
<code>
var $AppCore = {
/* What is strictly required here? */
}
document.observe('dom:loaded', $AppCore.onDomLoad.bind(AppCore));
// more observers as needed
</code>
+++ 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
+++ Horde Ajax Request Service
The Horde Base App provides a common receiver for ajax requests by Ajax_Applications.
It only works for AUTHENTICATED user requests.
Fails silently for malformed requests and unauthenticated users
It loads the app, passes the call's variables to $App_Ajax_Application and runs the ->doAction() method on this class.
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
<code>
**
* 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
*/
</code>
+++ $App_Ajax_Application_Handler
A Handler inherits from Horde_Core_Ajax_Application_Handler and can manage external/public (unauthenticated??) calls
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?
++ Client side js infrastructure
important hordecore.js HordeCore class methods:
* doAction(action, params, opts) - client side method for ajax requests against Horde_Ajax_Application
* submitForm(form, opts) - ajax request to submit a form
TODO
++ The big picture
* When do I use a service/ajax.php handler as opposed to a rampage.php Controller ?
* 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"