<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % cartoweb SYSTEM "../cartoweb.ent" >
  %cartoweb;
  ]>
<!-- $Id: query.xml,v 1.22 2007-07-10 11:58:24 sypasche Exp $ -->
<chapter id="user.query">
  <title>Queries</title>
  <subtitle>Plugins Query, MapQuery, Hilight and Tables</subtitle>
  <para>Core plugin Query allows to search for geographical objects. Found 
    objects are hilighted and if requested related data are returned to client. 
    </para>
  <para>Depending on configuration and user choices, queries are executed on 
    one layer, several layers or all layers currently displayed on map.</para>
  <para>Queries can be executed on a geographic selection or using a list of 
    object IDs. Geographic selection can be a point, a rectangle, a polygon or
    a circle but is a rectangle by default. The second way to execute a query is 
    used in particular to maintain selection persistence: object IDs are stored 
    client-side and sent to server each time the page is reloaded.</para>
  <para>Hilighting objects can be done using standard Mapserver queries or 
    using special Hilight plugin. See <xref 
    linkend="user.query.mapfile.hilight" /> for more information.</para>
  <para>Results are returned and displayed using Tables plugin. See <xref 
    linkend="user.query.client.tables" /> for more information.</para>
  <sect1 id="user.query.client">
    <title>Client-side Configuration</title>
    <sect2 id="user.query.client.ini">
      <title>query.ini</title>
      <para> Here are the options that can be set in client's query.ini: </para>
      <itemizedlist>
        <listitem>
          <para> 
            persistentQueries<indexterm><primary>persistentQueries</primary></indexterm>: 
            if true, queries will be persistent. If false, selection is lost 
            after next page reload. Note that persistency will work only with 
            layers with id_attribute_string set (see <xref 
            linkend="user.query.mapfile" />) </para>
        </listitem>
        <listitem>
          <para> 
            displayExtendedSelection<indexterm><primary>displayExtendedSelection</primary></indexterm>: 
            if true, shows form for selection extended functions. This form is 
            mainly used by developers (see TODO: link to developer's doc)</para>
        </listitem>
        <listitem>
          <para> 
            queryLayers<indexterm><primary>queryLayers</primary></indexterm>: 
            the comma separated list of layers which will appear in the 
            extended selection form. If this list is absent, all msLayers 
            appear in the form.</para>
        </listitem>
        <listitem>
          <para> 
            returnAttributesActive<indexterm><primary>returnAttributesActive</primary></indexterm>: 
            if true, the layers attributes can be requested. If false, only 
            object IDs will be returned (default: false)</para>
        </listitem>
        <listitem>
            <para> defaultPolicy<indexterm>
                <primary>defaultPolicy</primary></indexterm>: can be either
                POLICY_XOR, POLICY_UNION, POLICY_INTERSECTION or POLICY_REPLACE.
                Defines how new selected objects are mixed with previous ones (default:
                POLICY_XOR)</para>
        </listitem>
        <listitem>
            <para> defaultMaskmode<indexterm>
                <primary>defaultMaskmode</primary></indexterm>: if true, selected
                objects are highlighted in mask mode (default: false). See also <xref
                    linkend="user.query.mapfile.hilight.mask"/></para>
        </listitem>
        <listitem>
          <para> 
            defaultHilight<indexterm><primary>defaultHilight</primary></indexterm>: 
            if true, objects are highlited (default: true)</para>
        </listitem>
        <listitem>
          <para> 
            defaultAttributes<indexterm><primary>defaultAttributes</primary></indexterm>: 
            if true, the layers attributes are returned (default: true)</para>
        </listitem>
        <listitem>
          <para> 
            defaultTable<indexterm><primary>defaultTable</primary></indexterm>: 
            if true, the results table is displayed (default: true)</para>
        </listitem>
        <listitem>
          <para> 
            weightQueryByPoint<indexterm><primary>weightQueryByPoint</primary></indexterm>: 
            integer which defines display order of the query by point tool icon in 
            toolbar (default: 40). Negative weighted tools are disabled</para>
        </listitem>
        <listitem>
          <para> 
            weightQueryByBbox<indexterm><primary>weightQueryByBbox</primary></indexterm>: 
            see weightQueryByPoint (default: 41).</para>
        </listitem>
        <listitem>
          <para> 
            weightQueryByPolygon<indexterm><primary>weightQueryByPolygon</primary></indexterm>: 
            see weightQueryByPoint (default: 42).</para>
        </listitem>
        <listitem>
          <para> 
            weightQueryByCircle<indexterm><primary>weightQueryByCircle</primary></indexterm>: 
            see weightQueryByPoint (default: 43). </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="user.query.client.tables">
      <title>Tables Configuration</title>
      <para> Tables plugin can be used by any plugin to manage, transfer and 
        display tables structure. In basic &cartoweb; installation, only Query 
        plugin uses this functionality. </para>
      <para>To configure table appearance, use tables client-side rules 
        described in Developer's Documentation (<xref 
        linkend="dev.newplugin.special.tables" />).</para>
    </sect2>
  </sect1>
  <sect1 id="user.query.server">
    <title>Server-side Configuration</title>
    <sect2 id="user.query.server.ini">
      <title>query.ini</title>
      <para> Here are the options that can be set in server's query.ini: </para>
      <itemizedlist>
        <listitem>
          <para> 
            drawQueryUsingHilight<indexterm><primary>drawQueryUsingHilight</primary></indexterm>: 
            if true, query hilighting will use Hilight plugin. In this case, 
            Hilight plugin must be loaded on server. If false, objects will be 
            hilighed using MapServer query functionality. See also <xref 
            linkend="user.query.mapfile.hilight" /> (default:
            false)</para>  
        </listitem>
        <listitem>
          <para> 
            noRowId<indexterm><primary>noRowId</primary></indexterm>: 
            if true, row id will not be included in the table. In this
            case the row id will not be displayed in the output table
            (html, pdf, etc.). (default:
            false)</para>  
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="user.query.server.mapquery">
      <title>MapServer Query Configuration</title>
      <para> MapQuery plugin can be used by any plugin to retrieve objects 
        information from MapServer. </para>
      <para>Following options can be set in server's mapquery.ini: </para>
      <itemizedlist>
        <listitem>
          <para> 
            maxResults<indexterm><primary>maxResults</primary></indexterm>: 
            Maximum number of results to handle in the query plugin. This limit 
            is to avoid high load on the server. It should be the client 
            responsibility not to ask too many objects to avoid reaching this 
            limit. Ignoring big queries can be done with the 
            ignoreQueryThreshold parameter, which give a better behaviour for 
            the user </para>
        </listitem>
        <listitem>
          <para> 
            ignoreQueryThreshold<indexterm><primary>ignoreQueryThreshold</primary></indexterm>: 
            Do not take into account the elements selected by a shape 
            (rectangle, polygon) in a query, if this shape intersects more than 
            ignoreQueryThreshold objects. It should be less than maxResults to 
            have informative messages to the user </para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1 id="user.query.mapfile">
    <title>Related Elements in Mapfile</title>
    <sect2 id="user.query.mapfile.queriable">
      <title>Making a Layer Queriable</title>
      <para>
        To make a MapServer layer queriable, one have to add a <parameter>TEMPLATE</parameter> parameter 
        in the mapfile layer definition. In our case, any value fits. For instance:
      </para>
      <programlisting>LAYER
  NAME "foobar"
  ...
  TEMPLATE "ttt"
  ...
END
</programlisting>
    </sect2>
    <sect2 id="user.query.mapfile.metadata">
      <title>Meta Data</title>
      <para> Here are the meta data that can be set to mapfile's layers: </para>
      <itemizedlist>
        <listitem>
          <para> 
            "id_attribute_string"<indexterm><primary>id_attribute_string</primary></indexterm> 
            "name|type": describes the attribute used for the id, and the type 
            of the id. Type can be either "int" or "string". Caution: case 
            sensitive</para>
        </listitem>
        <listitem>
          <para> 
            "query_returned_attributes"<indexterm><primary>query_returned_attributes</primary></indexterm> 
            "attribute1 attribute2": the names (space separated) of the fields 
            returned by a query. If not set, all fields are returned. Caution: 
            case sensitive</para>
        </listitem>
        <listitem>
          <para> 
            "hilight_use_logical_expressions"<indexterm>
               <primary>hilight_use_logical_expressions</primary></indexterm> 
            "true"/"false": Set this to true if you are using a layer for
             hilight (using the convention <code>yourlayer_hilight</code>) and
             you want to preserve your expressions in the hilight layer for
             hilighted objects. IMPORTANT: you need to set this metadata on the
             hilight layer, not the original one.</para>
        </listitem>
      </itemizedlist>
      <para>Example:<programlisting><![CDATA[
METADATA
  "id_attribute_string" "FID|string"
  "query_returned_attributes" "FID FNAME"
END]]> </programlisting> </para>
    </sect2>
    <sect2 id="user.query.mapfile.hilight">
      <title>Hilight Configuration</title>
      <indexterm><primary>Hilight</primary></indexterm>
      <para> Hilight plugin can be used by any plugin to hilight objects on the 
        map. In basic &cartoweb; installation, only Query plugin uses this 
        functionality. As Hilight plugin is not a core plugin, it must be 
        loaded in order to use it with queries.</para>
      <sect3 id="user.query.mapfile.hilight.normal">
        <title>Normal Mode</title>
        <para> Hilight on a specific layer can be generated by several means: 
          special layer activation, special class activation, dynamic 
          layer/class generation. Decision is made in the following order: 
          </para>
        <orderedlist>
          <listitem>
            <para>looks for a layer named "&lt;layer_name&gt;_hilight" </para>
          </listitem>
          <listitem>
            <para>if not found, looks for a class named "hilight" in the 
              current layer </para>
          </listitem>
          <listitem>
            <para>if not found, dynamically creates a layer if meta data 
              "hilight_createlayer" is set to "true" </para>
          </listitem>
          <listitem>
            <para>if meta data "hilight_createlayer" is not set or set to 
              "false", dynamically creates a class</para>
          </listitem>
        </orderedlist>
        <para>Here are the meta data that can be set to mapfile's layers: 
          </para>
        <itemizedlist>
          <listitem>
            <para> 
              "hilight_color"<indexterm><primary>hilight_color</primary></indexterm> 
              "0-255 0-255 0-255": the hilight color of a dynamically generated 
              class</para>
          </listitem>
          <listitem>
            <para> "hilight_createlayer" 
              <indexterm><primary>hilight_createlayer</primary></indexterm> 
              "true": if true, a new layer will be dynamically generated for 
              the hilight </para>
          </listitem>
          <listitem>
            <para> "hilight_transparency" 
              <indexterm><primary>hilight_transparency</primary></indexterm> 
              "1-100": the transparency, for dynamically generated layers</para>
          </listitem>
        </itemizedlist>
        <para>Examples: </para>
        <para>Hilight using "&lt;layer_name&gt;_hilight" layer <programlisting><![CDATA[
LAYER
  NAME "foo"
  ...
END

LAYER
  NAME "foo_hilight"
  ...
END]]> </programlisting> </para>
        <para>Hilight using class "hilight" <programlisting><![CDATA[
LAYER
  NAME "foo"
  ...
  CLASS
    EXPRESSION /_always_false_/
    NAME "hilight"
    STYLE
      ...
    END
  END
  # other layer classes
  CLASS
    ...
  END
END]]> </programlisting> </para>
        <para>Hilight using dynamically generated layer <programlisting><![CDATA[
LAYER
  NAME "foo"
  ...
  METADATA
    "hilight_createlayer" "true"
    "hilight_color" "255 255 0"
    "hilight_transparency" "50"
  END
END]]> </programlisting> </para>
      </sect3>
      <sect3 id="user.query.mapfile.hilight.mask">
        <title>Mask Mode</title>
        <para> When mask mode is requested, decision is made in the following 
          order: </para>
        <orderedlist>
          <listitem>
            <para>looks for a layer named "&lt;layer_name&gt;_mask" </para>
          </listitem>
          <listitem>
            <para>if not found, dynamically creates a mask layer by copying 
              current layer </para>
          </listitem>
        </orderedlist>
        <para> Masking process also tries to find a layer which would hide the 
          area outside all possible selections: </para>
        <orderedlist>
          <listitem>
            <para>tries to activate a layer with name set in meta data 
              "outside_mask"</para>
          </listitem>
          <listitem>
            <para>if meta data "outside_mask" is not set, looks for a layer 
              named "default_outside_mask" </para>
          </listitem>
          <listitem>
            <para>if not found, no outside mask will be displayed </para>
          </listitem>
        </orderedlist>
        <para> Here are the meta data that can be set to mapfile's layers: 
          </para>
        <itemizedlist>
          <listitem>
            <para> "mask_color" 
              <indexterm><primary>mask_color</primary></indexterm> "0-255 0-255 
              0-255": color of the mask when mask layer 
              (&lt;layer_name&gt;_mask) is not defined</para>
          </listitem>
          <listitem>
            <para> "mask_transparency" 
              <indexterm><primary>mask_transparency</primary></indexterm> 
              "true": transparency of the mask when mask layer 
              (&lt;layer_name&gt;_mask) is not defined </para>
          </listitem>
          <listitem>
            <para> "outside_mask" 
              <indexterm><primary>outside_mask</primary></indexterm> 
              "layer_name": name of layer which will mask the outside (aka 
              "complement"). If not set, will try to find a layer named 
              "default_outside_mask" </para>
          </listitem>
        </itemizedlist>
        <para> Examples: </para>
        <para>Mask using "&lt;layer_name&gt;_mask" layer <programlisting><![CDATA[
LAYER
  NAME "foo"
  ...
END

LAYER
  NAME "foo_mask"
  ...
END]]> </programlisting> </para>
        <para>Mask using "&lt;layer_name&gt;_mask" layer and an outside mask 
          <programlisting><![CDATA[
LAYER
  NAME "foo"
  METADATA
    "outside_mask" "bar"
  END
  ...
END

LAYER
  NAME "foo_mask"
  ...
END

LAYER
  NAME "bar"
  ...
END]]> </programlisting> </para>
        <para>Mask using dynamically generated layer and default outside mask 
          <programlisting><![CDATA[
LAYER
  NAME "foo"
  METADATA
    "mask_color" "255 255 255"
    "mask_transparency" "60"
  END
  ...
END

LAYER
  NAME "default_outside_mask"
  ...
END]]> </programlisting> </para>
      </sect3>
    </sect2>
  </sect1>
</chapter>
