< Upgrading Views Data

Mapserver Debian Installation >

## 12. AJAX Implementation

## 12.1. Introduction

CartoWeb implements an AJAX layer, enabling asynchronous update of the HTML GUI.

## 12.2. AJAX Implementation Outline

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

### 12.2.1. Synchronous And Asynchronous Modes

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.

### 12.2.2. Ajaxable Interface

Client plugins can now implement an interface called Ajaxable that enables a plugin to handle an asynchronous request and render XML.

See CartoWeb 3.3 API documentation, interface Ajaxable.

### 12.2.3. Plugins Javascript Side

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.

### 12.2.4. Plugins Actions

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

### 12.2.5. Plugins Enablement Level

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().

## 12.3. Making Your Plugin Ajaxable

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