< Performance Tests

AJAX Implementation >

11. Upgrading Views Data

11.1. Introduction

Views saves given CartoWeb states by recording the plugins session data. Only client-side plugins implementing Sessionable interface may be saved in views.

Because CartoWeb and its plugins evolve, views might become outdated after some time. Plugin session containers may change: properties may be added, removed, renamed, etc. and thus shifts between old views and new plugin session formats appear. Those shifts then prevent some views from correctly displaying or even make CartoWeb crash.

However CartoWeb offers upgrade tools to read outdated views.

11.2. Upgrade Tools

11.2.1. Views Versions

Plugins session data are saved in views in separated XML elements. Each element records the plugin session container version. Plugin session container version must be incremented whenever a change is applied on the container format (new property, name change, etc.). Container version, if not specified, defaults to 1. To explicitely update it, add following constant definition before container declaration:

define('PLUGINNAME_SESSION_VERSION', 3);

where PLUGINNAME is the uppercased plugin name. Container versions are always integers.

11.2.2. Upgrade Filters

Upgrading a view is done by sequentially applying filters, each one updating it to the following version (from version N to version N+1). If matching sequence cannot be detected (missing filters), upgrade is aborted and outdated data is discarded. Current plugin data is then used instead.

Upgrade filters are PHP classes extending ViewUpgrader, the latter class being defined at the end of client/Views.php. They are saved in a ViewsUpgrade.php file, located in the same directory than the plugin client-side class file (for instance coreplugins/location/client/). Filters naming convention is <UppercasedPluginName>V<initialVersion>ToV<initialVersion+1>.

Some basic methods (rename, remove, add) are available in every filters but you may define your own transformers methods. Details about basic methods are given in ViewUpgrader class documentation (CartoWeb API manual). At least an upgrade filter class must redefine the callFilters() method that indicates the sequence of transformations to apply.

An example of filters might be:

<?php
/**
 * coreplugins/location/client/ViewsUpgrade.php
 */

class test {
var $game = 'arkanoid';
var $i = 12;
}

/**
 * Upgrades from V1 to V2
 */
class LocationV1ToV2 extends ViewUpgrader {
    protected function callFilters() {
        $this->add('test', 'toto');
    }
}

/**
 * Upgrades from V2 to V3
 */
class LocationV2ToV3 extends ViewUpgrader {
    protected function callFilters() {
        $this->rename('test', 'foo');
        $this->add('bar', new test);
        $this->add('someProperty', 2);
        $this->add('caramba', 'ole');
        $this->remove('someProperty');
    }
}
?>

Warning

It is the responsibility of each developer to provide adapted filters when he/she updates plugin session containers!

Warning

Upgrade filters do not support non object-typed plugin session containers.

11.2.3. Upgrade Configuration

See Section 13.2.2, “Main Views Controller”. Only two of these parameters are related to views upgrading. viewLogErrors enables to log outdated views loadings whereas viewUpgradeOutdated is useful to activate or not the upgrading device (if deactivated, outdated views parts are discarded).

11.3. Customizing Views Processing Using Project Hooks

CartoWeb offers the ability to add some project-specific controls ("hooks") within the views processing.

For now only one hook is available, right before the data of the loaded view is merged with the current session data. See method ViewManager::handleView() in client/Views.php.

To create hooks, write a PHP class extending the basic ViewHooks class defined in client/Views.php. The extended class must be saved in a file with the same name, located in your project plugins/views/client/ directory. If the latter directory does not exist, simply create it. The standard "views" plugin is not required to have hooks working. Finally, set the viewHooksClassName with your extended class name in client.ini.

; configuration in client.ini
viewOn = true
viewStorage = db
viewablePlugins = location, layers, query, outline
viewMetas = author
...
viewHooksClassName = FoobarViewHooks
<?php
/**
 * projects/<your_project>/plugins/views/client/FoobarViewHooks.php
 */
class FoobarViewHooks extends ViewHooks {

    /**
     * @see ViewHooks::handlePreLoading()
     */
    public function handlePreLoading($data, $viewId) {
        // Your customized code...
    }
}
?>
valid xhtml 1.0 valid css