<?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: location.xml,v 1.29 2007-07-31 09:57:54 ochriste Exp $ -->
<chapter id="user.location">
  <title>Navigation</title>
  <subtitle>Plugin Location</subtitle>
  <para> The plugin location is the core plugin that deals with geographic 
    navigation on the map. It handles bboxes (visible areas) and scales; it 
    drives the tools zoom-in, zoom-out and panning, the directional arrows 
    around the main map and the overview map. </para>
  <para> The corresponding configuration files are 
    <filename>location.ini</filename> (client-side) and 
    <filename>location.ini</filename> (server-side). </para>
  <sect1 id="user.location.client">
    <title>Client-side Configuration</title>
    <para> Here are the options that can be set: </para>
    <itemizedlist>
      <listitem>
        <para> 
          scalesActive<indexterm><primary>scalesActive</primary></indexterm>: 
          boolean, if true, the scales dropdown list is displayed (default: 
          false). If no visible scales are defined on the server, a simple 
          input text will be displayed. </para>
      </listitem>
      <listitem>
        <para> 
          freeScaleActive<indexterm><primary>freeScaleActive</primary></indexterm>: 
          boolean, if true, the free scales input is displayed (default: 
          false). This allow the user to freely set a scale value that is different from 
          the predefined scales. There are a few conditions for this to work:
            <itemizedlist>
              <listitem>
                <para>scalesActive must be activated (see above).</para>
              </listitem>
              <listitem>
                <para>scaleModeDiscrete must be deactivated (false) (see Server-side 
                Configuration).</para>
              </listitem>
              <listitem>
                <para>location.js must be loaded.</para>
              </listitem>
              <listitem>
                <para>prototype.js must be loaded (by default if ajax is on).</para>
              </listitem>
            </itemizedlist>
          </para>
      </listitem>      
      <listitem>
        <para> 
          recenterActive<indexterm><primary>recenterActive</primary></indexterm>: 
          boolean, if true, the coords recentering form is displayed (default: 
          false) </para>
      </listitem>
      <listitem>
        <para> 
          idRecenterActive<indexterm><primary>idRecenterActive</primary></indexterm>: 
          boolean, if true, the id recentering fields will be displayed 
          (default: false) </para>
      </listitem>
      <listitem>
        <para> 
          idRecenterLayers<indexterm><primary>idRecenterLayers</primary></indexterm> 
          the comma separated list of layers which will appear in the id 
          recentering selection form. If this list is absent, all msLayers 
          appear in the form. </para>
      </listitem>
      <listitem>
        <para> 
          shortcutsActive<indexterm><primary>shortcutsActive</primary></indexterm>: 
          boolean, if true, the shortcuts (direct access dropdown list) are 
          displayed (default: false) </para>
      </listitem>
      <listitem>
        <para> 
          scaleUnitLimit<indexterm><primary>scaleUnitLimit</primary></indexterm>: 
          scale above which DHTML measures use km ; below, they use m. </para>
      </listitem>
      <listitem>
        <para> panRatio<indexterm><primary>panRatio</primary></indexterm>: 
          ratio for panning by clicking directional arrows. Default is 1 (no 
          overlap, no gap). Values below 1 result in an overlap of the old and 
          the new maps; values above 1 in a gap between these two maps. </para>
      </listitem>
      <listitem>
        <para> 
          weightZoomin<indexterm><primary>weightZoomin</primary></indexterm>: 
          integer defining display order of the zoomin tool icon in toolbar 
          (if not specified, default to 10). A negative weight disables the 
          tool.
            <note>
                <para>Zoomin is the default tool and it will be activated automaticaly. 
                If you want to deactivate it, you need to set another default tool. See 
                <parameter>initialTool</parameter> in <xref linkend="user.config.client"/>.
                </para>
            </note>          
          </para>
      </listitem>
      <listitem>
        <para> 
          weightZoomout<indexterm><primary>weightZoomout</primary></indexterm>: 
          see weightZoomin (default to 11) </para>
      </listitem>
      <listitem>
        <para> weightPan<indexterm><primary>weightPan</primary></indexterm>: 
          see weightZoomin (default to 12) </para>
      </listitem>
      <listitem>
        <para> weightFullextent<indexterm><primary>weightFullextent</primary></indexterm>: 
          see weightZoomin (default to 14) </para>
      </listitem>
      <listitem>
        <para> crosshairSymbol<indexterm><primary>crosshairSymbol</primary></indexterm>:
               (integer) numerical id of symbol to use to materialize recentering point 
               (see your <parameter>symbolset</parameter> file)</para>
      </listitem>
      <listitem>
        <para> crosshairSymbolSize<indexterm><primary>crosshairSymbolSize</primary></indexterm>:
               integer defining the size used to display the recentering crosshair symbol.</para>
      </listitem>
      <listitem>
        <para> crosshairSymbolColor<indexterm><primary>crosshairSymbolColor</primary></indexterm>:
               RGB code (comma-separated list of integers) of the crosshair color.</para>
      </listitem>
        <listitem>
            <para> showRefMarks<indexterm>
                <primary>showRefMarks</primary></indexterm>: if true, will add
                reference marks to the main map. Reference marks configuration is set on
                server. </para>
        </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="user.location.server">
    <title>Server-side Configuration</title>
    <para> Here are the options that can be set: </para>
    <itemizedlist>
      <listitem>
        <para> minScale<indexterm><primary>minScale</primary></indexterm>: if 
          set, minimal scale allowed. </para>
      </listitem>
      <listitem>
        <para> maxScale<indexterm><primary>maxScale</primary></indexterm>: if 
          set, maximal scale allowed </para>
      </listitem>
      <listitem>
        <para> 
          scaleModeDiscrete<indexterm><primary>scaleModeDiscrete</primary></indexterm>: 
          boolean, if true, only specified scales (see below) can be set. 
          </para>
      </listitem>
      <listitem>
        <para> zoomFactor<indexterm><primary>zoomFactor</primary></indexterm>: 
          the zoom factor to use whan scaleModeDiscrete is set to false. </para>
      </listitem>
      <listitem>
        <para> noBboxAdjusting<indexterm><primary>noBboxAdjusting</primary></indexterm>: 
          If set to true, all data contained in the initial extent (mapfile)
          is visible on the full extent (first) map. This case is the default 
          mapserver behavior. If set to false (default), the user won't be 
          able to see anything outside the initial extent, even on full extent 
          map.</para>
      </listitem>
      <listitem>
        <para> 
          scales.#.value<indexterm><primary>scales.#.value</primary></indexterm> 
          (# = 0, 1, 2, ...): available value of the scale in discrete mode. 
          </para>
      </listitem>
      <listitem>
        <para> 
          scales.#.label<indexterm><primary>scales.#.label</primary></indexterm> 
          (# = 0, 1, 2, ...): label of the scale, to be displayed in the 
          dropdown list on the client. </para>
      </listitem>
      <listitem>
        <para> 
          scales.#.visible<indexterm><primary>scales.#.visible</primary></indexterm> 
          (# = 0, 1, 2, ...): boolean, if true, the scale is displayed in the 
          dropdown list. If false, this scale can only be selected by 
          zoom-in/zoom-out. Default is true. </para>
      </listitem>
      <listitem>
        <para> 
          shortcuts.#.label<indexterm><primary>shortcuts.#.label</primary></indexterm> 
          (# = 0, 1, 2, ...): label of the shortcut; appears in the direct 
          access dropdown list on the client. </para>
      </listitem>
      <listitem>
        <para> 
          shortcuts.#.bbox<indexterm><primary>shortcuts.#.bbox</primary></indexterm> 
          (# = 0, 1, 2, ...): geographic bbox of the shortcut. </para>
      </listitem>
      <listitem>
        <para> 
          recenterMargin<indexterm><primary>recenterMargin</primary></indexterm>: 
          margin to add around the centered-on object (valid for lines and 
          polygons). Expressed in percent of the width/height of the object.
          If not set, recenterDefaultScale is used. 
          </para>
      </listitem>
      <listitem>
        <para> 
          recenterDefaultScale<indexterm><primary>recenterDefaultScale</primary></indexterm>: 
          fixed scale to use when recentering. Mandatory when centered-on object
          is a point.</para>
      </listitem>
        <listitem>
            <para> refMarksSymbol<indexterm>
                <primary>refMarksSymbol</primary></indexterm>: symbol used to draw
                lines for reference marks (typically an ellipse). </para>
        </listitem>
        <listitem>
            <para> refMarksSymbolSize<indexterm>
                <primary>refMarksSymbolSize</primary></indexterm>: size in pixel of
                symbol used to draw lines for reference marks (typically 1 or 2). </para>
        </listitem>
        <listitem>
            <para> refMarksSize<indexterm>
                <primary>refMarksSize</primary></indexterm>: size of reference
                marks. Size is fixed and won't change with scale. </para>
        </listitem>
        <listitem>
            <para> refMarksColor<indexterm>
                <primary>refMarksColor</primary></indexterm>: color of reference
                marks (comma-separated R, G and B values). </para>
        </listitem>
        <listitem>
            <para> refMarksTransparency<indexterm>
                <primary>refMarksTransparency</primary></indexterm>: transparency
                of reference marks. </para>
        </listitem>
        <listitem>
            <para> refMarksOrigin<indexterm>
                <primary>refMarksOrigin</primary></indexterm>: origin for
                reference marks (comma-separated X and Y values, typically "0, 0").
                </para>
        </listitem>
        <listitem>
            <para> refMarksInterval.#.maxScale<indexterm>
                <primary>refMarksInterval.#.maxScale</primary></indexterm>:
                maximum scale for corresponding interval. </para>
        </listitem>
        <listitem>
            <para> refMarksInterval.#.interval<indexterm>
                <primary>refMarksInterval.#.interval</primary></indexterm>: real interval
                between two reference marks (comma-separated X and Y values). </para>
        </listitem>
        <listitem>
            <para> refLinesActive<indexterm>
                <primary>refLinesActive</primary></indexterm>: if true, will display
                reference marks on page borders. </para>
        </listitem>
        <listitem>
            <para> refLinesSize<indexterm>
                <primary>refLinesSize</primary></indexterm>: size in pixel of
                reference marks on page borders. </para>
        </listitem>
      <listitem>
        <para> refLinesFontSize<indexterm>
          <primary>refLinesFontSize</primary></indexterm>: size of font for
          reference marks on page borders.</para>
      </listitem>
      <listitem>
        <para> scaleUnitLimit<indexterm>
          <primary>scaleUnitLimit</primary></indexterm>: scale above which the scalebar use km ; below, m is used.</para>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="user.location.mapfile">
    <title>Related Elements Elsewhere</title>
    <para> <indexterm><primary>extent</primary></indexterm>The maximal extent 
      of the geographical zone is set by the EXTENT command in the mapfile. 
      </para>
    <para> <indexterm><primary>bbox (initial)</primary></indexterm>The initial 
      bbox is set by the active initialMapState. It is to be configured in the 
      <filename>myMap.ini</filename> file, using the following syntax: </para>
    <para> mapInfo.initialMapStates.initialMapStateId.location.bbox = 
      "xmin,ymin,xmax,ymax" </para>
  </sect1>
</chapter>
