General Query Service (query.php)
=================================

*2.2+ ONLY*

General Description
-------------------
GeoMOOSE provides a general query service that allows the user to query multiple layers and fields through a single CGI query.  Results can be optionally highlighted.

The Query service is intented to replace the itemquery.php service and eventually the identify service.  Both ItemQuery and Identify may be dropped as of the official 2.0 release. Currently Shapefiles, OGR, Oracle Spatial, and PostGIS are the only supported layer types for the General Query Service.  If you plan to search a layer other than you may consider modifying query.php to meet your needs or write another service entirely.

Important settings.ini Variables
--------------------------------

 * query_header - This will be prepended to the HTML results.
 * query_footer - This will be append to the HTML results.
 * query_miss - This is the message that will be displayed when no results are found.

*As a compatibility step, the current version of query.php will default to using the "itemquery_..." versions of the above settings when it cannot find the proper "query_..." settings.*

Parameters
----------
The parameters for this service are unique because they can be variable based on the number of fields and layers that will be queried by the service.

 * `mode` is a hidden input that should always be set to "search".
 * `highlight` is a hidden input that is a boolean.  "True" will mean the selected features will be highlighted, "false" means they will not be highlighted.
 * `zoom_to_first` is a hidden input that is a boolean.  When set to "true" GeoMOOSE will always zoom to the first feature found in the search, when set to "false" GeoMOOSE will not exhibit this behaviour.
 * `layer[0..n]` is the Mapbook path of the layer to search.  Only the 1st layer (layer0) is required.  If no other layers are specified then it is assumed that the target of all of the following inputs are layer0.
 * `value[0..n]` the value which should be search against.  Only the 1st value (value0) is required.  If no other values are specified then it is assumed that the initial value will be used to search all other fieldnames.
 * `fieldname[0..n]` is the name of the field in the table or DBF to search against.  This is required for every field.
 * `comparitor[0..n]` is the name of the comparison operator.  Valid comparison operators include:
 	* "eq-str" - String equals match.
	* "like" - Case-sensitive contains operator.  The equivalent SQL is "fieldname like '%value%'".
	* "right-like" - Case-sensitive "begins with" operator.  The equivalent SQL is "fieldname like 'value%'"
	* "left-like" - Case-sensistive "ends with" operator.  The equivalent SQL is "fieldname like '%value'"
	* "like-icase" - Case-insensitive "like."
	* "right-like-icase" - Case-insensitive "right-like."
	* "left-like-icase" - Case-insensitive "left-like."
	* "eq" - Equals operator.  This is used for numeric operations.
	* "gt" - Greater-than operator.
	* "lt" - Less-than operator.
	* "ge" - Greather-than or equal-to operator.
	* "le" - Less-than or equal-to operator.
 * `operator[1..n]` is the type of connecting operator between searching predicates.  There is no "operation0" as it is the start of the search-string and there is not a connecting operator.
 	* "and" - Require both this statement (n) and the previous one (n-1).
	* "or" - Require either this statement (n) or the previous one (n-1).
	* "nand" - Require this statement to be false (n) and the previous one to be true (n-1).
	* "nor" - Require this statement to be false (n) or the previous one to be true (n-1).
* `blanks[0..n]` is a hidden boolean tied to the value[0..n].  If set to "true" blank values will mean this predicate is ignored, when set to "false" then a blank value will be evaluated.
* `template[0..n]` specifies the template to use.  This template is specified in the LAYER's METADATA tag.  Only template0 is required.  If no other templates are specified it will try to use the template named in template0 for all layers.  For example, to mimic the itemquery functionality the "itemquery" template is used in the examples below.  It is possible to use other templates, such as `identify_record`, and is even possible to provide this as a drop-down option to the user.  This would allow a single search to have different result outputs.

Sample Mapbook Service Definitions
----------------------------------

This is a basic example that emulates the old itemquery.php service::

	<service name="search_parcels">
		<url>php/query.php</url>
		<step type="input">
			<input type="select" name="fieldname0" title="Search By:">
				<option value="OWNER_NAME">Owner</option>
				<option value="PIN">Parcel ID</option>
			</input>
			<input type="hidden" name="comparitor0" value="like-icase"/>
			<input type="user" name="value0" title=""/>
			<input type="hidden" name="layer0" value="parcels/parcels"/>
			<input type="hidden" name="template0" value="itemquery"/>

			<input type="hidden" name="highlight" value="true"/>
			<input type="hidden" name="mode" value="search"/>
		</step>
	</service>

This is an example that allows the user to choose what comparitor is used to search::

	<service name="search_parcels">
		<url>php/query.php</url>
		<step type="input">
			<input type="select" name="fieldname0" title="Search By:">
				<option value="OWNER_NAME">Owner</option>
				<option value="PIN">Parcel ID</option>
			</input>
			<input type="select" name="comparitor0" title="That: ">
				<option value="like-icase">Contains</option>
				<option value="right-like-icase">Begins With</option>
				<option value="eq-str">Matches Exactly</option>
			</input>
			<input type="user" name="value0" title=""/>
			<input type="hidden" name="layer0" value="parcels/parcels"/>
			<input type="hidden" name="template0" value="itemquery"/>

			<input type="hidden" name="highlight" value="true"/>
			<input type="hidden" name="mode" value="search"/>
		</step>
	</service>


Finally, this example shows searching multiple fields with selectable operators and comparitors::

	<service name="search_parcels">
		<url>php/query.php</url>
		<step type="input">
			<input type="hidden" name="highlight" value="true"/>
			<input type="hidden" name="mode" value="search"/>

			<input type="hidden" name="layer0" value="parcels/parcels"/>
			<input type="hidden" name="template0" value="itemquery"/>

			<input type="select" name="fieldname0" title="Search By:">
				<option value="OWNER_NAME">Owner</option>
				<option value="PIN">Parcel ID</option>
			</input>
			<input type="select" name="comparitor0" title="That: ">
				<option value="like-icase">Contains</option>
				<option value="right-like-icase">Begins With</option>
				<option value="eq-str">Matches Exactly</option>
			</input>
			<input type="user" name="value0" title=""/>

			<input type="hidden" name="fieldname1" value="FIN_SQ_FT"/>
			<input type="select" name="operator1">
				<option value="or">OR</option>
				<option value="and">AND</option>
			</input>
			<input type="select" name="comparitor1" title="Having Fin. Sq. Ft. ">
				<option value="gt">Greater Than</option>
				<option value="eq">Equal To</option>
				<option value="lt">Less Than</option>
			</input>
			<input type="user" name="value1" title=""/>
		</step>
	</service>