Editing



The spatial editing extension for Weave provides a means to edit geometry and attributes for an entity.

Features:

• Simple to setup for basic operation
• Customisable for advanced operation
• Supports transparent editing on an entity with multiple spatial layers
• Can be initiated from URL parameters

Limitations:

• Spatial mapper for entity must have <dynamic> set to true and <cache> set to false
  • But this is generally the case for any entity that can have it's underlying data altered on the fly
• Currently only attributes directly attached to the spatial table can be edited

Installation

Currently the Weave editing sub-system is provided as a single bundle, com.cohga.spatial.edit, but this may change before release.

This bundle must be copied to the weave\platform\plugins directory and the server restarted for it to be available.

Requirements

Configuring Entities

Before you can edit an entity there are some criteria that need to be met, firstly the entity id must be unique within a spatial table.
If an entity is composed of multiple spatial tables then it may be the case that the id may not be unique across all of the tables, if for example the entity is composed of more than one geometry type and the underlying spatial engine (e.g. ArcSDE, shapefiles) doesn't support different geometries in a single table, then the geometry would need to be spread over more than one table. In this situation the entity id would have to be the same in all of the spatial tables, but it must at least be unique within each table, this is the only way that Weave can determine which row in the table that it needs to update (it determines which spatial table to update based on the geometry type stored in the spatial table).

For editing multiple spatial tables are only fully supported when a different geometry type is stored in each table. That is if an entity is linked to more than one spatial table then each spatial table should contain a different geometry type (point, line or polygon), this is so that Weave knows which table to write the appropriate geometries to, for example if you were to have an entity linked to two spatial tables, both containing polygon geometry, then when an edit was submitted than contains a polygon Weave would not know which table the geometry was supposed to be added to or updated in.

Also, note that in the case of an entity represented by multiple spatial tables the schemas for the tables should all be the same, as the same attribute values will be written to each table when an edit is submitted that contains different geometry types.

Additionally, at this stage spatial engines that don't differentiate between geometry types, i.e. the spatial table stores "geometry" and not specifically points, lines or polygons, are not currently support in multi table configurations, since Weave can not determine which table to write the geometry to (they are supported in single table configurations). This may change in the future.

Configuration

Client Edit Plugin

Part of the client side editing sub-system is implemented as a 'plugin' for the map view, so the first thing that needs to be done when enabling the editing sub-system is to register the edit plugin with the map view in the client configuration.

<?xml version="1.0" encoding="UTF-8"?>

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">

  <client:config id="edit">
    <!-- more config items here -->

    <view id="com.cohga.html.client.map.mapView">
      <label>Map</label>
      <location>center</location>

      <plugin id="weave.edit"/> <!-- Register the edit plugin with the map view -->

      <!-- map config items here -->
    </view>

    <!-- more config items here -->
  </client:config>

</config>

The provides the edit sub-system with a hook into the map view so that it can provide access to the editing layer.

Client Edit View

When performing an edit a view panel is required to enter/change the attributes associated with the entity being edited. This view is provided by the com.cohga.client.panel.edit view and so also needs to be added to the client configuration.

<?xml version="1.0" encoding="UTF-8"?>

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">

  <client:config id="edit">
    <!-- more config items here -->

    <view id="com.cohga.client.panel.edit"> <!-- Add the Edit panel to the client -->
      <label>Edit</label>
      <location>west</location>
    </view>

    <view id="com.cohga.html.client.map.mapView">
      <label>Map</label>
      <location>center</location>

      <plugin id="weave.edit"/> <!-- Register the edit plugin with the map view -->

      <!-- more config items here -->
    </view>

    <!-- more config items here -->
  </client:config>

</config>

This view also provides the actions required to initiate editing and the tools required to perform the spatial edit operations.

Client panel buttons

Customising the client edit view

There are a number of customisation options available to alter the display of the edit view

Edit View with embedButtons set to true and showText set to false

Server Edit Configuration

Before an entity can be edited it must have at least one edit configuration associated with it. The edit configuration enables editing for the particular entity and also allows for overriding the details about the way the user can edit the entity, for example what attributes the user can edit, how the attributes are presented to the user, etc.

Basic Server Edit Configuration

The most basic edit configuration interrogates the underlying spatial tables for the information it requires, for example to determine what attributes the entity has associated with it or what spatial geometries (point, line or polygon) the user is allowed to create.

<?xml version="1.0" encoding="UTF-8"?>

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:edit="urn:com.cohga.spatial.edit#1.0">

  <edit:config id="simple.edit">
    <entity>graffiti</entity>
    <label>Graffiti</label>
    <description>Report graffiti for removal</description>
  </edit:config>

</config>

This provides a simple way to setup editing for an entity, allowing the user to directly edit the attributes attached to the entity in the underlying spatial table.

Default editing attributes

The basic edit configuration offers no options to customise what attributes are available for editing, they all are, or how the user will be able to edit those values, which will be determined by the underlying column type in the spatial table and be limited to simple field types (text fields for string and numbers, calendar field for dates, etc).

Default geometry requirements

What types of geometry the user will be able to create/edit will also be determined by the underlying spatial table, if the spatial table contains polygons then the user will only be able to create polygons, they will not be able to create points or lines. If however the entity is linked to two spatial tables, one containing polygons and the other containing points then the user will be able to edit points and polygons.

Further there is differentiation between spatial layers that contain single instance geometry and those that contain multi-instance geometry, that is if the spatial table contains multipolygons, as opposed to just polygons, then the user will be allowed to create more than one polygon shape when editing the entity, when the spatial table contains polygons the user will be limited to a single polygon object. The same applies to points/multipoints and line/multilines.

Finally the requirement for the user to actually create geometry is also determined by the underlying spatial table, if the spatial table allows nil geometry then the user will not be forced to create a geometry when creating a new entity, if the spatial table doesn't allow nil geometries then the user will be required to create a geometry before they'll be able to complete the edit.

Customising Server Edit Configuration

If you need more control over the attributes and geometry for an edit then you need to override the values that the simple form is generating.

The things that you can override are the parameters that the user can edit, the maximum number of geometry items the user can create and the required number of geometry items the user must create.

<?xml version="1.0" encoding="UTF-8"?>

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:edit="urn:com.cohga.spatial.edit#1.0">

  <edit:config id="custom.edit">
    <entity>graffiti</entity>
    <label>Grafitti</label>
    <description>Report graffiti for removal</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="description">
      <label>Description</label>
      <controlType>text-area</controlType>
      <column>DESCRIPTION</column>
    </parameter>
  </edit:config>

</config>

Custom geometry requirements

Unless explicitly set the types of geometry that a user can create for an entity, and also if the user can create an entity with no geometry, is defined by the underlying spatial tables, if you wish to override this then you do so with the geometry settings.

The geometry settings determine the minimum and maximum number of each geometry type (point, linestring and polygon) that the user can create, as well as the total number of geometry items (of any type) that the user can create.

This is done by specifying point, linestring, polygon and/or geometry items, and for each one specify the minimum and maximum value for each. If no point, linestring or polygon setting is specified then the user will not be able to create those geometry types, unless geometry is specified in which case the user can create all geometry types.

Some examples of why you would want to set these values are (these assume that you can't change the underlying spatial table):

Spatial table allows nil geometry but you wish to enforce geometry creation

<geometry minimum="1"/>

or

<geometry>
  <polygon minimum="1"/>
</geometry>

Spatial table allows multi part geometry but you wish to enforce creation of single part geometry

<geometry maximum="1"/>

or

<geometry>
  <polygon maximum="1"/>
</geometry>

The spatial engine supports multiple geometry types in a single table, for example Oracle Spatial, and you wish to limit the geometry

<geometry>
  <polygon/>
</geometry>

You want the user to specify 2 geometries, including 1 polygon and either a point or a line.

<geometry minimum="2" maximum="2">
  <polygon minimum="1" maximum="1"/>
  <linestring/>
  <point/>
</geometry>

You want the user to specify 2 geometries, including 1 polygon and either a point, line or polygon.

<geometry minimum="2" maximum="2">
  <polygon minimum="1"/>
  <linestring/>
  <point/>
</geometry>

You want the user to specify 1 or 2 geometries, including 1 polygon and optionally a point or line.

<geometry maximum="2">
  <polygon minimum="1"/>
  <linestring/>
  <point/>
</geometry>

You want the user to specify between 2 and four points.

<geometry>
  <point minimum="2" maximum="4"/>
</geometry>

Custom attributes

If the default attribute editing setup isn't suitable you can directly specify the attributes that the user can edit and how they appear to the user.

This is done by adding one or more parameter items to the edit configuration, where each parameter specified one input parameter. The format of the parameter items in an edit config are an extension of those available for search parameters.

A few things to not about the properties that can be applied to parameters:

• column is optional, if not provided then the field will still appear, but an attempt to write the entered value into the underlying spatial table will not be made. The user entered value can still be used by other means that will be covered later.
• The controltype now supports 'textarea' which isn't available for search fields, it provides a multi-line text input field.
• readonly, readonlyoninsert and readonlyonupdate aren't available for search field either, they're special marker that allow you to alter the ability of the user to change the value in a field. These are client side flags, and if set alter the display of the field so that the user cannot change the value, the field is still displayed, just not editable.
• updatable specifies that one a value is set it can't be changed, this is similar to readonlyonupdate, and in fact readonlyonupdate will be set to true if updatable is set to false, but it also provides additional checks on the server to ensure that the value is not updated.
• value can be used to set a value explicitly by directly supplying the value, or there are a number of formulas that are available.
  • entity() The name of the entity type being edited.
  • userid() The current username.
  • datetime() The current date/time.
  • operation() The type of operation being perform, will be one of the strings 'create', 'update' or 'delete'.
  • nextval() The value used for the column will be the previous largest value from the column plus one, the underlying column must be numeric.
  • geometry() A WKT (Well Known Text) representation of the geometry if available, otherwise null.
  • id() The value for the key field for the spatial table will be used if available, otherwise null.
  • auto() The value for the field is auto-generated by the database.
  • count() The number of geometry objects.
  • area() The area of the geometry.
  • length() The length of the geometry.

Custom parameter examples

Auditing changes

To record who created and who modifies an entity

  <edit:config id="custom.edit">
    <entity>graffiti</entity>
    <label>Grafitti</label>
    <description>Report graffiti for removal</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="description">
      <label>Description</label>
      <controlType>text-area</controlType>
      <column>DESCRIPTION</column>
    </parameter>
    <!-- Hidden parameters to record audit information -->
    <parameter id="createdby">
      <hidden>true</hidden>
      <column>CREATEDBY</column
      <value>userid()</value>
      <updatable>false</updatable>
    </parameter>
    <parameter id="createdon">
      <hidden>true</hidden>
      <column>CREATEDON</column>
      <value>datetime()</value>
      <updatable>false</updatable>
    </parameter>
    <parameter id="modifiedby">
      <hidden>true</hidden>
      <column>MODIFIEDBY</column
      <value>userid()</value>
    </parameter>
    <parameter id="modifiedon">
      <hidden>true</hidden>
      <column>MODIFIEDON</column>
      <value>datetime()</value>
    </parameter>
  </edit:config>

In this example the audit information is stored in the spatial table itself, so the table must already contain the CREATEDBY, CREATEDON, MODIFIEDBY and MODIFIEDON fields and they need to by character fields for the 'by' fields and timestamps for the 'on' fields.
Also, the about configuration assumes that there is an additional column that's used to identify the records, the id column, but that the column is auto-generated by the database and is not user editable.

Setting an id field

Specifying an field as an id field to be created by using the maximum value from the column.

  <edit:config id="custom.edit">
    <entity>graffiti</entity>
    <label>Grafitti</label>
    <description>Report graffiti for removal</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="id">
      <hidden>true</hidden>
      <column>ID</column>
      <value>nextval()</value>
    </parameter>
    <parameter id="description">
      <label>Description</label>
      <controlType>text-area</controlType>
      <column>DESCRIPTION</column>
    </parameter>
  </edit:config>

This example sets an id field that's hidden from the user and it's created from the existing values in the table. This is not an optimal solution to generating new key values, and it would be much better to use the functionality provided by the underlying database (sequences, auto-generate, identity, etc).

Drop down lists

Specifying that the value for a field is chosen from a list. Here we have a static list, status, included directly in the configuration, and a dynamic list populated from a data definition, reporter.

  <edit:config id="custom.edit">
    <entity>graffiti</entity>
    <label>Grafitti</label>
    <description>Report graffiti for removal</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="id">
      <hidden>true</hidden>
      <column>ID</column>
      <value>nextval()</value>
    </parameter>
    <parameter id="description">
      <label>Description</label>
      <controlType>text-area</controlType>
      <column>DESCRIPTION</column>
    </parameter>
    <parameter id="status">
      <label>Status</label>
      <controlType>list-box</controlType>
      <column>STATUS</column>
      <defaultValue>N</defaultValue>
      <list value="N" label="New"/>
      <list value="V" label="Verified"/>
      <list value="S" label="Scheduled"/>
      <list value="R" label="Removed"/>
    </parameter>
    <parameter id="reporter">
      <label>Reporter</label>
      <controlType>list-box</controlType>
      <dataSet>staff</dataSet>
      <allowNewValues>true</allowNewValues>
      <column>REPORTEDBY</column>
    </parameter>
  </edit:config>



Writing to other tables

So far all attribute values entered by the user have been written directly to the underlying spatial table, but it's also possible to write values, including those entered by the user and those available via value formulas, to another database table. This can be done by creating an audit edit configuration item and attaching it to an existing edit configuration item.

The audit configuration specified a datasource and table to write the values to plus a list of parameters that correspond to the columns in the table.
The columns can derive their values either from the values entered by the user as a parameter in the original edit configuration or as a formula using a value tag or as a hard coded value.

  <edit:config id="custom.edit">
    <entity>graffiti</entity>
    <label>Grafitti</label>
    <description>Report graffiti for removal</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="id" hidden="true" label="Id" column="ID" value="auto()"/>
    <parameter id="description" label="Description" controlType="text-area"/>
  </edit:config>

  <edit:audit id="custom.audit">
    <edit>custom.edit</edit>
    <datasource>datasource.main</datasource>
    <table>EDIT_AUDIT</table>
    <parameter column="ID" value="id()"/>
    <parameter column="DESC" parameter="description"/>
    <parameter column="USER" value="userid()"/>
    <parameter column="MODIFIED" value="datetime()"/>
  </edit:audit>

Starting from a URL

The edit process can be started by including either a 'create' or an 'edit' parameter as part of the url when starting the client

http://localhost:8080/weave/edit.html?create=custom.edit

create will initiate the creation of a new entity, using the configuration specified by the value of the create parameter.

http://localhost:8080/weave/edit.html/edit=custom.edit?id=1234

edit will initiate the editing of an existing entity, using the configuration specified by the value of the edit parameter and using the entity identified by the id parameter. Also, the client will zoom to the extent of the selected entity.

Both of these URL's also allow you to specify values to be used for the parameter in the edit.

http://localhost:8080/weave/edit.html?create=custom.edit&description=Type%20your%20description%20here