The implementation of AJAX in CartoWeb is achieved by extending the Cartoclient and creating a lightweight Javascript engine. It introduces a few new concepts:
- Synchronous and asynchronous modes
- Ajaxable interface
- Plugins Javascript side
- Plugins actions
- Plugins enablement level
In addition to the implicit synchronous mode (traditional until-now Cartoclient execution flow), an asynchronous mode has been implemented to process AJAX calls.
- The synchronous mode is the default Cartoclient execution flow, that processes each plugin's logic and renders a monolithic HTML page. Non-AJAX projects will run the synchronous mode without any alteration.
- The asynchronous mode is the execution flow specifically built to process AJAX calls. In this mode, a subset of the plugins features is processed and an XML document, containing plugins output, is rendered - to be processed by the Javascript part.
Client plugins can now implement an interface called Ajaxable that enables a plugin to handle an asynchronous request and render XML.
Each Ajaxable plugin is made of a Javascript part that handles:
- HTTP POST/GET parameters generation for AJAX requests
- GUI refresh logic: processing of the plugin XML response and DOM injection/manipulation.
AJAX introduces the concept of actions. An action is provided by a plugin and is used to define:
- From the Javascript side, what are the HTTP parameters (GET & POST) to be sent to the Cartoclient
- From the Caroclient side, what subset of each plugin's logic is to be processed
In example, the Location coreplugin provides the following actions:
- Location.Pan
- Location.Zoom
- Location.FullExtent
- Location.Recenter
When the Cartoclient's asynchronous mode is triggered, the action is used to determine what subset of each plugin's logic should be processed. Processing a subset of a plugin's logic is achieved by changing it's enablement level. Enablement levels are by default set to Full (i.e. the whole logic is processed).
Here are the yet available enablement levels:
- Load: The plugin is loaded
- Process: The plugin is loaded and handles GET/POST Requests
- ServerCall: The plugin handles GET/POST requests, builds/overrides server request and handles server result
- Full: The plugin's whole logic is executed
Note that all enablement levels perform a Sessionable::saveSession().
An ajaxable plugin has the ability to refresh the CartoWeb GUI asynchronously, if the project using it enables the AJAX mode (see how to enable AJAX in a project: Section 20.2, “Make Your Project AJAX Enabled”
Please have a look at the wiki for an up-to-date howto explaining how to make a plugin ajaxable: http://www.cartoweb.org/cwiki/HowToAjaxablePlugin
