The following describes the steps that a developer should take to integrate the GIS into their module.

First of all this guide assumes the developer is adding a geographical position to some object that is already in their module, for example a Camp in Camp Registry or an Inventory in ims. As such the guide will tailor to these needs first before explaining the more advanced features offered by the GIS.

Check the module that contains the item you wish to attach a geographical reference to has at LEAST the functionality and interfaces to add and remove the item in question from the sahana database. On top of this common starting page URLs to add, remove, edit and view items are very useful. For example:

      index.php?mod=admin&act=gis_database_classes_delete&seq=seq_2&c_uuid=ims_inventory

This is needed because:

Luckily this is a very straight forward process using the the gis fns libary

Every item in the Sahana GIS database is classified as a type (known as a Feature Class). Many Feature Classes are created on installation (eg Camp [NGO], Evacuation Point, Hospital), or alternately users can add, edit and remove them post-installation in the “Administration” → “GIS Configuration” → “GIS Internal Feature Class Management” section of Sahana.

In a way a feature class is basicly a styling tag associated with each feature It is not a feature Itself

To see a list of the classes currently in your Sahana set up, view the contents of the “gis_feature_class” table in the database.

You will probably need to register a Feature Class type on installation of Sahana to represent the item you wish to add geographical information to. To do this add the following code to the www/yourmodule/inst/dbcreate.sql file

    INSERT INTO gis_feature_class VALUES ('1', '2', '3', '4', '5', '6');

1. A unique ID for the item eg. “ims_inventory”
2. The shorthand for your module used by the front controller. eg “ims” MUST be filled-in to prevent features of this type being created outside your module!!!
3. The name of the item eg. “Inventory”
4. A description of the Feature Class eg. “Inventories may hold food, meds, shelter material”
5. An icon url. Icons can be absolute or relative to Sahana installation folder. eg. “res/img/markers/marker.png”
6. An icon color as 6 digits. eg. “000000” (for black) - Currently not used… maybe used for area markers

Altogether:

    INSERT INTO gis_feature_class VALUES ('ims_inventory', 'ims', 'Inventory', 'Inventories may hold food, meds, shelter material', 'res/img/markers/marker.png', '000000');

To aid the user in entering the coordinates of the item (or Feature as they are known in the GIS) the GIS provides a number of forms that will display a map which the user can click on to retrieve the coordinates of their new item. This can be done by including the following code

require_once $global['approot']."/inc/lib_gis/lib_gis_forms.inc";
shn_gis_form_map_add_marker($name_of_map, $name);

or

require_once $global['approot']."/inc/lib_gis/lib_gis_forms.inc";
shn_gis_form_map_add_marker_plus($name_of_map ,$nameOfPoint, $button_submit_opts, $extra_opts);

“shn_gis_form_map_add_marker($name_of_map, $name)” will add only the map whereas
“shn_gis_form_map_add_marker_plus($name_of_map ,$nameOfPoint, $button_submit_opts, $extra_opts)” will add the map and additional boxes to input the gps coordinates directly.

The coordinates from a marker placed on these maps can be retrieved such:

$marker_x_lat_coordinate = $_POST['loc_x'];
$marker_y_lng_coordinate = $_POST['loc_y'];

Now that your module has add and remove functionality, A Feature Class registered in the GIS and the coordinates of the feature to be created, it is time to actually create the feature in the GIS. This can be achieved using the following code:

// Include for the GIS Database API.
require_once $global['approot']."/inc/lib_gis/gis_fns.inc";
 
// Parse the Coordinates to wkt format.
$type = 'point';
$coords_center = array($marker_x_lat_coordinate, $marker_y_lng_coordinate, 0);
$coords = array($coords_center, $coords_center);
$coordinates = shn_gis_coord_encode($coords, $type);
 
// Register the values that will make the new feature as an array of key => values.
$keys_ = array(  
    'f_class'         => 'ims_inventory',
    'f_type'          =>  $type,
    'f_projection'    => 'EPSG:900913',
    'f_coords'        =>  $coordinates,
    'f_module_item'   => 'abc123',  // The UID used in your modules table to ref the item!
    'f_name'          => 'inventory A',
    'f_description'   => 'Inventory of toasters',
    'f_author'        => 'Pete the 5d',
    'f_url'           => 'http://www.toasterworld.com',
    'f_address'       => '1 Little Hill, Peteshire',
    'f_event_date'    => '2008-06-15 15:05:20',
    'f_extended_data' => 'aaaa',
    'f_url_view'      => 'index.php?mod=admin&act=gis_database_classes_view&seq=seq_2&c_uuid=ims_inventory, // my module's item view url
    'f_url_edit'      => 'index.php?mod=admin&act=gis_database_classes_edit&seq=seq_2&c_uuid=ims_inventory', // my module's item edit url
    'f_url_delete'    => 'index.php?mod=admin&act=gis_database_classes_delete&seq=seq_2&c_uuid=ims_inventory' // my module's item delete url
);
 
// Creature the Feature.
shn_gis_create_feature($keys_);

• Note The key list may be out of date - check the GIS API for the most updated documentation on each key and its possible values!.)

   'f_class'
   'f_type'    
   'f_projection'
   'f_coords'
   'f_module_item'

and

   'f_url_view' 
   'f_url_edit'
   'f_url_delete'

The first set contains basic information to display the feature on the map such as:

• The uuid of the feature class the item is being registered to (the uuid you created in your dbcreate.sql in step 2).
  
• The type: a 'point', 'line' or 'poly'.
  
• The projection (if not entered set to systems default set in $conf['gis_feature_projection_default']).
  
• The Coordinates are parsed into the “well known text” (wkt) format using the “shn_gis_coord_encode($coords, $type)” function. $coords is a multi dim array such:
  
• The uuid of the item in YOUR modules table. This field is very useful as it removes the need for external modules to keep a reference to a features personal uuid(f_uuid) on top of their own.
  It is VERY important that external modules register a value here. If not the GIS will assume the item was created in situation mapping and as such let the user edit/delete it there. This leads to big data concurrency issues!!!

[0 ⇒ center of obj] ⇒ [0 ⇒ x, 1 ⇒ y, 2 ⇒ z]
[1 ⇒ plot 1] ⇒ [0 ⇒ x, 1 ⇒ y, 2 ⇒ z]
[2 ⇒ plot 2] ⇒ [0 ⇒ x, 1 ⇒ y, 2 ⇒ z]
[3 ⇒ plot 3] ⇒ [0 ⇒ x, 1 ⇒ y, 2 ⇒ z]

(obviously for a point only the first 2 values are needed, lines and polygons will need more.

The second set contains information that allows the GIS module to provide links to manipulate the data from other modules within the system. These are:

• A link to view the item being registered, eg. The view page for a camp (see the camp reg module).
  
• A link to edit the item being registered.
  
• A link to delete the item being registered.
  

The other keys are mainly optional, however it is likely that the table that holds your item already has inputs for a name, description, etc. Although this is creating duplicate data it is recommended that you provide inputs for these values as it makes more information available in situation mapping, just remember to update them when your table is updated!

To edit a Feature using the same uuid as the item in your own module's database.

      // Include for the GIS Database API.
      require_once $global['approot']."/inc/lib_gis/gis_fns.inc";
 
      // Register the values to change in the Feature as an array of key => values.
      $keys_ = array(  
         'f_coords'        =>  $coordinates,
         'f_name'          => 'inventory A',
         'f_description'   => 'Inventory of toasters',
         'f_author'        => 'Pete the 5d',
         'f_url'           => 'http://www.toasterworld.com',
         'f_address'       => '1 Little Hill, Peteshire',
         'f_event_date'    => '2008-06-15 15:05:20',
      );
 
      shn_gis_modify_feature_module_item($f_module_item, $keys_);

To edit a Feature if you know the Feature's own uuid:

      // Include for the GIS Database API.
      require_once $global['approot']."/inc/lib_gis/gis_fns.inc";
 
      // Register the values to change in the Feature as an array of key => values.
      $keys_ = array(  
         'f_coords'        =>  $coordinates,
         'f_name'          => 'inventory A',
         'f_description'   => 'Inventory of toasters',
         'f_author'        => 'Pete the 5d',
         'f_url'           => 'http://www.toasterworld.com',
         'f_address'       => '1 Little Hill, Peteshire',
         'f_event_date'    => '2008-06-15 15:05:20',
      );
 
      shn_gis_modify_feature($uuid_, $keys_)

• Note For a full list of editable keys check the GIS API .

To remove a Feature using the same uuid as the item in your own module's database:

    // Include for the GIS Database API.
    require_once $global['approot']."/inc/lib_gis/gis_fns.inc";
 
    // Remove the feature from the GIS
    shn_gis_remove_feature_module_item($f_module_item);

To remove a Feature if you know the feature's own uuid is below:

    // Include for the GIS Database API.
    require_once $global['approot']."/inc/lib_gis/gis_fns.inc";
 
    // Remove the feature from the GIS
    shn_gis_remove_feature($feature_uuid);

      // Include for the GIS Database API.
      require_once $global['approot']."/inc/lib_gis/gis_fns.inc";
 
      // Register the values to change in the feature as an array of key => values.
      $keys_ = array(  
          'f_uuid'          => '1',
          'f_class'         => '1',
          'f_type'          => '1',
          'f_projection'    => '1',
          'f_coords'        => '1',  
          'f_module_item'   => '1',
          'f_name'          => '1',
          'f_description'   => '1',
          'f_author'        => '1',
          'f_url'           => '1',
          'f_address'       => '1',
          'f_event_date'    => '1',
          'f_extended_data' => '1',
          'f_url_view'      => '1',
          'f_url_edit'      => '1',
          'f_url_delete'    => '1'
       );
 
       // Alternatly you can use
       $keys_ = array('all' => '1');
 
      $features = shn_gis_get_features_item_ref($item_uuid_, $keys_);

Features are returned in the same array as given in keys with the '1' replaced with the corresponding values.

The are a number of get_feature functions available, check the GIS API for more details.

1. Is the item Created in the GIS when it is added to the module.
   
2. Is the item Edited in the GIS when it is edited in the module.
   
3. Is the item Removed from the GIS when it is removed from the module.
   
4. Does each item in the module have a Feature Class registered on installation of Sahana.
   

Location of all GIS forms and map display functions:

  require_once $global['approot']."/inc/lib_gis/lib_gis_forms.inc";

Location of all GIS Internal Database functions:

  require_once $global['approot']."/inc/lib_gis/gis_fns.inc";   

Soon to be:

  require_once $global['approot']."/inc/lib_gis/lib_gis_db_fns.inc";

Location of general GIS functions

  require_once $global['approot']."/inc/lib_gis/lib_gis_fns.inc";