CartoWeb 3.5.0
Download Now!


CartoWeb
Advanced Geographical Information System for the Web

Introduction

The goal of this tutorial is to explain how to make CartoWeb recenter on the map using a user-input form.

As developers we have the choice between extending an existing plugin (for instance location) or creating a new one. Both possibilities are detailed in the CartoWeb manual.

In our case it is easier to write a separate plugin that we will name exampleRecentering (see plugins NamingPolicy).

Definitions

CartoWeb plugins make great use of PHP5 interfaces mechanism. Interfaces list what methods a class should implement and thus ensure that those methods may correctly be called by the main CartoWeb controller.

When you write a class that implements a given interface you have to make sure that the interface methods are implemented in it. If some interface methods are useless in your class, simply add an empty implementation. For instance:

class MyClass implements SomeInterface {

    public function someImplementedInterfaceMethod() {
        // code comes here
    }

    /**
     * Mandatory but empty (since useless) method.
     */
    public function someUselessInterfaceMethod() {}

}

Most interfaces are defined in cartoweb3/client/ClientPlugin.php or cartoweb3/server/ServerPlugin.php and listed in the plugins diagram (PDF - 120kB).

Writing the Plugin

  • Create an exampleRecentering directory in your project plugins directory. Create client and templates subdirectories in the former directory as well:

cartoweb3/projects/yourProjectName/plugins/exampleRecentering/
cartoweb3/projects/yourProjectName/plugins/exampleRecentering/client/
cartoweb3/projects/yourProjectName/plugins/exampleRecentering/templates/
  • Create a ClientExampleRecentering.php file in the client directory, including a ClientExampleRecentering class definition:

cartoweb3/projects/yourProjectName/plugins/exampleRecentering/client/ClientExampleRecentering.php

<?php
/**
 * ClientExampleRecentering.php
 */

class ClientExampleRecentering extends ClientPlugin {
}
?>
  • Our plugin will have to :
    • deal with the graphical user interface (form) => must implement the GuiProvider interface,

    • intercept some POST data to make the geographical object detection and adapt the recentering instructions => must implement the FilterProvider interface.

<?php
/**
 * ClientExampleRecentering.php
 */

class ClientExampleRecentering extends ClientPlugin
                               implements GuiProvider, FilterProvider {

    /**
     * FilterProvider methods
     */
    public function filterPostRequest(FilterRequestModifier $request) {}
    public function filterGetRequest(FilterRequestModifier $request) {}

    /**
     * GuiProvider methods
     */
    public function handleHttpPostRequest($request) {}
    public function handleHttpGetRequest($request) {}
    public function renderForm(Smarty $template) {}
}
?>
  • To build the HTML form integrated in CartoWeb layout, create a template file named for instance recenterInput.tpl in the plugin templates directory:

cartoweb3/projects/yourProjectName/plugins/exampleRecentering/templates/recenterInput.tpl

<!-- recenterInput.tpl -->
<input type="text" name="exampleRecenterField" value="" />

and call it in your plugin class:

<?php
// ...

protected function drawUserForm() {
    $smarty = new Smarty_Plugin($this->getCartoclient(), $this);
    return $smarty->fetch('recenterInput.tpl');
}

public function renderForm(Smarty $template) {
    $template->assign('exampleRecenter', $this->drawUserForm());
}

// ...
?>

To make the input field appear in the general graphical interface, you have to edit your project cartoclient.tpl template and add the following code wherever you want it to appear:

<!-- cartoclient.tpl -->
<!-- some HTML before -->
{$exampleRecenter}
<!-- some HTML after -->
  • Now that the form is ready, let's have a look at the search-and-recenter process in the plugin class:

<?php
// ...

protected function makeSearch($searchString) {

    $searchString = Utils::addslashes(trim($searchString));
    $sql = "SELECT id FROM layerTableName WHERE name LIKE '$searchString'";

    $dsn = $this->getConfig()->dsn;
    $db = Utils::getDb($db, $dsn);
    $res = $db->query($sql);
    Utils::checkDbError($res);
    $row =& $res->fetchRow(DB_FETCHMODE_OBJECT);
    return $row->id;
}

public function filterPostRequest(FilterRequestModifier $request) {
    $searchString = $request->getValue('exampleRecenterField');
    if (!empty($searchString)) {

        // To simplify we assume that only one result is returned by the search
        $id = $this->makeSearch($searchString);
        $request->setValue('id_recenter_layer', 'theRecenteredObjectsLayerName');
        $request->setValue('id_recenter_ids', $id);
    }
}

// ...
?>

If your prefer to recenter on the object using coordinates, you may write instead:

<?php
// ...

protected function makeSearch($searchString) {
    // ...
    return array($x, $y);
}

public function filterPostRequest(FilterRequestModifier $request) {
    $searchString = $request->getValue('exampleRecenterField');
    if (!empty($searchString)) {

        // To simplify we assume that only one result is returned by the search
        list($x, $y) = $this->makeSearch($searchString);
        $request->setValue('recenter_x', $x);
        $request->setValue('recenter_y', $y);
    }
}

// ...
?>

The database connection info (DSN) are here detected from a config file placed in the project client_conf directory and named along the plugin name. In our case:

cartoweb3/projects/yourProjectName/client_conf/exampleRecentering.ini

with

; exampleRecentering.ini
dsn = pgsql://login:pass@host:port/db_name
; the example above is for postgres, PEAR::DB DSN syntaxes are detailed at 
; http://pear.php.net/manual/en/package.database.db.intro-dsn.php
  • Last but not least, activate the plugin by adding it in the client.ini loadPlugins parameter. For instance:

; cartoweb3/projects/yourProjectName/client_conf/client.ini

loadPlugins = exportPdf, hello, exampleRecentering

CartoWeb Wiki: HowToWriteaRecenterPlugin (last edited 2020-09-25 05:51:28 by OliverChristen)

© 2002-2007 CartoWeb by Camptocamp SA - Wiki powered by MoinMoin