.. _services_general:

.. This file is called "query.php.txt" when really it probably shoudl be "General_Services.txt" or "Standard_Services.txt

GeoMoose is configured with several standard services.  These services may be modified to allow customizations for a specific site.

Standard Services
=================================

birdseye
---------------------
birdseye –  a service called from the toolbar that provides a link to the Microsoft Bing! Maps. ::

	<service name="birdseye" target="_blank" title="Birds Eye View">
		<url>php/birdseye.php</url>
		<step type="spatial" name="xy" line="false" polygon="false" jump-start="true" default="point" format="delim" reproject="EPSG:4326">
			<header>
				Click on the map to view the area using Microsoft Bing! Maps.
			</header>
		</step>
	</service>

buffered_select
-------------------------
buffer_select – a service called from the toolbar that allows users to select parcels using a mouse ::

	<service name="buffered_select" title="Select Features">
		<url>php/select.php</url>

		<!-- Send a selection shape + the visible layers list to the service -->
		<step type="spatial" showTools="true" name="shape" line="true" polygon="true" point="true" default="polygon" edit-polygon="false" pan="false">

			<header><![CDATA[Create a selection area by clicking on the map.]]></header>

			<input type="visiblelayers" name="layers"/>

			<!-- 
				Option values should be the mapbook path to the layer.
				This only supports 'mapserver'-type layers.
			-->
			<input type="select" name="select_layer" title="Select features from:">
				<option value="parcels/parcels">Parcels</option>
			</input>
			
			<!--
			<input type="user" name="select_buffer" title="Buffer Selected Features (m)">0</input>
			-->

			<input type="length" name="selection_buffer" title="Buffer Selection Shape">0</input>
			<input type="select" name="query_layer" title="Using Features In">
				<option value="">No Layer</option>
				<option value="parcels/parcels">Parcels</option>
			</input>
			<input type="projection" name="projection"/>

			<footnote><![CDATA[
			]]></footnote>
		</step>
	</service>

buffered_select_followup
-------------------------------------------
buffered_select_followup – service called within the layer results (html template) for a selected set to buffer the selected set. ::

	<!-- this is called after a standard select in order to buffer the previous selection -->
	<service name="buffered_select_followup" title="Buffered Select">
		<url>php/select.php</url>
		<step type="input">
			<input type="hidden" name="shape"/>
			<input type="hidden" name="select_layer"/>
			<input type="hidden" name="query_layer"/>
			<input type="hidden" name="selection_buffer"/>
			<input type="length" name="shape_buffer" title="Buffer Features By: "/>
			<input type="projection" name="projection"/>
		</step>
	</service>

feature_report
-------------------------------------------
feature_report – featurereport: a service not called from the tool bar that is called from a feature layer html. ::

	<service name="feature_report" display="false" keep-others="true">
		<url>php/feature_report.php</url>
		<input type="hidden" name="layers" value="lmic/fsa"/>
		<input type="hidden" name="src"/>
		<input type="hidden" name="PIN"/>
	</service>

geocode_address
-------------------------------------------
geocode_address – a service called from the toolbar that allows users to GeoCode an address using googles geocode services. The google service requires a google key as used in the second input. ::

	<service name="geocode_address" title="Geocode Address">
		<url>php/geocode.php</url>
		<step type="input">
			<input type="user" name="address" title="Enter Address: "/>
			<input type="hidden" name="googlekey" value="ABQIAAAA4Q-VLyIpwp3L8M9DIzKb2BT2yXp_ZAY8_ufC3CFXhHIE1NvwkxRe8Hd6FR51Hvb-Fvd-wGjiDZDC4w"/>
		</step>
	</service>

identify
-------------------------------------------
identify – a services called from the toolbar that allows users to identify visible features ::

	<service name="identify" title="Identify" display="true">
		<url>php/identify.php</url>
		<step type="spatial" name="shape" line="false" polygon="false" jump-start="true" default="point" box="true" pan="false">
			<header>
				Click on the map to see more detailed information.
			</header>
			<input type="visiblelayers" name="layers"/>
			<input type="projection" name="projection"/>
		</step>
	</service>

popups
-------------------------------------------
popups – This service is not available at this time. 

print
-------------------------------------------
print – a service called from the toolbar that allows printing to an IMAGE, HTML, or PDF.  The print service uses templates stored in the geomoose2/conr/print directory. ::

	<service name="print" title="Print Map" keep-others="true">
		<step type="input">
			<url>php/print.php</url>
			<input type="print_info" name="layers"/>
			<input type="extent" name="extent"/>

			<input type="user" name="title" title="Map Title">Map</input>
			<input type="hidden" name="date" title="Map Date">true</input>

			<input type="select" name="template" title="Output Template: ">
				<option value="letter_landscape">Letter - Landscape</option>
				<option value="letter_portrait">Letter - Portrait</option>
				<option value="poster_landscape">11" x 17" - Landscape</option>
				<option value="poster_portrait">11" x 17" - Portrait</option>
			</input>

			<input type="select" name="quality" title="Image Quality: ">
				<option value="2">Higher</option>
				<option value="3">Highest</option>
				<option value="1">Standard</option>
			</input>

			<input type="select" name="scale" title="Print Scale: ">
				<option value="map">Current Map Scale</option>
				<option value="1000">1:1000</option>
				<option value="5000">1:5000</option>
				<option value="10000">1:10000</option>
			</input>
		</step>
	</service>

search_parcels
-------------------------------------------
search_parcels – This service called from the tool bar menu allows you to query and search for parcels. ::

	<service name="search_parcels" title="Search">
		<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>

streetview
-------------------------------------------
streetview – a service called from the toolbar that provides a link to Google Street View ::

	<service name="streetview" target="_blank" title="Street View">
		<url>php/streetview.php</url>
		<step type="spatial" name="xy" line="false" polygon="false" jump-start="true" default="point" format="delim" reproject="EPSG:4326">
			<header>
				Click on the map to view the point in Google Street View.
			</header>
		</step>
	</service>

.. _query:

query
------------------------------------------

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 intended 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 searched 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.
	* "in" - Inputs a semi-colon seperated list of values and performs an equals match with them.
 * `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>

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>

This example is the current service in the demo::

	<service name="search_parcels" title="Search">
		<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>

Additional resources
------------------------------------------
See also, :ref:`mapbook_services`.