Extending Editing functionality

Introduction

This guide will show how to add new functionality to the existing behaviour of Editing. The target layer will be World boundaries, and the goal is to set the currency code when adding or editing a country.

Extending editing functionality

In editing upon submiting a create, edit or a delete request a callback function is triggered after the data has been parsed. These callback functions perform the final saving operation, so if you want to make additional data manipulations before changes are saved then these functions should be used. Wikipedia provides an API for fetching information from it. We will use a request that will return information about the country that is being edited to find out it's currency code.

Before we start we need to create an additional field for the currency in database. To do that go to Administrator panel and click Database section. Select world_boundaries entry from data table and click Edit. Now add a new field named currency of type character varying with length 3 and leave the "Update layer fields and editing rules" checked (to find out more about editing database table see Edit). Since we don't want any user input to that field we must remove it from the Editing rules. To do that go to Administrator panel and click Layers section. Select World boundaries layer, right click on it and press Edit. Click on the Editing rules section. Now search for currency element in the xml and remove it (see Editing rules for more info).

Now let's add some code that will populate this field automatically. We will use the Giscuit_Db_Table_Layer_Worldboundaries class which extends Giscuit_Db_Table_Layer_Abstract class and overwrite the addItemForEditCallback and updateItemForEditCallback methods.

1. <?php
2. class Giscuit_Db_Table_Layer_Worldboundaries extends Giscuit_Db_Table_Layer_Abstract
3. {
4.     /**
5.      * Save a row in database
6.      * 
7.      * @param Zend_Db_Table_Row $row New row with data
8.      * @return integer $pkey Row id
9.      */
10.     public function addItemForEditCallback($row, $form = NULL)
11.     {
12.         //Set currency field
13.         $row->currency = $this->getCountryCurrency($row->name);
14.  
15.         //Execute parent method code
16.         $pkey = $row->save();
17.         
18.         return $pkey;
19.     }
20.     
21.     /**
22.      * Update row in database
23.      * 
24.      * @param Zend_Db_Table_Row $row Edited row
25.      * @return bool Update/don't update row in database
26.      */
27.     public function updateItemForEditCallback($row, $form = NULL)
28.     {
29.         //Set currency field
30.         $row->currency = $this->getCountryCurrency($row->name);
31.         
32.         //Execute parent method code
33.         $row->save();
34.         
35.         return true;
36.     }
37.     
38.     /**
39.      * Get currency for a country
40.      * 
41.      * @param string $name Country name
42.      * @return string $currency Country currency code
43.      */
44.     public function getCountryCurrency($name)
45.     {
46.         //Wiki url for fetching info about a country
47.         $url = 'http://en.wikipedia.org/w/api.php?action=query&prop=revisions&titles=' . $name .
48.             '&rvprop=content&format=txt';
49.         
50.         //Set user agent so that wikipedia will allow the request
51.         $opts = array(
52.             'http'=>array(
53.                 'method' => "GET",
54.                 'header' => "Accept-language: en\r\n",
55.                 'user_agent' => "Giscuit (+http://giscuit.com/)"
56.             )
57.         );
58.         
59.         $context = stream_context_create($opts);
60.         $countryInfo = file_get_contents($url, false, $context);
61.  
62.         //Explode the result by lines
63.         $countryInfo = explode("\n", $countryInfo);
64.  
65.         //Find the currency code line
66.         $currency = '';
67.         foreach ($countryInfo as $line) {
68.             if (substr($line, 0, 14) == '|currency_code' || substr($line, 0, 15) == '| currency_code') {
69.                 $currency = $line;
70.                 break;
71.             }}
72.  
73.         //If line exists get the currency code value and return it
74.         if (! empty($currency)) {
75.             $currency = explode("=", $currency);
76.             $currency = trim($currency[1]);
77.  
78.             return $currency;
79.         }
80.         
81.         //Otherwise return empty string
82.         return '';
83.     }
84. }

Put this code into "library/Giscuit/Db/Table/Layer/Worldboundaries.php" file and check the results by adding/editing a country and then using the Information tool on it. A new field should be visible wich displays the country's currency.

Similar method exists when delete action is performed (deleteItemForEditCallback), and a method to parse geometry WKT (parseGeometryBeforeEdit).