The spatial editing extension for Weave provides a means to edit geometry and attributes for an entity.
...
- Currently only attributes directly attached to the spatial table can be edited
Weave will only write to the spatial table when editing an entity, currently having some attributes written to the spatial table and other attributes written to separate database tables is not supported. Audit tables may provide enough functionality to support the required workflow though. - 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.
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.
...
Spatial engines that do not 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. This is because in these cases, 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.
...
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.
...
This view also provides the actions required to initiate editing and the tools required to perform the spatial edit operations.
Client panel buttons
name | description |
|---|---|
Create | Insert a new entity. |
Update | Change the currently selected entity. |
Delete | Remove the currently selected entity. |
Reset | Reset the form fields back to their original values. |
Submit | Complete the edit process and save the current changes. |
Cancel | Abort the edit process and abandon the current changes. |
Modify | Modify an existing geometry. |
Point | Create a new point. |
Line | Create a new line. |
Polygon | Create a new polygon. |
Remove | Remove the currently selected geometry. |
Snap | Toggle the snapping function on and off. |
Settings | Changes the snapping settings. |
Import | The import button allows the user to import geometry from another entity. |
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. Examples are what attributes the user can edit and or how the attributes are presented to the user.
| Info |
|---|
You can have multiple edits associated with each entity. The user will be able to choose which edit to perform by selecting from a list. |
Basic Server Edit Configuration
The most basic edit configuration interrogates the underlying spatial tables for the information it requires. (e.g. to determine what attributes are associated with the entity or what spatial geometries, point, line or polygon, the user is allowed to create)
...
| Tip |
|---|
The edit configuration has a |
Default editing attributes
The basic edit configuration enables all attributes available for editing. Also, the basic configuration does not provide an option to customise 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 (e.g. text fields for string and numbers, calendar field for dates).
Default geometry requirements
The types of geometry the user will be able to create or 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 and 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 both points and polygons.
...
The requirement for the user to 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 however if the spatial table doesn't allow nil geometries then the user will be required to create a geometry before they will 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.
...
Please note that the <column> value is case sensitive. "DESCRIPTION" is not the same as "Description"
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.
...
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
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<geometry minimum="1"/> |
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<geometry> <polygon minimum="1"/> </geometry> |
Spatial table allows multi part geometry but you wish to enforce creation of single part geometry
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<geometry maximum="1"/> |
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<geometry> <polygon/> </geometry> |
You want the user to specify 2 geometries, including 1 polygon and either a point or a line.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<geometry maximum="2"> <polygon minimum="1"/> <linestring/> <point/> </geometry> |
You want the user to specify between 2 and four points.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<geometry> <point minimum="2" maximum="4"/> </geometry> |
...
| Info |
|---|
If minimum is not specified it defaults to 0. |
Restricting edit types
You can selectively disable a users ability to create, update or delete entities by setting create, update or delete to false in the edit config.
| Code Block | ||
|---|---|---|
| ||
<?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>
<update>false</update>
<delete>false</delete>
</edit:config>
</config> |
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.
...
Name | Type | Required | Default | Description |
id | string | yes | A unique identifier for the parameter | |
label | string | yes | The prompt text displayed when user input the parameter value | |
column | string | no | The name of the column within the table that this parameter references | |
helptext | string | no | Additional text to display for the parameter to explain how to use the parameter | |
hidden | boolean | no | false | Hides the parameter from the parameter UI |
alignment | 'left', 'center', 'right', 'auto' | no | 'auto' | How the items should appear in the UI |
controltype | 'listbox', 'checkbox', 'radiobutton', 'textbox' or 'textarea' | no | 'textbox' | The suggested type of UI control to use when displaying the parameter |
datatype | 'any', 'date', 'time', 'datetime', 'integer', 'string' | no | 'string' | The data type for the parameter |
allownull | boolean | no | false | Whether a null value is allowed for this parameter |
allowblank | boolean | no | true | Give the user the choice of an empty value in the listbox (as opposed to a null value) |
allownewvalues | boolean | no | false | Allow the user to enter values not in the listbox already |
defaultvalue | any | no | The default value of the parameter | |
dataset | no | Where to get the values for a listbox | ||
labelcolumn | string | no | Column in the datadefinition that supplies the label of the value to show the user | |
valuecolumn | string | no | Column in the datadefinition that supplies the value of the value to use in the SQL | |
uppercase | boolean | no | false | Should the value be converted to upper case in the generated SQL |
readonly | boolean | no | false | Can the user change the value |
readonlyoninsert | boolean | no | false | Can the user change the value when a new entity is being created |
readonlyonupdate | boolean | no | false | Can the user change the value when an entity is being edited |
updatable | boolean | no | true | Can the underlying value ever be changed once set (implied readonlyonupdate if set to true) |
value | any | formula or any | A value to insert into the database, provides a means of creating values beyond what the user enters (implied readonly if set | |
| persisted | boolean | no | false | Should the value the user chooses for the field become the default value for the field? |
| minvalue | any | no | The minimum value allowed for a field. Available from 2.5.28. | |
| maxvalue | any | no | The maximum value allowed for a field. Available from 2.5.28. | |
| minlength | integer | no | The minimum length allowed for a field. Available from 2.5.28. | |
| maxlength | integer | no | The maximum length allowed for a field. Available from 2.5.28. | |
| increment | integer | no | The increment to use for fields that support it, the units are dependant upon the field type. Available from 2.5.28 and currently only for time fields. |
A few things to not about the properties that can be applied to parameters:
...
| Note |
|---|
When geometry is being written to multiple spatial tables the count(), area() and length() functions will behave differently when used in an edit config item versus an edit audit item. |
Custom parameter examples
Auditing changes
To record who created and who modifies an entity use:
...
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 be 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.
...
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.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<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>
|
Check Boxes and Radio Buttons
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<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="checkbox">
<label>Check Box</label>
<controlType>checkbox</controlType>
<column>CHECKBOX</column>
<trueValue>Y</trueValue>
<falseValue xsi:nil="true"/>
</parameter>
<parameter id="radiobutton">
<label>Radio Button</label>
<controlType>radiobutton</controlType>
<column>RADIOBUTTON</column>
<defaultValue>value2</defaultValue>
<list>
<label>Label 1</label>
<value>value1</value>
</list>
<list>
<label>Label 2</label>
<value>value2</value>
</list>
<list>
<label>Label 3</label>
<value>value3</value>
</list>
</parameter>
</edit:config>
|
Writing to other tables
| Note |
|---|
Currently only writing new records to a separate database table is supported, that is you can not currently update an existing record in an external database table. |
...
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<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">
<mode>create,update,delete</mode> <!-- specify when audit records are written. create,update,delete is the default so this isn't really needed here -->
<edit>custom.edit</edit>
<datasource>datasource.main</datasource>
<table>EDIT_AUDIT</table>
<parameter column="ID" value="id()"/>
<parameter column="DESC" parameter="description"/>
<parameter column="GEOM" value="geometry()"/> <!-- at the moment this is text, not actual Geometry, in WKT format -->
<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
...
| Anchor | ||||
|---|---|---|---|---|
|
Localisation
It's possible to localise the text used in the edit panels so they're displayed in the local language of the user, this localisation is performed using the standard localisation mechanism outlined at Internationalisation and Localisation.
...
| Info |
|---|
It's possible, as of version 0.38 of the edit bundle to specify when, on create, update and/or delete, the audit record is written by specifying a 'mode' value in the audit config as a comma separated list of those three values. e.g The default, if not specified, is |
Create New Button
As of release 2.5.21 there is an additional button that can be added to a tool bar or status bar to immediately initiate the creation of a new object.
...
| Code Block |
|---|
<item action="weave.edit.createNew" entity="graffiti" edit="grafitti.edit"/> |
Overriding Edited Table
It's possible to override the table that Weave will update when the user submits an edit, rather than just using the table associated with the entity in the spatial mapper. This helps when working with views that can't be updated but the table that underlies the view can be.
...