< Developer Manual

New Plugins >

1. Calling Plugins

This chapter describes the structure of SOAP calls to CartoWeb server methods in order to obtain cartographic data.

Warning

Due to some CartoWeb evolutions, please note that some parts of the current chapter may need some updates!

Global WSDL code can be found in file CARTOWEB_HOME/server/cartoserver.wsdl. WSDL code specific to plugins are located in PLUGIN_HOME/common/plugin_name.wsdl.inc. Interesting parts from these files are copied in the following sections.

Complete WSDL code dynamically generated for a map ID is accessible at the URL CARTOWEB_URL/cartoserver.wsdl.php?mapId=project_name.mapfile_name.

SOAP method getMapInfo is used to retrieve server configuration information, such as available layers, initial state, etc.. It shouldn't be called each time a map is requested. A mechanism based on a timestamp is available to be sure configuration is up-to-date (see Section 1.2, “Call to getMapInfo”).

SOAP method getMap is used each time a new map or related information are needed.

1.1. Standard Structures

1.1.1. Simple Types

These types are used in different other structures.

<complexType name="ArrayOfString">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="xsd:string[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of character strings

<complexType name="Dimension">
  <all>
    <element name="width" type="xsd:int"/>
    <element name="height" type="xsd:int"/>
  </all>
</complexType>

  • width - width in pixels
  • height - height in pixels

<complexType name="GeoDimension">
  <all>
    <element name="dimension" type="types:Dimension"/>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

1.1.2. Shapes

These types define a hierarchy of shapes. As heritage and polymorphism cannot be used, type Shape includes all attibutes of its children types.

<complexType name="Bbox">
  <all>
    <element name="minx" type="xsd:double"/>
    <element name="miny" type="xsd:double"/>
    <element name="maxx" type="xsd:double"/>
    <element name="maxy" type="xsd:double"/>
  </all>
</complexType>

  • minx - minimum x coordinate
  • miny - minimum y coordinate
  • maxx - maximum x coordinate
  • maxy - maximum y coordinate

<complexType name="Point">
  <all>
    <element name="x" type="xsd:double"/>
    <element name="y" type="xsd:double"/>
  </all>
</complexType>

  • x - x coordinate
  • y - y coordinate

<complexType name="ArrayOfPoint">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Point[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of points

<complexType name="Shape">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="x" type="xsd:double" minOccurs="0"/>
    <element name="y" type="xsd:double" minOccurs="0"/>
    <element name="minx" type="xsd:double" minOccurs="0"/>
    <element name="miny" type="xsd:double" minOccurs="0"/>
    <element name="maxx" type="xsd:double" minOccurs="0"/>
    <element name="maxy" type="xsd:double" minOccurs="0"/>
    <element name="points" type="types:ArrayOfPoint" minOccurs="0"/>
  </all>
</complexType>

  • className - shape class name: "Point", "Bbox", "Rectangle", "Line" or "Polygon"
  • x - x coordinate (Point)
  • y - y coordinate (Point)
  • minx - minimum x coordinate (Bbox or Rectangle)
  • miny - minimum y coordinate (Bbox or Rectangle)
  • maxx - maximum x coordinate (Bbox or Rectangle)
  • maxy - maximum y coordinate (Bbox or Rectangle)
  • points - list of points (Line or Polygon)

<complexType name="ArrayOfShape">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Shape[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of shapes

1.1.3. Tables

These types define a table structure, used in particular in Query plugin (see Section 1.3.6, “Query”).

<complexType name="TableRow">
  <all>
    <element name="rowId" type="xsd:string"/>
    <element name="cells" type="types:ArrayOfString"/>
  </all>
</complexType>

<complexType name="ArrayOfTableRow">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:TableRow[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of rows

<complexType name="Table">
  <all>
    <element name="tableId" type="xsd:string"/>
    <element name="tableTitle" type="xsd:string"/>
    <element name="numRows" type="xsd:integer"/>
    <element name="totalRows" type="xsd:integer"/>
    <element name="offset" type="xsd:integer"/>
    <element name="columnIds" type="types:ArrayOfString"/>
    <element name="columnTitles" type="types:ArrayOfString"/>
    <element name="noRowId" type="xsd:boolean"/>
    <element name="rows" type="types:ArrayOfTableRow"/>
  </all>
</complexType>

  • tableId - table ID
  • tableTitle - table title
  • numRows - number of rows in table
  • totalRows - total number of rows in context (for future use)
  • offset - current position in context rows (for future use)
  • columnIds - column IDs (see Section 1.1.1, “Simple Types” for a description of type ArrayOfString)
  • columnTitles - column titles (see Section 1.1.1, “Simple Types” for a description of type ArrayOfString)
  • noRowId - if true, table rows contain no row IDs
  • rows - list of rows

<complexType name="ArrayOfTable">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Table[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of tables

<complexType name="TableGroup">
  <all>
    <element name="groupId" type="xsd:string"/>
    <element name="groupTitle" type="xsd:string"/>
    <element name="tables" type="types:ArrayOfTable"/>
  </all>
</complexType>

  • groupId - ID of table group
  • groupTitle - title of table group
  • tables - list of tables

<complexType name="ArrayOfTableGroup">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:TableGroup[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of table groups

<complexType name="TableFlags">
  <all>
    <element name="returnAttributes" type="xsd:boolean"/>
    <element name="returnTable" type="xsd:boolean"/>
  </all>
</complexType>

  • returnAttributes - if true, will return attributes (row cells) in addition to row IDs
  • returnTable - if false, won't return any table information. This can be useful for instance when hilighting an object on which no information is needed

1.2. Call to getMapInfo

This method returns server configuration, which includes layers, initial states and other plugin-specific configuration. Variables returned by this method are set in server configuration files described in Part II, “User Manual”.

1.2.1. Global Server Configuration

This includes layers configuration and initial states.

<complexType name="LayerState">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="hidden" type="xsd:boolean"/>
    <element name="frozen" type="xsd:boolean"/>
    <element name="selected" type="xsd:boolean"/>
    <element name="unfolded" type="xsd:boolean"/>
  </all>
</complexType>

  • id - layer state ID
  • hidden - if true, layer isn't displayed in tree and attribute selected cannot be modified
  • frozen - if true, layer is displayed in tree but attribute selected cannot be modified
  • selected - if true, layer is displayed as selected in tree
  • unfolded - if true, layer tree is displayed unfolded (layer groups)

<complexType name="ArrayOfLayerState">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:LayerState[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of layer states

<complexType name="InitialLocation">
  <all>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

<complexType name="InitialMapState">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="location" type="types:InitialLocation"/>
    <element name="layers" type="types:ArrayOfLayerState"/>
  </all>
</complexType>

  • id - initial state ID
  • location - initial location
  • layers - list of layer states

<complexType name="ArrayOfInitialMapState">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:InitialMapState[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of initial states

<complexType name="MapInfo">
  <all>
    <element name="timestamp" type="xsd:integer"/>
    <element name="mapLabel" type="xsd:string"/>
    <element name="keymapGeoDimension" type="types:GeoDimension"/>
    <element name="initialMapStates"
             type="types:ArrayOfInitialMapState"/>
    ...elements specific to plugins...
  </all>
</complexType>

  • timestamp - timestamp of last update. This timestamp is transferred each time method getMap is called, so client knows when configuration was modified (see also Section 1.3.1.1, “Global Request”)
  • mapLabel - name of map as defined in mapfile
  • keymapGeoDimension - pixel and geographical dimension information for key map
  • initialMapStates - list of initial states

1.2.2. Layers

This includes configuration specific to Layers plugin, ie. list of all available layers and their properties.

<complexType name="ArrayOfLayerId">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="xsd:string[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of layer IDs

<complexType name="ChildrenSwitch">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="layers" type="types:ArrayOfLayerId" minOccurs="0"/>
  </all>
</complexType>

  • id - switch ID
  • layers - list of layers

<complexType name="ArrayOfChildrenSwitch">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType=ChildrenSwitch[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of children switches

<complexType name="Layer">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="id" type="xsd:string"/>
    <element name="label" type="xsd:string"/>
    <element name="children"
             type="types:ArrayOfChildrenSwitch" minOccurs="0"/>
    <element name="minScale" type="xsd:double"/>
    <element name="maxScale" type="xsd:double"/>
    <element name="icon" type="xsd:string"/>
    <element name="link" type="xsd:string"/>
    <element name="aggregate" type="xsd:boolean" minOccurs="0"/>
    <element name="rendering" type="xsd:string" minOccurs="0"/>
    <element name="metadata" type="types:ArrayOfString" minOccurs="0"/>
  </all>
</complexType>

  • className - layer class name: "LayerGroup", "Layer" or "LayerClass"
  • id - layer ID
  • label - label to be displayed. This label is not yet translated using internationalization
  • children - list of children
  • minScale - minimum scale at which layer will be displayed
  • maxScale - maximum scale at which layer will be displayed
  • icon - filename of the static icon for the layer. Dynamic legends are described in Section 6.4, “Layers Legends”
  • link - if set, layer name is clickable
  • msLayer - MapServer layer id
  • aggregate - if true, children are not displayed and cannot be selected individually
  • rendering - how layer will be displayed: "tree", "block", "radio" or "dropdown". See Chapter 6, Layers [coreplugin] for more details on this option
  • metadata - list of meta data defined in server configuration file. Format of each string in list is "variable_name=value"

<complexType name="ArrayOfLayer">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Layer[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of layers

<complexType name="SwitchInit">
  <all>
    <element name="id" type="xsd:string"/>
    <element name="label" type="xsd:string"/>
  </all>
</complexType>

  • id - switch ID
  • label - switch label

<complexType name="ArrayOfSwitchInit">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:SwitchInit[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of switches

<complexType name="LayersInit">
  <all>
    <element name="notAvailableIcon" type="xsd:string"/>
    <element name="notAvailablePlusIcon" type="xsd:string"/>
    <element name="notAvailableMinusIcon" type="xsd:string"/>
    <element name="layers" type="types:ArrayOfLayer"/>
    <element name="switches" type="types:ArrayOfSwitchInit" minOccurs="0"/>
  </all>
</complexType>

  • notAvailableIcon - filename of icon for not available layer (current scale is above or below this layer maximum/minimum scale)
  • notAvailablePlusIcon - filename of icon for not available layer (current scale is above this layer maximum scale)
  • notAvailableMinusIcon - filename of icon for not available layer (current scale is below this layer minimum scale)
  • layers - list of layers
  • switches - list of switches

1.2.3. Location

This includes configuration specific to Location plugin, ie. fixed scales, scales limits and shortcuts.

<complexType name="LocationScale">
  <all>
    <element name="label" type="xsd:string"/>
    <element name="value" type="xsd:double"/>
  </all>
</complexType>

  • label - scale caption
  • value - scale value to be set when scale is selected

<complexType name="ArrayOfLocationScale">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:LocationScale[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of scales

<complexType name="LocationShortcut">
  <all>
    <element name="label" type="xsd:string"/>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

  • label - shortcut caption
  • bbox - bounding box to recenter on when shortcut is selected

<complexType name="ArrayOfLocationShortcut">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:LocationShortcut[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of shortcuts

<complexType name="LocationInit">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="scales" type="types:ArrayOfLocationScale"/>
    <element name="minScale" type="xsd:double"/>
    <element name="maxScale" type="xsd:double"/>
    <element name="shortcuts" type="types:ArrayOfLocationShortcut"/>
  </all>
</complexType>

  • className - "LocationInit" or extended class name if project implements an extension
  • scales - list of fixed scales
  • minScale - global minimum scale
  • maxScale - global maximum scale
  • shortcuts - list of bounding box shortcuts

1.2.4. Layer Reorder

This includes configuration specific to LayerReorder plugin.

<complexType name="LayerReorderInit">
  <all>
    <element name="layers" type="types:ArrayOfLayerInit"/>
  </all>
</complexType>

  • array - layers are ordered from top to bottom of the displayed stack, see below to LayerInit structure overview.

<complexType name="LayerInit">
  <all>
    <element name="layerId" type="xsd:string"/>
    <element name="layerLabel" type="xsd:string"/>
  </all>
</complexType>

  • layerId - Layer Id
  • layerLabel - label to be displayed. This label is not yet translated using internationalization

1.3. Call to getMap

For each plugin, SOAP XML format are described for both server calls (i.e. requests) and server results.

1.3.1. Global Structures

Below is a description of general requests and results which include plugin-specific ones.

1.3.1.1. Global Request

<complexType name="MapRequest">
  <all>
    <element name="mapId" type="xsd:string"/>
    ...elements specific to plugins...
  </all>
</complexType>

  • mapId - map ID, ie. project name and mapfile name separated by a point

1.3.1.2. Global Result

<complexType name="Message">
  <all>
    <element name="channel" type="xsd:integer"/>
    <element name="message" type="xsd:string"/>
  </all>
</complexType>

  • channel - type of message: 1 = end user, 2 = developer
  • message - text of the message

<complexType name="ArrayOfMessage">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:Message[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of messages

<complexType name="MapResult">
  <all>
    <element name="timestamp" type="xsd:integer"/>
    <element name="serverMessages"
             type="types:ArrayOfMessage" minOccurs="0"/>
    ...elements specific to plugins...
  </all>
</complexType>

  • timestamp - timestamp which identifies the server configuration. If this timestamp changes, it means server configuration changed and a call to method getMapInfo is required to get latest version (see Section 1.2, “Call to getMapInfo”).
  • serverMessages - list of messages returned by server

1.3.2. Images

The Images plugin generates MapServer images. The three types of images are main map, key map and scale bar. Basic parameters, such as image size, are defined in this request/result. More specific parameters, such as map location or content, are defined in other plugins.

1.3.2.1. Images Request

<complexType name="Image">
  <all>
    <element name="isDrawn" type="xsd:boolean"/>
    <element name="path" type="xsd:string"/>
    <element name="width" type="xsd:int"/>
    <element name="height" type="xsd:int"/>
  </all>
</complexType>

  • isDrawn - true if the image should be generated (when used in a request) or if it was generated (when returned in a result)
  • path - relative path of generated image. Not used in request
  • width - image width
  • height - image height

<complexType name="ImagesRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="mainmap" type="types:Image"/>
    <element name="keymap" type="types:Image"/>
    <element name="scalebar" type="types:Image"/>
  </all>
</complexType>

  • className - "ImagesRequest" or extended class name if project implements an extension
  • mainmap - main map image information
  • keymap - key map image information
  • scalebar - scale bar image information

1.3.2.2. Images Result

<complexType name="ImagesResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="mainmap" type="types:Image"/>
    <element name="keymap" type="types:Image"/>
    <element name="scalebar" type="types:Image"/>
  </all>
</complexType>

  • className - "ImagesResult" or extended class name if project implements an extension
  • mainmap - main map image information (see Section 1.3.2.1, “Images Request” for a description of type Image)
  • keymap - key map image information
  • scalebar - scale bar image information

1.3.3. Layers

The Layers plugin handles layers selection. Its request object includes list of layers to be displayed on main map. This plugin has no specific result object.

1.3.3.1. Layers Request

<complexType name="LayersRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="layerIds" type="types:ArrayOfLayerId"/>
    <element name="resolution" type="xsd:int"/>
    <element name="switchId" type="xsd:string"/>
  </all>
</complexType>

  • className - "LayersRequest" or extended class name if project implements an extension
  • layerIds - list of layers to include in map generation (see Section 1.1.1, “Simple Types” for a description of type ArrayOfLayerId)
  • resolution - MapServer resolution. Set this to null if you want to use default resolution
  • switchId - current switch ID

1.3.3.2. Layers Result

<complexType name="LayersResult">
  <all>
    <element name="className" type="xsd:string"/>
  </all>
</complexType>

  • className - "LayersResult" or extended class name if project implements an extension

1.3.4. Layer Reorder

The LayerReorder plugin handles layers reorder selection. Its request object includes list of layerIds rightly ordered to be displayed on main map. This plugin has no specific result object.

1.3.4.1. Layer Reorder Request

<complexType name="LayersRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="layerIds" type="types:ArrayOfLayerId"/>
  </all>
</complexType>

  • className - "LayerReorderRequest" or extended class name if project implements an extension
  • layerIds - list of layers to include in map generation rightly ordered from top to bottom (see Section 1.1.1, “Simple Types” for a description of type ArrayOfLayerId).

1.3.5. Location

The Location plugin handles position and moves on the map. Its request process includes different position methods, such as recentering on a specific object or moves relative to previous position. It returns the new bounding box and scale.

1.3.5.1. Location Request

<simpleType name="LocationType">
  <restriction base="xsd:string">
    <enumeration value="bboxLocationRequest"/>
    <enumeration value="panLocationRequest"/>
    <enumeration value="zoomPointLocationRequest"/>
    <enumeration value="recenterLocationRequest"/>
  </restriction>
</simpleType>

  • bboxLocationRequest - recenters on a bounding box
  • panLocationRequest - moves horizontaly/verticaly (panning)
  • zoomPointLocationRequest - recenters on a point, includes relative zoom and fixed scale
  • recenterLocationRequest - recenters on mapfile IDs

<complexType name="LocationConstraint">
  <all>
    <element name="maxBbox" type="types:Bbox"/>
  </all>
</complexType>

  • maxBbox - maximum bounding box. If given parameters lead to a larger bounding box, it will be cropped (see Section 1.1.2, “Shapes” for a description of type Bbox)

<complexType name="LocationRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="locationType"  type="types:LocationType"/>
    <element name="bboxLocationRequest"
             type="types:BboxLocationRequest" minOccurs="0"/>
    <element name="panLocationRequest"
             type="types:PanLocationRequest" minOccurs="0"/>
    <element name="zoomPointLocationRequest"
             type="types:ZoomPointLocationRequest" minOccurs="0"/>
    <element name="recenterLocationRequest"
             type="types:RecenterLocationRequest" minOccurs="0"/>
    <element name="locationConstraint"
             type="types:LocationConstraint" minOccurs="0"/>
  </all>
</complexType>

1.3.5.1.1. BBox Request

<complexType name="BboxLocationRequest">
  <all>
    <element name="bbox" type="types:Bbox"/>
  </all>
</complexType>

1.3.5.1.2. Pan Request

<simpleType name="PanDirectionType">
  <restriction base="xsd:string">
    <enumeration value="VERTICAL_PAN_NORTH"/>
    <enumeration value="VERTICAL_PAN_NONE"/>
    <enumeration value="VERTICAL_PAN_SOUTH"/>
    <enumeration value="HORIZONTAL_PAN_WEST"/>
    <enumeration value="HORIZONTAL_PAN_NONE"/>
    <enumeration value="HORIZONTAL_PAN_EAST"/>
  </restriction>
</simpleType>

  • VERTICAL_PAN_NORTH - panning north
  • VERTICAL_PAN_NONE - no vertical panning
  • VERTICAL_PAN_SOUTH - panning south
  • HORIZONTAL_PAN_WEST - panning west
  • HORIZONTAL_PAN_NONE - no horizontal panning
  • HORIZONTAL_PAN_EAST - panning east

<complexType name="PanDirection">
  <all>
    <element name="verticalPan" type="types:PanDirectionType"/>
    <element name="horizontalPan" type="types:PanDirectionType"/>
  </all>
</complexType>

  • verticalPan - type of vertical panning
  • horizontalPan - type of horizontal panning

<complexType name="PanLocationRequest">
  <all>
    <element name="bbox" type="types:Bbox"/>
    <element name="panDirection" type="types:PanDirection"/>
  </all>
</complexType>

1.3.5.1.3. Zoom-Point Request

<simpleType name="ZoomType">
  <restriction base="xsd:string">
    <enumeration value="ZOOM_DIRECTION_IN"/>
    <enumeration value="ZOOM_DIRECTION_NONE"/>
    <enumeration value="ZOOM_DIRECTION_OUT"/>
    <enumeration value="ZOOM_FACTOR"/>
    <enumeration value="ZOOM_SCALE"/>
  </restriction>
</simpleType>

  • ZOOM_DIRECTION_IN - zoom in (default is x2)
  • ZOOM_DIRECTION_NONE - no zoom, recenter on point only
  • ZOOM_DIRECTION_OUT - zoom out (default is x0.5)
  • ZOOM_FACTOR - zoom using a custom factor
  • ZOOM_SCALE - zoom to a fixed scale

<complexType name="ZoomPointLocationRequest">
  <all>
    <element name="bbox" type="types:Bbox"/>
    <element name="point" type="types:Point"/>
    <element name="zoomType" type="types:ZoomType"/>
    <element name="zoomFactor" type="xsd:float" minOccurs="0"/>
    <element name="scale" type="xsd:integer" minOccurs="0"/>
  </all>
</complexType>

  • bbox - bounding box (unused when zoom type = ZOOM_SCALE)
  • point - point to recenter on
  • zoomType - type of zoom
  • zoomFactor - zoom factor (unused when zoom type != ZOOM_FACTOR)
  • scale - fixed scale (unused when zoom type != ZOOM_SCALE)

1.3.5.1.4. Recenter Request

<complexType name="IdSelection">
  <all>
    <element name="layerId" type="xsd:string"/>
    <element name="idAttribute" type="xsd:string"/>
    <element name="idType" type="xsd:string"/>
    <element name="selectedIds" type="types:ArrayOfString"/>
  </all>
</complexType>

  • layerId - ID of layer on which query will be executed
  • idAttribute - name of ID attribute
  • idType - type of ID attribute ("string" or "int")
  • selectedIds - list of IDs

<complexType name="ArrayOfIdSelection">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:IdSelection[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of ID selections

<complexType name="RecenterLocationRequest">
  <all>
    <element name="idSelections" type="types:ArrayOfIdSelection"/>
  </all>
</complexType>

  • idSelections - list of ID selections

1.3.5.2. Location Result

<complexType name="LocationResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="bbox" type="types:Bbox"/>
    <element name="scale" type="xsd:double"/>
  </all>
</complexType>

  • className - "LocationResult" or extended class name if project implements an extension
  • bbox - new bounding box (see Section 1.1.2, “Shapes” for a description of type Bbox)
  • scale - new scale

1.3.6. Query

The Query plugin allows to search objects, hilight them on map and return text results. Search can be executed from a rectangle selection and/or using a list of object IDs.

Query request object is not mandatory. For more information about Query plugin, see Chapter 9, Queries [coreplugin] (query).

1.3.6.1. Query Request

<simpleType name="QuerySelectionPolicy">
  <restriction base="xsd:string">
    <enumeration value="POLICY_XOR"/>
    <enumeration value="POLICY_UNION"/>
    <enumeration value="POLICY_INTERSECTION"/>
  </restriction>
</simpleType>

  • POLICY_XOR - XOR selection: when selecting a group of objects, already selected ones are unselected and not yet selected ones are selected (default type)
  • POLICY_UNION - union selection: when selecting a group of objects, already selected ones are kept selected and not yet selected ones are selected
  • POLICY_INTERSECTION - intersection selection: when selecting a group of objects, only already selected ones are kept selected

<complexType name="QuerySelection">
  <all>
    <element name="layerId" type="xsd:string"/>
    <element name="idAttribute" type="xsd:string"/>
    <element name="idType" type="xsd:string"/>
    <element name="selectedIds" type="types:ArrayOfString"/>
    <element name="useInQuery" type="xsd:boolean"/>
    <element name="policy" type="types:QuerySelectionPolicy"/>
    <element name="maskMode" type="xsd:boolean"/>
    <element name="hilight" type="xsd:boolean"/>
    <element name="tableFlags" type="types:TableFlags"/>
  </all>
</complexType>

  • layerId - layer ID on which query will be executed
  • idAttribute - name of ID attribute
  • idType - type of ID attribute ("string" or "int")
  • selectedIds - list of IDs
  • useInQuery - if true, will force query to use this layer
  • policy - type of selection
  • maskMode - if true, will apply a mask instead of a simple selection. This won't work when using MapServer's hilighting feature (see Chapter 9, Queries [coreplugin] (query))
  • hilight - if false, selection won't be hilighted on map
  • tableFlags - table flags (see Section 1.1.3, “Tables” for a description of type TableFlags)

<complexType name="ArrayOfQuerySelection">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType"
                 wsdl:arrayType="types:QuerySelection[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of query selections

<complexType name="QueryRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="shape" type="types:Shape"/>
    <element name="queryAllLayers" type="xsd:boolean"/>
    <element name="defaultMaskMode" type="xsd:boolean"/>
    <element name="defaultHilight" type="xsd:boolean"/>
    <element name="defaultTableFlags" type="types:TableFlags"/>
    <element name="querySelections" type="types:ArrayOfQuerySelection"/>
  </all>
</complexType>

  • className - "QueryRequest" or extended class name if project implements an extension
  • shape - type of query object dependant. It can be a bounding box, a polygon, a circle or a point (see Section 1.1.2, “Shapes” for a description of differents types)
  • queryAllLayers - if true, will execute query on all selected layers, ie. layers sent through Layers request (see Section 1.3.3.1, “Layers Request”). Unused when bounding box is not specified
  • defaultMaskMode - mask mode for new layers (returned by query and but not yet in array querySelections). Unused when queryAllLayers = false
  • defaultHilight - highlight for new layers (returned by query and but not yet in array querySelections). Unused when queryAllLayers = false
  • defaultTableFlags - table flags for new layers (returned by query and but not yet in array querySelections, see Section 1.1.3, “Tables” for a description of type TableFlags). Unused when queryAllLayers = false
  • querySelections - list if query selections. It contains all objects that must be hilighted and can be used to maintain persistence of a selection

1.3.6.2. Query Result

<complexType name="QueryResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="tableGroup" type="types:TableGroup"/>
  </all>
</complexType>

  • className - "QueryResult" or extended class name if project implements an extension
  • tableGroup - group of tables which contains query results (one table per layer)

1.3.7. Outline

The Outline plugin allows to draw shapes on the main map. Shapes can also be drawn as a mask, ie. as holes in a rectangle covering map. It returns total area covered by shapes.

Outline request is not mandatory. As Outline plugin is not a core plugin, it must be activated in order to use the following request/result objects.

1.3.7.1. Outline Request

<complexType name="Color">
  <all>
    <element name="r" type="xsd:int"/>
    <element name="g" type="xsd:int"/>
    <element name="b" type="xsd:int"/>
  </all>
</complexType>

  • r - red
  • g - green
  • b - blue

<complexType name="ShapeStyle">
  <all>
    <element name="symbol" type="xsd:int"/>
    <element name="size" type="xsd:int"/>
    <element name="color" type="types:Color"/>
    <element name="outlineColor" type="types:Color"/>
    <element name="backgroundColor" type="types:Color"/>
    <element name="transparency" type="xsd:int"/>
  </all>
</complexType>

  • symbol -index of Mapserver symbol
  • size - size of shape
  • color - color
  • outlineColor - outline color
  • backgroundColor - background color
  • transparency - transparency

<complexType name="LabelStyle">
  <all>
    <element name="font" type="xsd:int"/>
    <element name="size" type="xsd:int"/>
    <element name="color" type="types:Color"/>
    <element name="outlineColor" type="types:Color"/>
    <element name="backgroundColor" type="types:Color"/>
  </all>
</complexType>

  • font - index of Mapserver font
  • size - size of font
  • color - color
  • outlineColor - outline color
  • backgroundColor - background color

<complexType name="StyledShape">
  <all>
    <element name="shapeStyle" type="types:ShapeStyle"/>
    <element name="labelStyle" type="types:LabelStyle"/>
    <element name="shape" type="types:Shape"/>
    <element name="label" type="xsd:string"/>
  </all>
</complexType>

  • shapeStyle - style of shape
  • labelStyle - style of label
  • shape - shape (can be a point, rectangle, line or polygon, see Section 1.1.2, “Shapes” for a description of type Shape)
  • label - content of label

<complexType name="ArrayOfStyledShape">
  <complexContent>
    <restriction base="enc11:Array">
      <attribute ref="enc11:arrayType" wsdl:arrayType="types:StyledShape[]"/>
    </restriction>
  </complexContent>
</complexType>

  • array - list of shapes with style

<complexType name="OutlineRequest">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="shapes" type="types:ArrayOfStyledShape"/>
    <element name="maskMode" type="xsd:boolean"/>
  </all>
</complexType>

  • className - "OutlineRequest" or extended class name if project implements an extension
  • shapes - list of styled shapes
  • maskMode - if true, will draw the complement of all shapes merged together

1.3.7.2. Outline Result

<complexType name="OutlineResult">
  <all>
    <element name="className" type="xsd:string"/>
    <element name="area" type="xsd:double"/>
  </all>
</complexType>

  • className - "OutlineResult" or extended class name if project implements an extension
  • area - total area for all shapes

1.4. Examples

The following examples show simple SOAP calls using PHP.

To use these examples with your CartoWeb server, you'll have to modify the map ID and the layer names. Please note that in these examples, access to resources uses symbolic links (see Chapter 4, Configuration Files).

1.4.1. Retrieving Server Configuration

First thing to do is to declare the SOAP client. Class SoapClient will need the WSDL code dynamically generated by script cartoserver.wsdl.php.

<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...

Method only needs map ID as argument.

try{
    $result = $client->getMapInfo("swiss_project.swiss");
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>

Result is shown below. It includes server configuration for the corresponding project and mapfile.

stdClass Object
(
  [timeStamp] => 1107043488
  [mapLabel] => Switzerland
  [keymapGeoDimension] => stdClass Object
    (
      [dimension] => stdClass Object
        (
          [width] => 100
          [height] => 100
        )
      [bbox] => stdClass Object
        (
          [minx] => 485000
          [miny] => 65000
          [maxx] => 835000
          [maxy] => 298000
        )
    )
  [initialMapStates] => Array
    (
      [0] => stdClass Object
        (
          [id] => default
          [location] => stdClass Object
            (
              [bbox] => stdClass Object
                (
                  [minx] => 470000
                  [miny] => 50000
                  [maxx] => 860000
                  [maxy] => 320000
                )
            )
          [layers] => Array
            (
              [0] => stdClass Object
                (
                  [id] => swiss_layer_1
                  [hidden] => 
                  [frozen] => 
                  [selected] => 1
                  [unfolded] => 
                )
              [1] => stdClass Object
                (
                  [id] => swiss_layer_2
                  [hidden] => 1
                  [frozen] => 
                  [selected] => 1
                  [unfolded] => 
                )
            )
        )
    )
  [layersInit] => stdClass Object
  (
  [notAvailableIcon] => gfx/icons/swiss_project/swiss/na.png
  [notAvailablePlusIcon] => gfx/icons/swiss_project/swiss/nap.png
  [notAvailableMinusIcon] => gfx/icons/swiss_project/swiss/nam.png
  [layers] => Array
    (
      [0] => stdClass Object
        (
          [className] => LayerGroup
          [id] => root
          [label] => root
          [children] => Array
            (
              [0] => swiss_layer_1
              [1] => swiss_layer_2
            )
          [minScale] => 0
          [maxScale] => 0
          [icon] => 
          [link] => 
          [aggregate] => 
          [rendering] => 
          [metadata] => Array
            (
              [0] => foo=bar
            )
        )
      [1] => stdClass Object
        (
          [className] => Layer
          [id] => swiss_layer_1
          [label] => Swiss Layer 1
          [children] => Array
            (
            )
          [minScale] => 0
          [maxScale] => 0
          [icon] => gfx/icons/swiss_project/swiss/icon_1.png
          [link] => 
          [metadata] => Array
            (
            )
        )
      [2] => stdClass Object
        (
          [className] => Layer
          [id] => swiss_layer_2
          [label] => Swiss Layer 2
          [children] => Array
            (
            )
          [minScale] => 1
          [maxScale] => 20
          [icon] => 
          [link] => 
          [metadata] => Array
            (
            )
        )
    )
  [locationInit] => stdClass Object
    (
      [className] => LocationInit
      [scales] => Array
        (
          [0] => stdClass Object
            (
              [label] => 1/50000
              [value] => 50000
            )
          [1] => stdClass Object
            (
              [label] => 1/100000
              [value] => 100000
            )
          [2] => stdClass Object
            (
              [label] => 1/500000
              [value] => 500000
            )
        )
      [minScale] => 25000
      [maxScale] => 1000000
      [shortcuts] => Array
        (
          [0] => stdClass Object
            (
              [label] => Romandie
              [bbox] => stdClass Object
                (
                  [minx] => 475000
                  [miny] => 65750
                  [maxx] => 670000
                  [maxy] => 212000
                )
            )
        )
    )
)

1.4.2. Getting a Map Using a Point and a Scale

The simpliest way to obtain a map from CartoWeb server is to send an X-Y location and a scale.

First thing to do is to declare the SOAP client. Class SoapClient will need the WSDL code dynamically generated by script cartoserver.wsdl.php.

<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...

The map ID is required also in the request object.

$request->mapId = 'swiss_project.swiss';
...

In this example, only main map and scale bar are requested. So key map's isDrawn attribute is set to false.

$request->imagesRequest->className = 'ImagesRequest';

$request->imagesRequest->mainmap->isDrawn = true;
$request->imagesRequest->mainmap->path = '';
$request->imagesRequest->mainmap->width = 500;
$request->imagesRequest->mainmap->height = 500;
$request->imagesRequest->mainmap->format = '';

$request->imagesRequest->keymap->isDrawn = false;
$request->imagesRequest->keymap->path = '';
$request->imagesRequest->keymap->width = 0;
$request->imagesRequest->keymap->height = 0;
$request->imagesRequest->keymap->format = '';

$request->imagesRequest->scalebar->isDrawn = true;
$request->imagesRequest->scalebar->path = '';
$request->imagesRequest->scalebar->width = 100;
$request->imagesRequest->scalebar->height = 100;
$request->imagesRequest->scalebar->format = '';
...

Two layers are displayed. Resolution attribute is set to null to keep standard Mapserver resolution.

$request->layersRequest->className = 'LayersRequest';

$request->layersRequest->layerIds = array('swiss_layer_1',
                                          'swiss_layer_2');
$request->layersRequest->resolution = null;
...

In this case, the location request object is of type zoom-point, and zoom type is set to ZOOM_SCALE. Bbox is unused but is required.

$request->locationRequest->className = 'LocationRequest';

$request->locationRequest->locationType = 'zoomPointLocationRequest';
$request->locationRequest
        ->zoomPointLocationRequest->bbox->minx = 500000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->miny = 100000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->maxx = 600000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->maxy = 200000;
$request->locationRequest
        ->zoomPointLocationRequest->point->x = 550000;
$request->locationRequest
        ->zoomPointLocationRequest->point->y = 150000;
$request->locationRequest
        ->zoomPointLocationRequest->zoomType = 'ZOOM_SCALE';
$request->locationRequest
        ->zoomPointLocationRequest->scale = 200000;
...

Now request object is ready, SOAP method is called.

try{
    $result = $client->getMap($request);
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>

Result is shown below. It includes relative paths to generated images and new bounding box computed from requested scale.

stdClass Object
(
  [timestamp] => 1107925732
  [serverMessages] => Array
    (
    )
  [imagesResult] => stdClass Object
    (
      [className] => ImagesResult
      [mainmap] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110839565198671.jpg
          [width] => 500
          [height] => 500
          [format] => 
        )
      [keymap] => stdClass Object
        (
          [isDrawn] => 
          [path] => 
          [width] => 
          [height] => 
          [format] => 
        )
      [scalebar] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110839565198672.png
          [width] => 300
          [height] => 31
          [format] => 
        )
    )
  [locationResult] => stdClass Object
    (
      [className] => LocationResult
      [bbox] => stdClass Object
        (
          [minx] => 536770.840477
          [miny] => 136770.840477
          [maxx] => 563229.159523
          [maxy] => 163229.159523
        )
      [scale] => 200000
    )
)

1.4.3. Executing a Query

The following code shows how to use queries to display hilighted selection and to retrieve corresponding attributes.

First thing to do is to declare the SOAP client. Class SoapClient will need the WSDL code dynamically generated by script cartoserver.wsdl.php.

<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...

The map ID is required also in the request object.

$request->mapId = 'swiss_project.swiss';
...

In this example, only main map and key map are requested. So scale bar's isDrawn attribute is set to false.

$request->imagesRequest->className = 'ImagesRequest';

$request->imagesRequest->mainmap->isDrawn = true;
$request->imagesRequest->mainmap->path = '';
$request->imagesRequest->mainmap->width = 500;
$request->imagesRequest->mainmap->height = 500;
$request->imagesRequest->mainmap->format = '';

$request->imagesRequest->keymap->isDrawn = true;
$request->imagesRequest->keymap->path = '';
$request->imagesRequest->keymap->width = 100;
$request->imagesRequest->keymap->height = 100;
$request->imagesRequest->keymap->format = '';

$request->imagesRequest->scalebar->isDrawn = false;
$request->imagesRequest->scalebar->path = '';
$request->imagesRequest->scalebar->width = 0;
$request->imagesRequest->scalebar->height = 0;
$request->imagesRequest->scalebar->format = '';
...

Two layers are displayed. Resolution attribute is set to null to keep standard Mapserver resolution.

$request->layersRequest->className = 'LayersRequest';

$request->layersRequest->layerIds = array('swiss_layer_1',
                                          'swiss_layer_2');
$request->layersRequest->resolution = null;
...

In this case, the location request object is of type bbox. Only new bounding box is required.

$request->locationRequest->className = 'LocationRequest';

$request->locationRequest->locationType = 'bboxLocationRequest';
$request->locationRequest->bboxLocationRequest->bbox->minx = 550000;
$request->locationRequest->bboxLocationRequest->bbox->miny = 100000;
$request->locationRequest->bboxLocationRequest->bbox->maxx = 600000;
$request->locationRequest->bboxLocationRequest->bbox->maxy = 150000;
...

The query will be performed on a rectangle, on all selected layers (ie. layers defined in layers request object). IDs and attributes will be returned.

$request->queryRequest->className = 'QueryRequest';

$request->queryRequest->shape->className = 'Bbox';
$request->queryRequest->shape->minx = 570000;
$request->queryRequest->shape->miny = 120000;
$request->queryRequest->shape->maxx = 580000;
$request->queryRequest->shape->maxy = 130000;
$request->queryRequest->queryAllLayers = true;
$request->queryRequest->defaultMaskMode = false;
$request->queryRequest->defaultTableFlags->returnAttributes = true;
$request->queryRequest->defaultTableFlags->returnTable = true;
$request->queryRequest->querySelections = array();
...

Now request object is ready, SOAP method is called.

try{
    $result = $client->getMap($request);
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>

Result is shown below. It includes relative paths to generated images and new scale computed from requested bounding box.

Query results include one table per layer. No results were found in layer swiss_layer_1 and two results in swiss_layer_2. As requested, attributes (here attribute_3 and attribute_4) are returned for each row.

stdClass Object
(
  [timestamp] => 1107925732
  [serverMessages] => Array
    (
    )
  [imagesResult] => stdClass Object
    (
      [className] => ImagesResult
      [mainmap] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110846607738541.jpg
          [width] => 500
          [height] => 500
          [format] => 
        )
      [keymap] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110846607738542.png
          [width] => 150
          [height] => 99
          [format] => 
        )
      [scalebar] => stdClass Object
        (
          [isDrawn] => 
          [path] => 
          [width] => 
          [height] => 
          [format] => 
        )
    )
  [locationResult] => stdClass Object
    (
      [className] => LocationResult
      [bbox] => stdClass Object
        (
          [minx] => 550000
          [miny] => 100000
          [maxx] => 600000
          [maxy] => 150000
        )
      [scale] => 377952.96
    )
  [queryResult] => stdClass Object
    (
      [className] => QueryResult
      [tableGroup] => stdClass Object
        (
          [groupId] => query
          [groupTitle] => Query
          [tables] => Array
            (
              [0] => stdClass Object
                (
                  [tableId] => swiss_layer_1
                  [tableTitle] => swiss_layer_1
                  [numRows] => 0
                  [totalRows] => 0
                  [offset] => 0
                  [columnIds] => Array
                    (
                    )
                  [columnTitles] => Array
                    (
                    )
                  [noRowId] => 
                  [rows] => Array
                    (
                    )
                )
              [1] => stdClass Object
                (
                  [tableId] => swiss_layer_2
                  [tableTitle] => swiss_layer_2
                  [numRows] => 2
                  [totalRows] => 0
                  [offset] => 0
                  [columnIds] => Array
                    (
                      [0] => attribute_3
                      [1] => attribute_4
                    )
                  [columnTitles] => Array
                    (
                      [0] => attribute_3
                      [1] => attribute_4
                    )
                  [noRowId] => 
                  [rows] => Array
                    (
                      [0] => stdClass Object
                        (
                          [rowId] => 123
                          [cells] => Array
                            (
                              [0] => Foo
                              [1] => 84.98
                            )
                        )
                      [1] => stdClass Object
                        (
                          [rowId] => 456
                          [cells] => Array
                            (
                              [0] => Bar
                              [1] => 32.47
                            )
                        )
                    )
                )
            )
        )
    )
)

valid xhtml 1.0 valid css