Spatial Search

A spatial search is similar to an attribute search, but uses the results of the search to then perform a geometry intersection search on another entity, which is the real target of the search.

So a spatial search works like this:

The user enters the search parameters and submits the search
The server searches for the source entities that match the search parameters
The geometry of the found source entities are then used in a spatial search for the target entities
The selection for the target entities is then updated based on the results of the spatial search

The spatial search has been extended to provide support for performing an attribute search against a spatial engine.
That is a spatial search can now be used to perform the same function as an attribute search, but rather than performing the operation against a database table it's performed against a spatial engines layer.

None of the operations outlined above in "So a spatial search works like this" is performed, instead the operation more closely follows what an attribute search performs, i.e. finding rows in a layer that have attributes that match what a user has entered.

The configuration of the spatial attribute search follows more closely that of the attribute search, but because it is using the underlying API of the spatial engine, rather than SQL as the attribute search does (although some spatial engines also use SQL as their API) the support and configuration may be different depending upon the level of support provided by the underlying spatial engine, for example a spatial search operating on a spatial engine that's pointing to a directory of shapefiles may operate differently from one that's pointing to ArcSDE, this is similar to the differences in an attribute search that's pointing to an Oracle database verses one that's pointing to SQL Server.

Namespace

urn:com.cohga.server.search.spatial#1.0

Tags

spatial

Properties

Name	Type	Required	Description
id	string	yes	unique identifier for this search
entity	ref urn:com.cohga.server.entity#1.0:entity	yes	The id of the entity that this search will be searching for
sourceEntity (or sourceentity)	ref urn:com.cohga.server.entity#1.0:entity	yes	The id of the entity that the search parameters apply to
displayName (or displayname)	string	yes	Text to be displayed to the user to represent this search
description	string	no	Description of the search that could be displayed to the user to explain this search
acl	ref urn:com.cohga.server.acl#1.0:acl	no	A reference to an ACL to attach to the search

Sub-tags

Name	Type	Cardinality
parameter	urn:com.cohga.server.search.database#1.0:parameter	1..n
acl	urn:com.cohga.server.acl#1.0:acl	0..1
cache	urn:com.cohga.server.cache#1.0:cache	0..1

Content

None

Notes

An ACL can either be defined in-line or referenced indirectly, but only one should be used (the in-line version will take priority)

parameter

Properties

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	yes		The name of the column within the table that this parameter references
displayname	string	no	label	Provides a user-friendly name for the element
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'	no	'textbox'	The suggested type of UI control to use when displaying the parameter
datatype	'any', 'boolean', 'datetime', 'decimal', 'float', '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
displayformat	string	no		The formatting instructions for the parameter value within the parameter UI
dataset	ref urn:com.cohga.server.data.database#1.0:datadefinition	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

Sub-tags

Name	Type	Cardinality
parameter	urn:com.cohga.server.data.database#1.0:parameter	0..n

Notes

If the controltype is listbox then a dataset must be provided. This dataset will provide the values to be displayed in the listbox.
If the listbox dataset only contains 1 column then that column will supply both the label and the value, if it contains two values then the first column will supply the label and the second the value.
If a parameter contains another parameter then you are defining a cascading parameter, where setting the first sub-parameter will enable, and filter, the second parameter, and setting the second parameter will do the same for the third, etc.
In a cascading parameter all sub-parameters must be of listbox type, and the dataset should be set in the outer parameter, not the sub parameters.
In a cascading parameter only one level of nesting should be used.
In a cascading parameter the dataset should supply the columns for all of the parameters, and valuecolumn properties should be set for each sub-parameter, and labelcolumn should be also set for all parameters if a different label is to be displayed to the user.

Spatial operation types

By default Weave will use a spatial intersection operation when performing the comparison between the source and target geometries.
This can be changed by specifying a "spatialOperation" option in the config, see the example below.
The available options for the spatial operation setting are:

intersect - The geometries have at least one point in common
contains - One geometry contains another
disjoint - The geometries have no points in common
crosses - The geometries do more than touch, they actually overlap edges
touches - The geometries only touch edges and do not overlap in any way
within - One geometry is completely within another (no touching edges)

Examples

<data:datadefinition id="dd_wards">
	<datasourcedataconnection datasource="datasource.main" table="WARDS" prefix="DISTINCT">
		<parameter name="name" column="WARD_NAME"/>
		<parameter name="code" column="WARD_CODE"/>
	</datasourcedataconnection>
</data:datadefinition>

<search:spatial id="property.byward">
	<displayname>by Ward Boundary</displayname>
	<description>Locate a property or properties by ward</description>
	<entity>property</entity>
	<sourceentity>ward</sourceentity>
	<parameter id="ward">
		<dataset>dd_wards</dataset>
		<label>Ward Name</label>
		<controltype>listbox</controltype>
		<column>CODE</column>
		<valuecolumn>code</valuecolumn>
		<labelcolumn>name</labelcolumn>
	</parameter>
</search:spatial>

Search with buffer

<search:spatial id="property.byward">
	<displayname>by Ward Boundary</displayname>
	<description>Locate a property or properties by ward</description>
	<entity>property</entity>
	<sourceentity>ward</sourceentity>
	<parameter id="ward">
		<dataset>dd_wards</dataset>
		<label>Ward Name</label>
		<controltype>listbox</controltype>
		<column>CODE</column>
		<valuecolumn>code</valuecolumn>
		<labelcolumn>name</labelcolumn>
	</parameter>
	<options:options>
		<!-- version 1.4.105 of com.cohga.server.search.database and earlier -->
		<buffer:distance>-10</buffer:distance>
		<!-- version 1.5.105 of com.cohga.server.search.database and later -->
		<buffer>-10</buffer>
		<bufferUnits>m</bufferUnits>
	</options:options>
</search:spatial>

Changing the spatial operation type

<search:spatial id="property.byward">
	<displayname>by Ward Boundary</displayname>
	<description>Locate a property or properties by ward</description>
	<entity>property</entity>
	<sourceentity>ward</sourceentity>
	<parameter id="ward">
		<dataset>dd_wards</dataset>
		<label>Ward Name</label>
		<controltype>listbox</controltype>
		<column>CODE</column>
		<valuecolumn>code</valuecolumn>
		<labelcolumn>name</labelcolumn>
	</parameter>
	<options:options>
		<spatialOperation>within</spatialOperation>
	</options:options>
</search:spatial>

Performing an "attribute" search against a spatial engine

<search:spatial id="ward">
	<displayname>by Ward Name</displayname>
	<description>Locate a ward by name</description>
	<entity>ward</entity>
	<parameter id="ward">
		<dataset>dd_wards</dataset>
		<label>Ward Name</label>
		<controltype>listbox</controltype>
		<column>CODE</column>
		<valuecolumn>code</valuecolumn>
		<labelcolumn>name</labelcolumn>
	</parameter>
</search:spatial>