Your Federal Quarterly Tax Payments are due April 15th Get Help Now >>

CERCALIA API Javascript Manual by ryg11839

VIEWS: 98 PAGES: 47

									Joaquim Botet i Sisó, 6 · 17003 · Girona
Avinguda Meridiana, 216, 1ª · 08027 · Barcelona
Tel. 902 10 22 55 · www.nexusgeografics.com




      CERCALIA API Javascript Manual




      Enterprise: Nexus Geografics SL
      Last modified: 24/08/2009
      Document: manual_API_CERCALIAv2.9.1 English.doc
      1 Contents

1   Contents .......................................................................................................................................... 2
2   Architecture...................................................................................................................................... 4
  2.1     Installation................................................................................................................................ 5
    2.1.1      With domain validation .................................................................................................... 5
    2.1.2      With proxy validation ....................................................................................................... 5
3   Interface integration and personalization ........................................................................................ 5
  3.1     Basic example and integration ................................................................................................ 5
  3.2     Style and image personalization.............................................................................................. 6
  3.3     The configuration file ............................................................................................................... 7
4   The cercaliaClient class................................................................................................................. 10
  4.1     Structures or objects used by this tutorial’s classes.............................................................. 10
    4.1.1      Attributes of an error (Error) .......................................................................................... 10
    4.1.2      Attributes of a candidate (candidate)............................................................................. 10
    4.1.3      Attributes of a geoentity (Geoentity) .............................................................................. 10
    4.1.4      Attributes of a point of interest (Poi) .............................................................................. 11
    4.1.5      Attributes of proximity (Prox) ......................................................................................... 12
    4.1.6      Attributes of arc (Arc)..................................................................................................... 12
    4.1.7      Attributes of a mobile object (Mo).................................................................................. 12
    4.1.8      Attributes of a marker style object (markerStyle) .......................................................... 12
    4.1.9.     Attributes of a feature .................................................................................................... 13
  4.2     Methods for the treatment of markers ................................................................................... 13
    4.2.1      createMarker (id, x, y, srs, style, id2)............................................................................. 13
    4.2.2      createMarkers (obj, style) .............................................................................................. 14
    4.2.3      moveMarker (id, x, y, srs, cont) ..................................................................................... 16
    4.2.4      setMarkerIcon(id,url)...................................................................................................... 16
    4.2.5      deleteMarkers ([id l [, id2[…]]]) ...................................................................................... 17
    4.2.6      centerToMarkers (changeScale [,id 1 [, id2 […]]])......................................................... 17
    4.2.7      showMarkers (state [,id1 [, id2 […]]])............................................................................. 17
  4.3     Methods for handling features ............................................................................................... 18
    4.3.1      createFeature (wkt, srs, style) ....................................................................................... 18
    4.3.2      createFeature(gml,style [, editstyle]) ............................................................................. 20
    4.3.3      centerToFeatures (changeScale [, feature1 [, feature2 […]]])....................................... 20
    4.3.4      deleteFeatures([feature1 [, feature2 [...]]])..................................................................... 20
    4.3.5      getFeaturesByState(created, modified, deleted, unchanged[,SRS]) ............................ 21
    4.3.6      getFeaturesByStateAsGML(created, modified, deleted, unchanged[,SRS]) ................ 22
    4.3.7      getFeatures([feature1 [, feature2 [...]]][,SRS]) ............................................................... 22
    4.3.8      getFeaturesAsGML([feature1 [, feature2 [...]]][,SRS]) ................................................... 22
  4.4     Methods for map treatment ................................................................................................... 22
    4.4.1      activateTool(tool) ........................................................................................................... 22
    4.4.2      isCompleted() ................................................................................................................ 22
    4.4.3      showPois(visible,category[[,category]…]) ..................................................................... 22
    4.4.4      setLanguage(lang)......................................................................................................... 23
    4.4.5      getMap() ........................................................................................................................ 23
    4.4.6      deleteRoute (resultCalculateRoute) .............................................................................. 23
    4.4.7      setParse< operation> (function) .................................................................................... 23
    4.4.8      showResult< operation> (obj)........................................................................................ 25
    4.4.9      getExtent(srs) ................................................................................................................ 25
    4.4.10     getCenter(srs)................................................................................................................ 26
    4.4.11     setCenter(center,scale) ................................................................................................. 26
    4.4.12     setCenter(center,srs,scale) ........................................................................................... 26
    4.4.13     zoomToExtent(extent,srs) ............................................................................................. 27
    4.4.14     getScale(closest) ........................................................................................................... 27
    4.4.15     getCurrentSRS () ........................................................................................................... 27
  4.5     Methods for obtaining information ......................................................................................... 27
    4.5.1      geocoding(search,returnFunc) ...................................................................................... 27

Joaquim Botet i Sisó, 6                       Avinguda Meridiana, 216, 1ª                    tel 902 102255                                        2/47
17003 Girona                                  08027 Barcelona                                www.nexusgeografics.com
    4.5.2      proximity(search,returnFunc)......................................................................................... 29
    4.5.3      getPoi (infoxml, poicode [, poicode [,…]], execute) ....................................................... 31
    4.5.4      calculateRoute(stopList, routeParams, lineStyle, drawStopMarkers, execute) ............ 32
    4.5.5      createReport(xml,idElement,xsl_name) ........................................................................ 34
    4.5.6      createMapImage(routeId,lineStyle,routeParams,execute, poicats) .............................. 35
    4.5.7      calculateMultiRoute(stopList, routeParams, execute) ................................................... 36
    4.5.8      transformCoordinates (objlist,srs).................................................................................. 37
    4.5.9      coordToPixel(obj)........................................................................................................... 37
    4.5.10     coordToPixel(obj,srs)..................................................................................................... 38
5   Map style ....................................................................................................................................... 38
  5.1    getStyle() ............................................................................................................................... 38
  5.2    createWMSStyle (name, url, params, options)...................................................................... 38
6   Annex: Geocodification without a map .......................................................................................... 41
  There is the possibility to realize geocodifications without having to initialize the map. ................... 41
7   Annex: Coordinates systems......................................................................................................... 42
8   Annex: customclick buttons 1/2..................................................................................................... 43
    8.1.1      getCoordFromPixel(pixel,srs) ........................................................................................ 43
9   Annex: Editing tools....................................................................................................................... 44
10    Annex: difference between version 1 and 2 .............................................................................. 46




Joaquim Botet i Sisó, 6                       Avinguda Meridiana, 216, 1ª                   tel 902 102255                                        3/47
17003 Girona                                  08027 Barcelona                               www.nexusgeografics.com
    2 Architecture


  Users
usuarios                  Servidores Cliente
                            Client’s net                                CERCALIA net servers
                                                                         Servidores CERCALIA
                            - Opcional -
                              servers

                                                                                               Servidor
                                                                                                 CERCALIA
                                 -          File
                               - Fichero config.                                               CERCALIA:
                                                                    API           Middleware     net servers:
                                 configur.
                               API Cercalia                      Javascript          Java                Mapas
                                                                                               - -Caché Cache
                                 API
                               -CSS cercalia                                                      Oracle
                                                                                               - maps
                               - WEB (HTML)
                                 - CSS                                                         - Rutas
                                                                                                   O     l




Cercalia’s net servers provide a Javascript API which allows the fast and simple
incorporation of maps and other functionalities in your web sites.

In order to control API access and the services provided by the Cercalia net servers,
security mechanisms have been installed according to our clients’ or distributors’
needs.


    •    Domain validation

         Each distributor has one or more access points. Whenever one of these points
         is accessed, it is checked to make sure that it has been made through one of
         our distributor’s domains or net servers. To be precise, the referrer is checked
         to make sure that it belongs to one of our distributor’s domains or net servers.

         This solution needs less requirements in the client’s web server. Scritag
         technology (dynamic scripting) is used to avoid the validation of skip domain
         browsers. This technology has some limitations:

         - The longest petition don’t send correctly because IE is not able to send more
         than 256 bytes of information.
         - synchronization between calls is more rudimentary and in the IE6 does not
         work sometimes.


    •    Proxy Validation

         In this case the distributor must install a proxy servlet which requires the
         distributor to have a servlet net server. The proxy servlet receives the clients’
         petitions, adds the distributor’s identifier and resends both to the Cercalia net
         servers. It is important to protect the proxy in order to impede access from non
         valid locations.
Joaquim Botet i Sisó, 6            Avinguda Meridiana, 216, 1ª       tel 902 102255                       4/47
17003 Girona                       08027 Barcelona                   www.nexusgeografics.com
         This solution is more reliable because costumers can access to the proxy with
         AJAX petition and they don’t have limitations on the size of information. The
         proxy swings petitions according to the speed of the servers response and it
         tolerates the drop of these (in case of this).




     2.1 Installation

           2.1.1 With domain validation

    •    Unzip the Cercalia.zip file provided to a folder.
    •    Eliminate the sub folder WEB-INF
    •    Edit “cercalia.js” file and uncomment the section: connection by domain.
         Modify the variable value of context by the provided by Nexus.
    •    Publish the file in a web Server.
    •    Inform Nexus of the list of domains which the web server serves.
    •    Try the demo provided.


           2.1.2 With proxy validation

    •    Unzip the Cercalian.zip file provided to a folder.
    •    Add your distributor’s password (10 digits) to the configuration file WEB-
         INF/web.xml.
    •    Edit “cercalia.js” file and uncomment section: connection with proxy.
    •    Publish the folder in the applications Server.
    •    Try out the demo provided.




3 Interface integration and personalization

     3.1 Basic example and integration
The following code is a Basic example of how to use the API:

        <html>
        <head>
         <meta http-equiv=Content-Type content="text/html; charset=ISO-8859-1">
         <script type='text/javascript' src='cercalia.js'></script>
         <script>

        function execute(){
                f51 = cercalia.createFeature(“POINT (-448003 4817761)”,
        “EPSG:54004”,{strokeWidth: 3, strokeColor: “#00ee00”,
        fillColor: “#00ee00”, fillOpacity: 0.2});
                }

Joaquim Botet i Sisó, 6     Avinguda Meridiana, 216, 1ª   tel 902 102255              5/47
17003 Girona                08027 Barcelona               www.nexusgeografics.com
         var properties;
         var cercalia;

         function createAll(){
                properties=new cercaliaProperties(“config.xml”);
                cercalia = new cercaliaClient(properties,execute,”map”);
         }

        </script>
       </head>
       <body style="overflow: hidden;" onload="createAll();">
               <div id="map" class="mapa"></div>
       </body></html>


Before using the API it has to be loaded using the following instruction:

         <script type='text/javascript' src='cercalia.js'></script>

The CercaliaClient builder needs a div to place the map in. Now we’re going to
create a div in the page’s tag body:

         <div id="map" class="map">
         </div>



When the cercaliaClient builder is called the div must already be defined within the
page’s structure. In order to ensure correct use we must do it in the onload event
which is called after loading and composing the page.

         <body style="overflow: hidden;" onload="createCercalia();">


Initialization consists of basically reading a properties file and calling the
cercaliaClient builder using the parameter of the div name where the map must be
placed, an object with the properties and a function which will be run when the map is
initialised.

var cercalia;
     function createCercalia() {
        var properties=new cercaliaProperties("config.xml");
        cercalia = new cercaliaclient(properties,execute,”map”);
     }


Once the map is initialised the run function is called where we can call whatever API
functions we want:
function execute() {
       f51 = cercalia.createFeature("POINT (-448003 4817761)",
              "EPSG:54004",{strokeWidth: 3, strokeColor: "#00ee00", fillColor:
              "#00ee00",fillOpacity: 0.2});
}




     3.2 Style and image personalization
After loading the API we can overload the styles by means of the following
instruction:

Joaquim Botet i Sisó, 6     Avinguda Meridiana, 216, 1ª   tel 902 102255            6/47
17003 Girona                08027 Barcelona               www.nexusgeografics.com
<link rel="stylesheet" type="text/css" href="../theme/otro/estil.css" />



In this style file we can change names and/or the interface image paths:
    • Tab background images in on and off mode.
    • Title, content and generic marker background images.
    • Closing images, maximise and minimise the marker contents by defect, the
        API’s and simple API applications which only have a close button.
    • Menu options images.

Example: Changing the marker title background image.

We modify the html file in order to load the local styles sheet:


       <html>
       <head>
        <meta http-equiv=Content-Type content="text/html; charset=ISO-8859-
       1">
        <script type='text/javascript' src='cercalia.js'></script>
              <link rel="stylesheet" type="text/css"
       href="../theme/otro/estil.css" />
        <script>


We look for the following lines on the local styles sheet:

       .titolPopup
       {
         color: #444444;
         background-image: url('img/bg_div_info.gif');
       }


and we replace them with:

       .titolPopup
       {
         color: #444444;
         background-image: url('img/mifondo.gif ');
       }


We copy the new image in the images file.



     3.3 The configuration file

The map’s configuration properties can be loaded from a file in XML format with the
value labels to be personalised. An example of the file:

       <?xml version="1.0" encoding="ISO-8859-1"?>
        <config>
        <language>es</language>
        <panel_status>maximized</panel_status>
        <panel_pages>
               <search selected="true">true</search>
               <proximity>true</proximity>
               <route>true</route>
               <pois>true</pois>

Joaquim Botet i Sisó, 6    Avinguda Meridiana, 216, 1ª   tel 902 102255            7/47
17003 Girona               08027 Barcelona               www.nexusgeografics.com
         </panel_pages>

         <overview_map_status>minimized</overview_map_status>
         <overview_map_style>default</overview_map_style>

         <map_style>default</map_style>
         <show_mouse_position>false</show_mouse_position>

         <zoombar_status>hidden</zoombar_status>
         <pancontrol_status>visible</pancontrol_status>

         <map_center>410977,4896277</map_center>

         <xsl_name>rutas_ruta.xsl</xsl_name>


       <toolbar_status>maximized</toolbar_status>
       <toolbar_tools>
              <pan selected="true">true</pan>
              <zoomin>true</zoomin>
              <zoomout>true</zoomout>
              <draw>true</draw>
              <clean>true</clean>
              <measure>false</measure>
              <infopoi>true</infopoi>
              <infoter>true</infoter>
              <pois>true</pois>
              <export>false</export>
       </toolbar_tools>
</config>



In the following table the labels which can be found in the configuration file and their
meanings are listed:

      client                       Client’s code which is linked to the main distributor’s
                                   key: Do not put your distributor’s key in this
                                   parameter
      map_zoom_level               Map’s initial scale.
      map_center                   Map centre coordinates.
      map_style                    Map style. Use “default” unless another value is
                                   indicated.
      map_extent                   Maximum extent to which the map is visualised.
                                   Format: left, bottom, right, top
      language                     Language code (name of the xml file which contains
                                   messages).
      panel_status                 Side panel status. Possible values:
                                       Hidden
                                       Minimized
                                       Maximized
      panel_pages                  List of side panel pages and whether they are visible
                                   or not. One of the page may be “selected” to “true”
                                   to indicate that this page will be initially selected.
                                   Possible pages:
                                       Geocoding: candidate search page.
                                        Proximity: proximity resolution page.
                                        Route: route calculation page.
                                        Pois: points of interest viewing control page.

Joaquim Botet i Sisó, 6     Avinguda Meridiana, 216, 1ª   tel 902 102255             8/47
17003 Girona                08027 Barcelona               www.nexusgeografics.com
      zoombar_status             Possible values:
                                   Hidden
                                   Minimized
                                   Maximized
      pancontrol-status          Move control
                                     hidden
                                     visible

      overview_map_status        Possible values:
                                      Hidden
                                      Minimized
                                      Maximized
      overview_map_style         Use “default” unless another value is indicated.
      toolbar_status                  Hidden
                                      Minimized
                                      Maximized
      toolbar_tools              Order, buttons which appear on the toolbar and the
                                 initially selected button.

                                      •  Pan: tool for moving around the map.
                                      •  Zoomin: Tool for zooming in on any particular
                                         region.
                                      • Zoomout: Tool for observing a map from a
                                         greater distance.
                                      • Draw: Tool for drawing on a map. (not
                                         implemented)
                                      • Clean: Eliminates the results of previous
                                         searches.
                                      • measure: Calculates distances (not
                                         implemented)
                                      • Infopoi: information on a point of interest.
                                      • Infoter: Information on a geoentity from any
                                         given coordinate.
                                      • Pois: Opens the poi category selection
                                         dialogue.
                                      • export: (not implemented)
                                      • Customclick1*: personalization button. (see
                                         annex)
                                      • Customclick2*: personalization button. (see
                                         annex)
      show_mouse_position        If true is specified it displays the mouse’s coordinates.
                                 False by default.
      xsl_name                   Name and path of the xsl template that uses the
                                 createReport function by default. If no path is
                                 specified, the template must be in the same folder as
                                 the configuration file.

    * customclick1/2

    Tool devised in order to obtain the pixel corresponding to the point clicked on the
    map. It can be implanted to obtain the true coordinates of any marked/clicked
Joaquim Botet i Sisó, 6   Avinguda Meridiana, 216, 1ª   tel 902 102255                9/47
17003 Girona              08027 Barcelona               www.nexusgeografics.com
    point by means of the getCoordFromPixel method

    In order to be implanted a menuCustomClick{n} function must be defined, which
    will be run when the map is clicked on with this tool. It can be used to send an
    alert, to obtain an event from its coordinates, etc…

    Example (sending an alert with the geographic coordinates of the point clicked
    on):

       function menuCustomClick1(e) {
         alert("coord EPSG:4326   "
                +cercalia.getCoordFromPixel(e.xy,"EPSG:4326"));
       }



4 The cercaliaClient class

     4.1 Structures or objects used by this tutorial’s
         classes.

    CercaliaClient is this API’s main class. The objects in this tutorial represent a
    map and possess all the Cercalia calling methods and services. The methods’
    initial parameters are structures composed of the following classes:


           4.1.1          Attributes of an error (Error)

               Field                                           Description
        id                 Error code
        type               Type of error
        text               Error description


           4.1.2          Attributes of a candidate (candidate)

               Field                                           Description
        desc               Candidate description
        type               Type of candidate
        id                 Geoentity identifier
        name               Name of the geoidentity
        ge                 Type of geoentity object
        pos                Order number (Used to order the results)


           4.1.3          Attributes of a geoentity (Geoentity)

               Field                                           Description



Joaquim Botet i Sisó, 6          Avinguda Meridiana, 216, 1ª          tel 902 102255            10/47
17003 Girona                     08027 Barcelona                      www.nexusgeografics.com
        type                Type of geoentity:
                               •     ctry: Country
                               •     reg: Region
                               •     subreg: Subregion
                               •     mun: municipality
                               •     ct: City / town/ place.
                               •     st: Street
                               •     rd: Road
                               •     pcode: Post code
                               •     poi: Point of interest
        countryId           Country code
        country             Country name
        regionId            Region code
        region              Region name
        subregionId         Subregion code
        subregion           Subregion name
        municipalityId      Municipality code
        municipality        Municipality name
        cityId              City / town / place / code
        city                City / town / place / name
        streetId            Street code
        street              Street name
        streetPrefix        Street prefix
        streetArticle       Street article
        streetName          Short street name
        houseNumber         Street number
        postalCode          Postal code
        roadId              Road code
        roadName            Road name
        km                  Road kilometric point
        poiId               Point of interest code
        poiName             Point of interest name
        x                   X coordinate at the centre of a geoentity
        y                   Y coordinate at the centre of a geoentity
        srs                 Coordinate’s reference system
        arc                 Arc type object (only informed in proximity)
        prox                Prox type object (only informed in proximity)
        pos                 Order number (used to order results)



           4.1.4          Attributes of a point of interest (Poi)

               Field                                             Description
        id                  Point of interest code
        name                Point of interest name
        categoryId          Category code
        subcategoryId       Subcategory code
        geometry            Type of geometry:
                              P: Point
                              L: Line
                              Z: Polygon
        info                Information on a point of interest

Joaquim Botet i Sisó, 6            Avinguda Meridiana, 216, 1ª         tel 902 102255            11/47
17003 Girona                       08027 Barcelona                     www.nexusgeografics.com
        infoxml             Xml information on a point of interest in a string object
        x                   Point of interest x coordinate
        y                   Point of interest y coordinate
        srs                 Coordinate’s reference system
        ge                  Geoentity related to the point of interest
        prox                Prox type object
        pos                 Order number (used to order results)
        wkt                 Geometry of the interest point in web format known text o null.
                            This field only inform “calculateRoute”



           4.1.5          Attributes of proximity (Prox)

              Field                                            Description
        dist               Euclidean distance (straight line) from the centre
        routedist          Distance by car (only if weight has been specified in the call)
        routetime          Distance in time (only if weight has been specified in the call)


           4.1.6          Attributes of arc (Arc)

              Field                                            Description
        frc                Type of stretch. Functional road class.
        kmh                Speed of stretch
        zonename           Name of the zone to which the stretch belongs
        zonetype           Type of zone


           4.1.7          Attributes of a mobile object (Mo)

              Field                                            Description
        id                 Identifier
        desc               Description (optional)
        status             Status (optional)
        x                  Central reference x coordinate
        y                  Central reference y coordinate
        srs                Coordinates reference system (see code annex)
        pos                Order number (used to order results)




           4.1.8          Attributes of a marker style object (markerStyle)

                  Field                                            Description
        icon                    Name of the file for the icon (e.g. “ico2.gif”)
        width                   Icon image width in pixels
        height                  Icon image height in pixels
        visible                 Boolean which indicates if you want to show the marker
                                information
        minimized               Boolean which indicates if you only want to show the marker’s title

Joaquim Botet i Sisó, 6          Avinguda Meridiana, 216, 1ª          tel 902 102255            12/47
17003 Girona                     08027 Barcelona                      www.nexusgeografics.com
        noHideOthers    Boolean which indicates not having to minimize all other existing
                        markers when creating the current one, in the case that it can be
                        minimized.
        showNumber      Boolean which indicates the possibility of shoeing the number on
                        the marker icon
        numberTextColor String with the icon number colour (e.g. “#FFFFFF”)
        title           Marker title format
        content         Content format
        cssTitle        String with the style to be applied to the title




4.1.9. Attributes of a feature

         Field                     Description
        <Geometry>                 A geometric object in the requested format
        Id                         Internal object identifier
        created                    Boolean indicating that it is an object created by the user
                                   (*)
        modified                   Boolean indicating that it is an object modified by the user
                                   (*)
        deleted                    Boolean indicating that it is an object deleted by the user
                                   (*)
        style                      The style in which the object has been created.
        styleSelect                The style in which the object is viewed when it is selected
                                   for editing.
              (*) if all the Booleans are false, the object has not changed with respect to the original

   The <Geometry> field is represented as one of the following fields, depending on
   the method requested to obtain the features:

         Field                     Description
        Wkt                        Geometric object in “Well-known Text Representation”
        Gml                        Geometric object in GML v.3 format



     4.2 Methods for the treatment of markers

           4.2.1          createMarker (id, x, y, srs, style, id2)

Create a marker according to the parameters which affect it:

    •    id: Identifier of the marker and div which will hold the marker’s content.
    •    x,y: x and y coordinates where the marker will be situated.
    •    srs: Coordinates system used (see coordinates systems annex).
    •    style: markerStyle type object which defines the marker’s characteristics.
    •    id2: Optional parameter which enables us to associate a current marker with
         another, and an arrow between the two can be drawn.

Marker examples:

Joaquim Botet i Sisó, 6          Avinguda Meridiana, 216, 1ª      tel 902 102255                           13/47
17003 Girona                     08027 Barcelona                  www.nexusgeografics.com
Maximized marker:




Minimized marker:




Marker without visible content and title:



In this case we do not associate the marker to any other, and therefore we do not
pass the last parameter.

If a markerStyle which does not specify either title or cssTitle in the label is used,
there will only be content. The content will have to be a valid html and the view
format will have to be specified by the user (pos css) or by means of an attribute
style. If content is not specified either, a marker without a label will be created.

Code examples:

var cont = '<font style="font: 12px black; padding: 5px;">11:00:00</font>' ;

var style={icon:"img/green_lorry.gif", width:22, height:22, visible:true,
   minimized:false, title:"10101OUO", cssTitle:"contTitolPopup", content:cont,
   noHideOthers:true};

cercalia.createMarker(“10101 OUO 1”, 43.458308,-3.808951, “EPSG:4326”, style);


Content examples:
var cont=’’;

cont+=’<div class=”estilCSS”>’;
cont+=’interiorContenido’;
cont+=’</div>’;

var cont2=’’;

cont2+=’<div style=”background: #FFFFFF; color: #000000; border-color: blue;”>’;
cont2+=’interiorContenido’;
cont2+=’</div>’;


In interiorContent we can put whatever html code we want: images, tables, etc… In
the     previous    example:   '<font    style=”font:  12px    black;     padding:
5px;”>11:00:00</font>'



           4.2.2          createMarkers (obj, style)

This function creates markers for the elements contained within an object resulting

Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255            14/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
from a geocoding or a proximity. The obj parameter must have resultGeocoding,
resultProximity or resultGetPoi type. The style object is a list of attributes
belonging to a markerStyle.

In the title, icon and content attribute of the markerStyle, candidate fields, points of
interest or geoentity fields can be specified, the marker of which is created by means
of the format: %{expr}%, a message code from the message file may also be
specified with the syntax: %[msg1]%

Code exemple to create interest points markers:

function obtenerPois()
{
   cercalia.getPoi(1,"C57240362250410,C57240362276846",retorno);
}

function retorno(datos)
{
   var style={width:16, height:16, visible:true,
               minimized:false, noHideOthers:true,
               showNumber:false, content:null,
               cssTitle:”contTitolPopup“};

    var cont = '';

    if(datos.pois!=null && datos.pois.length>0)
    {
       cont+='<table>';
       cont+='<tr><td colspan="2"><b>%{pois.name}%</b></td></tr>';
       cont+='<tr><td>%[City]%</td><td>%{pois.ge.city}%</td></tr>';
       cont+='<tr><td>%[PostalCode]%</td><td>%{pois.ge.postalCode}%</td></tr>';
       cont+='<tr><td>%[Municipality]%</td><td>%{pois.ge.municipality}%</td></tr>';
       cont+='<tr><td>%[Subregion]%</td><td>%{pois.ge.subregion}%</td></tr>';
       cont+='<tr><td>%[Region]%</td><td>%{pois.ge.region}%</td></tr>';
       cont+='<tr><td>%[Country]%</td><td>%{pois.ge.country}%</td></tr>';
       cont+='</table>';

        style.title="%{pois.name}%";
        style.content=cont;
        style.numberTextColor="red";
        style.showNumerated=true;
        style.icon="img/point_prox.gif";
        cercalia.createMarkers(dades.pois,style);
        cercalia.centerToMarkers(true);
    }
}


Code example to create the first interest point marker:


function obtenerPois()
{
   cercalia.getPoi(1,"C57240362250410,C57240362276846",retorno);
}

function retorno(datos)
{
   var style={width:16, height:16, visible:true,
               minimized:false, noHideOthers:true,
               showNumber:false, content:null,
               cssTitle:”contTitolPopup“};

    var cont = '';


Joaquim Botet i Sisó, 6     Avinguda Meridiana, 216, 1ª   tel 902 102255            15/47
17003 Girona                08027 Barcelona               www.nexusgeografics.com
    if(datos.pois!=null && datos.pois.length>0)
    {
       cont+='<table>';
       cont+='<tr><td colspan="2"><b>%{poi.name}%</b></td></tr>';
       cont+='<tr><td>%[City]%</td><td>%{poi.ge.city}%</td></tr>';
       cont+='<tr><td>%[PostalCode]%</td><td>%{poi.ge.postalCode}%</td></tr>';
       cont+='<tr><td>%[Municipality]%</td><td>%{poi.ge.municipality}%</td></tr>';
       cont+='<tr><td>%[Subregion]%</td><td>%{poi.ge.subregion}%</td></tr>';
       cont+='<tr><td>%[Region]%</td><td>%{poi.ge.region}%</td></tr>';
       cont+='<tr><td>%[Country]%</td><td>%{poi.ge.country}%</td></tr>';
       cont+='</table>';

        style.title="%{poi.name}%";
        style.content=cont;
        style.numberTextColor="red";
        style.showNumerated=false;
        style.icon="img/point_prox.gif";
        cercalia.createMarkers(dades.pois[0],style);
        cercalia.centerToMarkers(true);
    }
}


           4.2.3          moveMarker (id, x, y, srs, cont)

Moving the marker with the id identifier to new coordinates.

    •    id: Identifier of the marker and div which will hold the marker’s content.
    •    x,y: x and y coordinates where the marker will be situated.
    •    srs: Coordinates system used.
    •    cont: html content valid for refreshing the marker’s popup. (Optional
         parameter).

Example 1:
cercalia.moveMarker("10101 OUO 1",43.458425,-3.80895,”EPSG:4326”);



Example 2:

Changes the content of the marker’s (indicated by parameter) popup.
var cont = '<font style="font: 12px black; padding:5px;">'+lon+','+lat+'</font>';
cercalia.moveMarker("10101 OUO 1",43.458425,-3.80895,”EPSG:4326”,cont);



           4.2.4          setMarkerIcon(id,url)

Allows modification of the marker icon indicated by the parameter ID. The picture that
will replace the current one is indicated by the URL parameter. Both parameters are
obligatory and there should be a marker with the identifier indicated.

For example, it can be combined with the utility of the mouseclick attribute of the
createMarker function style parameter. In this way the state of the icon can be
modified when the user clicks on it.

Example 1:


Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255            16/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
cercalia.setMarkerIcon(“10101 OUO 1”,”img/red_car.gif”);


           4.2.5          deleteMarkers ([id l [, id2[…]]])

Eliminates the markers which pass their identifier through a parameter. If no identifier
passes, all the map’s markers will be eliminated.

Examples:

Eliminate all markers:

cercalia.deleteMarkers();

Eliminate one marker:

cercalia.deleteMarkers("10101 OUO 1");

Eliminate three markers:

cercalia.deleteMarkers("10101 OUO 1","10101 OUO 2","10101 OUO 3");


           4.2.6          centerToMarkers (changeScale [,id 1 [, id2 […]]])

Centres the map with respect to the markers which pass their identifiers through a
parameter. If no identifier is passed, it will be centred on all the map’s markers.

    •    changeScale: Boolean which indicates if the scale must be changed in order
         to view all the affected markers.

Examples:

Centre the map with respect to all the markers changing the scale in order to view
them all.
cercalia.centerToMarkers(true);

Centre the map on a marker without changing the scale:
cercalia.centerToMarkers(false,"10101 OUO 1");

Centre the map with respect to three markers changing the scale:
cercalia.centerToMarkers(true,"10101 OUO 1","10101 OUO 2","10101 OUO 3");




           4.2.7          showMarkers (state [,id1 [, id2 […]]])

Change the state of visibility of markers to their previous state using the state
parameter. This change affects all markers which pass their identifier through a
parameter, and in the case of there being no identifier, it will affect all the map’s
markers.

Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255            17/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
    •state:         state in which the affected markers will be changed. These can be
     three:
         o         closed: will close the markers.
         o         minimized: will minimize the markers.
         o         maximized: will maximize the markers.
Examples:

Maximize all the map’s markers:
cercalia.showMarkers("maximized");

Minimize a marker:
cercalia.showMarkers("minimize","10101 OUO 1");

Hide the information related to three markers:
cercalia.showMarkers("closed","10101 OUO 1","10101 OUO 2","10101 OUO 3");



     4.3 Methods for handling features

           4.3.1          createFeature (wkt, srs, style)

Create one or more features based on their geometric definition in WKT, the
reference system and the style definition. It returns a list of identifiers for the created
features.

    •    wkt: geometric features
    •    srs: coordinates system used *
    •    style: depiction style
    •    editstyle: published depiction style

* Possible coordinate system values (srs parameter): see annex

The WKT (“Well-known Text Representation for Geometry”) format is the standard
for interchanging geometries defined by the Open Geospatial Consortium. The
following table shows examples of this format:




Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255            18/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
For further information see OpenGIS® Implementation Specification for Geographic
information - Simple feature access - Part 1: Common architecture.

The parameter style is a list of properties with their values:

     Property               Description                                Default value
     fillColor              Fill colour                                “#ee9900”
     fillOpacity            Fill opacity                               0.4
     strokeColor            Line or contour colour                     “#ee9900”
     strokeOpacity          Line or contour opacity                    1
     strokeWidth            Line or contour width                      1
     pointRadius            Point size in pixels                       0

Example for drawing a polyline:
f25 = cercalia.createFeature("LINESTRING(-2.4027508398930078 41.190563340655544,-2.402553210530501
41.188147539419674,-2.398420960223551                            41.18071635184718,-2.398340111847981
41.179012827498276)","EPSG:4326",{strokeWidth: 5,strokeColor: "#FF0000"});

Example for drawing a polygon:
f31 = cercalia.createFeature("POLYGON(-448003 4817761,-706393 4682834,-667531 4466724,-448003
4817761)","EPSG:54004",{strokeWidth: 3,strokeColor: "#00ee00", fillColor: "#00ee00",fillOpacity: 0.2});

Example for drawing a rectangle:
f41 = cercalia.createFeature("POLYGON(-758765 4940710,-756487 4940710,-756487 4941341,-758765
4941341,-758765         4940710)","EPSG:54004",{strokeWidth: 3,strokeColor: "#00ee00", fillColor:
"#00ee00",fillOpacity: 0.2});

Example for drawing a circle:
f51 = cercalia.createFeature("POINT (-448003 4817761)","EPSG:54004",{strokeWidth: 3,strokeColor: "#00ee00",
fillColor: "#00ee00",fillOpacity: 0.2});

Similarly, the parameter editstyle contains the style of the features when the user
wishes to change them.




Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª      tel 902 102255                       19/47
17003 Girona                    08027 Barcelona                  www.nexusgeografics.com
           4.3.2          createFeature(gml,style [, editstyle])

Create one or more features based on their geometric definition in GML 3.1.1
(Geography Markup Language) as a string and the style definition. This returns a list
of identifiers for the created features.

    •    gml: geometric features
    •    style: depiction style
    •    editstyle: editing depiction style

The GML format must contain the value for the srsName field. If it does not, it will be
assumed that the coordinates are shown in the map coordinate system.

For more information on the GML standard, see the specification provided by
OpenGIS (http://www.opengeospatial.org/standards/gml).


           4.3.3          centerToFeatures (changeScale [, feature1 [, feature2
                          […]]])

Centres the map on the features in one or more of the parameters. If no object is
shown, it will centre on all the features shown on the map.

    •    changeScale: Boolean that shows us if the scale has to be modified to show
         all the affected features.

Examples:

Centres the map with respect to all the features, changing the scale so that they can
all be seen:
cercalia.centerToFeatures(true);

Centres the map on a feature without changing the scale:
cercalia.centerToFeatures(false,f25);

Centres the map with respect to two features, changing the scale:
cercalia.centerToFeatures(true,f25,f31);



           4.3.4          deleteFeatures([feature1 [, feature2 [...]]])

Eliminates the features specified in one or more parameters. It none is specified, all
the features will be deleted. If no parameters are specified, all the elements on the
list of features previously eliminated using the draw tool        utilities will also be
deleted (see “Editing Tools” annex). The features in the ‘deleted’ state can no longer
be consulted with the getFeaturesByState method.

Examples:

Joaquim Botet i Sisó, 6            Avinguda Meridiana, 216, 1ª   tel 902 102255            20/47
17003 Girona                       08027 Barcelona               www.nexusgeografics.com
Eliminate all features:
cercalia.deleteFeatures();

Eliminate a feature:
cercalia.deleteFeatures(f25);

Eliminate two features:
cercalia.deleteFeatures(f25,f31);



           4.3.5           getFeaturesByState(created, modified, deleted,
                           unchanged[,SRS])
Get the features that comply with indicated states: allows the geometry of the
features created using the API digitalisation module to be recovered and stored in a
database (see Annex 8).

As an optional parameter, you can indicate the coordinate system in which you wish
to obtain the geometries. If this is not specified, that corresponding to the background
map will be used.

States:

    •    created: Boolean to get the new features created by the user.
    •    modified: Boolean to get the features modified by the user.
    •    deleted: Boolean to get the features deleted by the user.
    •    unchanged: Boolean to get the features unchanged by the users.

Any combination of states can be made. However, any false state will not return a
reply.

The features are returned in a resultFeatures object, with the following definition:

     Field                Description
    features              List of Feature type objects

The features will have the wkt attribute to contain the definition of the geometry.

Examples:

Get the features that have been created on the map (new features) using the draw
tool       (see annex “Editing Tools”).

var resfeatures=cercalia.getFeaturesByState(true,false,false,false);
var numFeatsNew = resfeatures.features.length;

Get the features that have been created using the createFeature function that have
subsequently been modified using the draw tool utilities.

var resfeatures=cercalia.getFeaturesByState(false,true,false,false);

Joaquim Botet i Sisó, 6             Avinguda Meridiana, 216, 1ª   tel 902 102255            21/47
17003 Girona                        08027 Barcelona               www.nexusgeografics.com
           4.3.6          getFeaturesByStateAsGML(created, modified,
                          deleted, unchanged[,SRS])
Get the features that comply with the indicated states (similar to the previous
function).

The features are returned in a resultFeatures object. The features will have the gml
attribute to contain the geometry definition.


           4.3.7          getFeatures([feature1 [, feature2 [...]]][,SRS])
Get the features specified in one or more parameters. If no feature is specified, they
will all be returned. This allows you to recover and store the geometry of the features
created with the API digitalization module in your own database (see Annex 8).

The features are returned in a resultFeatures object. The features will have the wkt
attribute to contain the definition of the geometry.

Features deleted with the draw         tool will only be returned if they have been
created with the createFeature function.



           4.3.8          getFeaturesAsGML([feature1 [, feature2 [...]]][,SRS])
Get the features specified in one or more parameters in a similar way to the previous
function.

The features are returned in a resultFeatures object. The features will have the gml
attribute to contain the definition of the geometry.

     4.4 Methods for map treatment


           4.4.1          activateTool(tool)

Selects or activates the tool which is indicated by the parameter (‘pan’, ‘zoomin’,
‘zoomout’, ‘draw’, ‘clean’, measure’, ‘infopoi’, ‘infoter’, ‘pois’, ‘export’, ‘customclick1’,
‘customclick2’). The tool must be available in the tool bar.

cercalia.activateTool(“customclick1”);



           4.4.2          isCompleted()
It returns true boolean if cercalia object is ready to use it


           4.4.3          showPois(visible,category[[,category]…])
Show or not show the visualization of the interest points of the specified category. If

Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255               22/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
you don’t indicate categories, they will visualize or will desactivate the category of all
existing categories according to the visible parameter indicated.

Example to visualize the categories C001 C003 of the interest points

cercalia.showPois(true,’C001’,’C003’);


Example to desactivate the categories C001 and C003 of the interest points

cercalia.showPois(false,’C001’,’C003’);



           4.4.4          setLanguage(lang)
It changes client’s language. lang parameter indicates the language that we want
change. If it doesn’t exist a language xml file it will appear an error message.

Example to change language to English:

cercalia.setLanguage(‘EN’);



           4.4.5          getMap()
It returns an OpenLayers.Map object. You should check the OpenLayers API
documentation      to    understand the   possibilities of  this   object
(http://www.openlayers.org)

Example:

var map = cercalia.getMap();
map.events.register("zoomend", map, actualizarPosicion);



           4.4.6          deleteRoute (resultCalculateRoute)
It deletes any graphic representation of a route (marks and features).


           4.4.7          setParse< operation> (function)
These methods allow the customization response received by the user when he
activates the actions in the sidebar or buttons.

Function names to call the code, and respective parameters are:

setParsePanelSearchGeo (function)

It lets you customize the realized action after the candidates searched with the side
panel (address or postcode panel). The function parameter must specify a function
that receives a parameter as resultGeocoding. This function can call
showResultPanelSearchGeo (resultGeocoding) to show results.

setParsePanelSearchCoord (function)


Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255            23/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
It lets you customize the realized action after the coordinate searched in the side
panel. The function parameter must specify a function that receives a parameter as
resultProximity.     This   function   can     call   showResultPanelSearchCoord
(resultProximity) to show results.

setParsePanelProximity (function)

It lets you customize the realized action after the proximity searched in the side
panel. The function parameter must specify a function that receives a parameter as
resultProximity. This function can call showResultPanelProximity (resultProximity) to
show results.

setParseToolInfoPOI (function)

It lets you customize the realized action after the searched POI information selected
in the side panel. The function parameter must specify a function that receives a
parameter as resultProximity. This function can call showToolInfoPOI(resultProximity)
to show results.

setParseToolInfoTer (function)

It lets you customize the realized action after the information obtained. The function
parameter must specify a function that receives a parameter as resultProximity. This
function can call showToolInfoTerI(resultProximity) to show results.

Example: modify the output of candidates to obtain a marker on the map for each
candidate.
function functionSetParsePanelGeo(data)
    {
        if(data.candidates && data.candidates.length>1)
        {
            var cont="";
            cont+='<table style="font-size: 11px;font-family: Tahoma;color: #666666;
width:100%; height:100%; padding:4px; ">';
                    cont+='<tr><td style="border-bottom: 1px solid rgb(134, 134, 134);
padding-top:5px; padding-bottom:5px;" colspan="2"><b>%{candidates.name}%</b></td></tr>';
                    cont+='<tr><td style=" padding-top:5px; padding-bottom:5px;"
><b>%[City]%</b></td><td>%{candidates.ge.city}%</td></tr>';
                    cont+='<tr><td style="padding-bottom:5px;"
><b>%[PostalCode]%</b></td><td>%{candidates.ge.postalCode}%</td></tr>';
                    cont+='<tr><td style="padding-bottom:5px;"
><b>%[Municipality]%</b></td><td>%{candidates.ge.municipality}%</td></tr>';
                    cont+='<tr><td style="padding-bottom:5px;"
><b>%[Subregion]%</b></td><td>%{candidates.ge.subregion}%</td></tr>';
                    cont+='<tr><td style="padding-bottom:5px;"
><b>%[Region]%</b></td><td>%{candidates.ge.region}%</td></tr>';
                    cont+='<tr><td style="padding-bottom:5px;"
><b>%[Country]%</b></td><td>%{candidates.ge.country}%</td></tr>';
                    cont+='</table>';
            var style={ icon:"img/xinxeta.gif",
                         width:16,
                         height:16,
                         visible:false,
                         minimized:false,
                         title:"%{candidates.name}%",
                         noHideOthers:true,
                         showNumber:false,
                         content:cont,cssTitle:""};
            style.cssTitle="contTitolPopup";
            cercalia.createMarkers(data.candidates,style);
            cercalia.centerToMarkers(true);
        }
        else cercalia.showResultPanelSearchGeo(data);

Joaquim Botet i Sisó, 6     Avinguda Meridiana, 216, 1ª   tel 902 102255                   24/47
17003 Girona                08027 Barcelona               www.nexusgeografics.com
     }

cercalia.setParsePanelSearchGeo(functionSetParsePanelGeo);


Example: Modify the information “infoposition” output to obtain the coordinates in
geographic format.
function infoposicion(data)
{
        cercalia.transformCoordinates(data.geoentities,"EPSG:4326");
        cercalia.showToolInfoTer(data);
}

cercalia.setParseToolInfoTer(infoposicion);




           4.4.8          showResult< operation> (obj)
If with the functions you only want manipulate the data and you want finish with a
presentation by default, you can call the following methods:

showPanelSearchGeo (resultGeocoding)

Show the results of a candidates searched on the side panel (postal address or
postal code).

showPanelSearchCoord (resultProximity)

Show the results of a coordinates searched on the side panel.

showPanelProximity (resultProximity)

Show the results of a proximity searched on the side panel.

showToolInfoPOI (resultProximity)

Show on the map the information of the closest POI.

showToolInfoTer (resultProximity)

Show on the map the information of the closest geoentity.


           4.4.9          getExtent(srs)
It returns an OpenLayers.Bounds Object with the coordinates of the extension map
that you are visualizing. The coordinates will be in the system indicated by the
obligatory parameter srs.

Example: Get the map extension with the current coordinate system.

function obtenerExtension()
{
       var srs = cercalia.getCurrentSRS();

var ext = cercalia.getExtent(srs);

Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255            25/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
          alert(ext.left+","+ext.bottom+","+ext.right+","+ext.top);



           4.4.10         getCenter(srs)
It returns an OpenLayers.LonLat object with the coordinates of the center of the map
that you are visualizing. The coordinates will be in the system indicated by the
obligatory parameter srs.

Example: get the map’s center with the current coordinate system:

function obtenerCentro()
{
       var srs = cercalia.getCurrentSRS();

         var center=cercalia.getCenter(srs);

alert(center.lon+","+center.lat);
}



           4.4.11         setCenter(center,scale)
It changes the map’s center that you are visualizing at this moment. The center
parameter will have the next format {x:…., y:….., srs:…..} where x, y are coordinates
and srs the coordinate system. If we indicate the scale parameter the visualization of
the map will fit the scale1 level of cercalia’s system. If we don’t work with Cercalia’s
Cartography it will fit it to the current closest scale level of cercalia.

Example: update the center of the map with the coordinates of the system
EPSG:4326 and indicates a scale level of cercalia.

function actualizaCentro()
{

var point={x:"2.820709",y:"41.976419",srs:"EPSG:4326"};
cercalia.setCenter(point,5);
}



           4.4.12         setCenter(center,srs,scale)
It changes the center of the map to other specified. The center parameter should
have OpenLayers.LonLat object, and the coordinates should be in the coordinate
system indicated by srs. If we indicate the scale parameter the visualization of the
map will fit the scale2 level of cercalia’s system. If we don’t work with Cercalia’s
Cartography it will fit it to the current closest scale level of cercalia.

Example: Update the center of the map with coordinates of the EPSG system:

function actualizaCentro()
{


1 There are 14 scale levels in cercalia’s system (0 to 13). Level 0 is the smallest and level 13 is
the biggest available in Cercalia.
2 There are 14 scale levels in cercalia’s system (0 to 13). Level 0 is the smallest and level 13 is

the biggest available in Cercalia.
Joaquim Botet i Sisó, 6         Avinguda Meridiana, 216, 1ª   tel 902 102255                  26/47
17003 Girona                    08027 Barcelona               www.nexusgeografics.com
        var lonlat = new OpenLayers.LonLat("2.820709","41.976419");
 cercalia.setCenter(lonlat,"EPSG:4326");
}


           4.4.13         zoomToExtent(extent,srs)
Adjusting the zoom’s map to the indicated extend. The parameter srs indicates the
coordinate system which is expressed by the extend. The extend is indicated by the
extend parameter and it can be an OpenLayers.Bounds object or a list with four
attributes: {x1: ….., y1: ….., x2: ……, y2: …. .}

Example:

var ext=new OpenLayers.Bounds(-22000000,-13191574,21000000,18500000);
cercalia.zoomToExtent(ext,"EPSG:54004");


ó
var ext={x1:”-22000000”,y1:”-13191574”,x2:”21000000”,y2:”18500000”);
cercalia.zoomToExtent(ext,"EPSG:54004");



           4.4.14         getScale(closest)

It returns a numeric that indicates the current scale3 level of the map. If closes is true
it returns the current scale level of cercalia and if we work with other cartography it
returns the closest scale level of cercalia according to the map we are using

If closest is false it always returns the scale level of cercalia and if we work with other
cartography it will return null. getSyle method indicates the cartography that we are
using.


           4.4.15         getCurrentSRS ()
It returns a string indicating the current coordinate system.



     4.5 Methods for obtaining information

           4.5.1          geocoding(search,returnFunc)
Makes a petition of geoconversion according to the search object’s parameters.
Once resolved the returnfunc function is run passing a resultGeocoding type object
as a parameter.

The search object may contain the following fields:

           Field                                   Description                              P. Serv. Cerc.
    name                  name filter without specifying level                             locn

3 There are 14 scale levels in cercalia’s system (0 to 13). Level 0 is the smallest and level 13 is
the biggest available in Cercalia.
Joaquim Botet i Sisó, 6           Avinguda Meridiana, 216, 1ª    tel 902 102255                        27/47
17003 Girona                      08027 Barcelona                www.nexusgeografics.com
    countryId   country code filter                                                 ctryc
    country     country name filter                                                 ctryn
    regionId    region code filter                                                  regc
    region      region name filter                                                  regn
    subregionId subregion code filter                                               subregc
    subregion   subregion name filter                                               subregn
    subOrRegion region or subregion name filter                                     rsn
                municipality code filter
    municipalityId                                                                  munc
    municipalitymunicipality name filter                                            munn
    cityId      city / town / place code filter                                     ctc
    city        city / town / place name filter                                     ctn
    postalCode  postal code filter. Country code must be specified                  pcode
    streetId    street code filter                                                  stc
    street      street name filter                                                  stn
    street2     second street name filter for the calculation of an                 istn
                intersection
    street2Id   second street code filter for the calculation of an                 istc
                intersection
    houseNumber street number filter                                                stnum
    roadName    road name filter                                                    rdn
    roadId      road code filter                                                    rdc
    km          kilometric point filter for roads                                   km
    fullSearch  Search all candidate parameters                                     fullsearch
    numCand     Number of candidates to be returned per page                        numcand
    posCand     position of the first candidate to be returned starting             poscand
                with 0
    num         Maximum number of results
    poicat      Points of interest categories list filter                           poicat
    poiId       Point of interest code filter                                       poic
    poiName     Point of interest name filter                                       poiname

The intersection parameters are incompatible with the street number, and can only
be used when street specification exists. The parameters for specifying street and
road are mutually incompatible.

If there are more than one candidate the coordinate backed away couldn’t be the
coordinate sought. For exemple, if we seek an address (street + number) and we
send back us candidates of country, city, street, etc, … the coordinates of these
candidates will be the country, city or street but not the portal (number).

The parameters are passed in the following way:

         var search={ countryId:null, city:null };
         search.countryId = ”ESP”; // Código del país
         search.city = ”Madrid”; // Nombre de localidad
         cercalia.geocoding(search, execute);

         function execute(data)
         {
                // tratar información
         }


The resultGeocoding information data is the following:



Joaquim Botet i Sisó, 6     Avinguda Meridiana, 216, 1ª   tel 902 102255                         28/47
17003 Girona                08027 Barcelona               www.nexusgeografics.com
     Response type            Field                                Description
         error            error            Error type object (if there is no error it contains null)
                          candidates       List of Candidate type objects
                          pos              Position of the first returned candidate
                          numCand          Number of candidates per page
        Candidates
                          num              Maximum number of desired results indicated in the
                                           query
                          total            Total number of search candidates


           4.5.2          proximity(search,returnFunc)

Performs a proximity request/query according to the search object parameters. In
order to carry out a proximity the reference parameters (the centre of the search)
must be specified and parameters that specify which are referred to (those being
searched for near the centre).


In order to specify the reference the same parameters are used as in geocoding:


         Campo                                     Descripción                              P. Serv. Cerc.
          Field
    name        name filter without specifying level                                        locn
    countryId   Country code filter                                                         ctryc
    country     country name filter                                                         ctryn
    regionId    region code filter                                                          regc
    region      region name filter                                                          regn
    subregionId subregion code filter                                                       subregc
    subregion   subregion name filter                                                       subregn
    subOrRegion region or subregion name filter                                             rsn
                municipality code filter
    municipalityId                                                                          munc
    municipalitymunicipality name filter                                                    munn
    cityId      city / town / place code filter                                             ctc
    city        city / town / place name filter                                             ctn
    postalCode  Postal code filter. Country code must be specified                          pcode
    streetId    Street code filter                                                          stc
    street      Street name filter                                                          stn
    street2     second street name filter for the calculation of an                         istn
                intersection
    street2Id   second street code filter for the calculation of an                         istc
                intersection
    houseNumber street number filter                                                        stnum
    roadName    road name filter                                                            rdn
    roadId      road code filter                                                            rdc
    km          kilometric point filter for roads                                           km
    fullSearch  Resolve all candidate parameters                                            fullsearch
    numCand     number of candidates to be returned                                         numcand
    posCand     position of the first candidate to be returned starting                     poscand
                with 0
    num         Maximum number of desired results



Joaquim Botet i Sisó, 6           Avinguda Meridiana, 216, 1ª     tel 902 102255                         29/47
17003 Girona                      08027 Barcelona                 www.nexusgeografics.com
or a coordinate centre is specified:


            Field                                                Description
    x                     reference centre X coordinate
    y                     reference centre Y coordinate
    srs                   Coordinates reference system (see codes annex)


In order to specify references, one of the following three types may be specified:
geoentity, points of interest or mobile objects.

In all three cases a search radius may be specified (in Euclidean distance) and a
maximum number of results.

In the case of points of interest the weight parameter may be defined to calculate
distance and time by car and order the result according to the minimum time (time),
distance (distance) or money (money) cost. By default the program calculates the
cost from the reference point to the referred to point. If you want to calculate a cost
the other way round the inverse to true parameter must be specified.


        Referred to          Field
           type                                                        Description
         geoentity        rqge              Geoentity level (adr,st,ct,mun,subreg,reg,ctry)
                          rqpoicats         Points of interest categories list separated with
                                            commas
                          infoxml           Numerical which indicates the point of interest xml
                                            information to be returned.
     points of interest
                          weight            Optional. Cost of ordering results. Possible time,
                                            distance, money values
                          inverse           Optional. May have true or false values. When true the
                                            cost is from the referred to the reference.
      mobile objects      mos               Mo type mobile objects list
                          num               Maximum number of results
          common
                          rad               Maximum search radius (Euclidean distance)

The parameters are passed in the following way:

          var search={countryId:null, city:null, num:0, rad:0, rqpoicats:null };
          search.countryId=”ESP”; // Código del país
          search.city=”Madrid”; // Nombre de localidad
          search.num=5; // cinco candidatos
          search.rad=1000; // radio de 1000 metros
          search.rqpoicats=”C001”; // Gasolineras
          cercalia.proximity(search,execute);

          function execute(data)
          {
                 // tratar información
          }


If the search result didn’t have candidates or had more than one candidate the
returnFunc function indicated with the same structure as a resultGeocoding is
called.

Joaquim Botet i Sisó, 6            Avinguda Meridiana, 216, 1ª        tel 902 102255            30/47
17003 Girona                       08027 Barcelona                    www.nexusgeografics.com
The resultProximity return data is the following:

     Response type            Field                                Description
         error            error            Error type object (if there is no error it contains null)
                          candidates       Candidate type candidates list (only if there is more
                                           than one candidate)
                          pos              Position of the first returned candidate
        candidates        num              Maximum number of results desired indicated in the
                                           query/request
                          numCand          Number of candidates per page
                          total            Total number of search candidates
                          type             Type of proximity requested {adr, st, ct, mun, subreg,
          proximity
                                           reg, ctry, poi}
                          pois             poi objects list (only in poi resolved proximity)
       POI proximity

                          location         Geoentity where the reference is situated
         Geoentity
         proximity        geoentities      Geoentity type objects list (only in geoentity resolved
                                           proximity)
       mobile object      mos              Mo type objects list (only in mobile object resolved
        proximity                          proximity)


           4.5.3          getPoi (infoxml, poicode [, poicode [,…]], execute)

Sends a request to obtain information on indicated POIS using their corresponding
codes. Infoxml is a numerical to specify the xml information to be returned. Use 0 by
default. Once the information is resolved the execute (or run?) function with a
resultGetPoi type parameter is called which contains the result of the operation.


         cercalia.getPoi(“C57240362250385”,0,execute);

         function execute(getPoiResult)
         {
                if (getPoiResult.error) {
                       alert(“Error:” + getPoiResult.error.id)
                } else {
                       for (i=0;i< getPoiResult.pois.length; i++) {
                              alert(getPoiResult.pois[i].name);
                       }
                }
         }



ResultGetPoi format:

     Response type            Field                                description
         error            error            Error type object (if there is no error it contains null)
        POIS list         pois             poi objects list




Joaquim Botet i Sisó, 6           Avinguda Meridiana, 216, 1ª     tel 902 102255                       31/47
17003 Girona                      08027 Barcelona                 www.nexusgeografics.com
           4.5.4          calculateRoute(stopList,  routeParams,                           lineStyle,
                          drawStopMarkers, execute)

Calculate the optimum route from a list of stops.

StopList parameter specifies the list of stops. The first object of the list specifies the
origin and the last one specifies the destionation. The objects between them
specifies the stops. Each element of the list can be specified by:

    •    An object poi
    •    An object geoentity
    •    An object mo
    •    A coordinate: {x:<x> ,y:<y>, srs:<srs>}
    •    A geoentity code. Example: {cityId: ESP17240300056757 }
    •    A interest point code. Example: {poiId: C17240332252905}


The first three objects may be a solutions of a geocoding or proximity.

The “routeparams” parameter specify a list of options to calculate a route:

    Campo                 Descripción
    weight                Weight for route calculate (obligatory).
                          Valor              Idioma
                          distance           The route is calculated by the distance
                          time               The route is calculated by the time
                          money              The route avoid toll roads
    lang                  Language report (spanish language by default)
                          Valor              Idioma
                          ca                 Catalan
                          de                 Geman
                          en                 English
                          es                 Spanish
                          fr                 French
                          it                 Italian
                          nl                 Dutch
                          pt                 Portuguese
    mindist               Minimum distance covered to generate a skip between subetages
                          (1000 m by default).
    report                It indicates if the answer has a report or it only has a distance covered.
                          true – It returns a xml with a route description (by default).
                          false – It returns a xml only with distances and times covered.
    reorder               It indicates if we must reorder the stops or not to find the best path.
                          true – The stops are reordered to find the best path.
                          false – The stops are not reordered (by default)

Joaquim Botet i Sisó, 6           Avinguda Meridiana, 216, 1ª   tel 902 102255                      32/47
17003 Girona                      08027 Barcelona               www.nexusgeografics.com
    getpoicats              It gets information of the interest points selected in the route
    poiwkt                  Boolean that indicates if we must inform of the geometry of the interest
                            points. (false by default)
    poitolerance            Value that indicates the simplification’s degree of the interest points
                            geometry (100,0 meters by default)
    infoxml                 If we specify with another number different to 0 it returns a xml
                            information related of the interest points (0 by default).
    toll                    It retuns a total price of tolls included in the route
                            true – it returns information
                            false – It not retuns information.
                            Tolls only availables in Spain, Portugal and Andorra.
    intoll                  List of integer or integers. Each integer controls if the stop may find (or
                            not) on a stretch toll.
                            If it is -1 the stop always will find it out of stretch toll. If we specify a
                            positive number it will be allow that a stop will be in a stretch toll.
                            If the integers are finished the last one it uses to the rest of the stops.
                            For example: intoll=[-1] all the stops will be out of stretch tolls.
    net                     Specify the net to calculate routes. We must only specify in special
                            cases.
    xml                     Boolean that indicates if we want inform about the xml route report
                            (false by default)
    tolerance               Value that indicates simplification’s degree of routes geometry (false
                            by default).

The lineStyle parameter specify the route line properties. If this parameter is null the
route will not draw it.


     Property                  Description                                      Value by default
     strokeColor               Color line or outline                            “#ee9900”
     strokeOpacity             Opacitiy line or outline                         1
     strokeWidth               Width line or outline                            1

drawParadeMarkers parameter is a boolean that specify if we must create a marker
for the origin, stops or destination route.

execute parameter defines the function that will call when the route is solved by the
resultCalculteRoute type parameter.

resultCalculateRoute format:

     Answer                Field        Description
    Error                 error         Object type error (If there isn’t error then it contents null)
    ruta                  id            Route id
                          distance      Total distance route (in meters)
                          time          Total time in the next format: hh:mm:ss.
                          weight        Weight for the route (distance, time, toll)
                          lang          Language report (if there isn’t report it will be null).


Joaquim Botet i Sisó, 6              Avinguda Meridiana, 216, 1ª   tel 902 102255                        33/47
17003 Girona                         08027 Barcelona               www.nexusgeografics.com
                          mindist       Minimum distance between subetages (if there isn’t report it
                                        will be null)
                          coste_v1      Price tolls for vehicles type 1 (if there isn’t report it will be
                                        null)
                          coste_v2      Price tolls for vehicles type 2 (if there isn’t report it will be
                                        null)
                          coste_v3      Price tolls for vehicles type 3 (if there isn’t report it will be
                                        null)
                          stoplist      List of stops (type of poi, geoentity o mo) ordered
                                        according to route
                          pois          List of objects like poi where the route passes
                          xml           xml document with the route report. If no ask for a report it
                                        will be null

Example: Calculate a route and generate a report.

         function calcularRuta ()
         {
            var stopList=new Array();
            stopList[0]={ctc:'ESP17240300056757'};
            stopList[1]={ctc:'ESP17240332252624'};
            stopList[2]={ctc:'ESP47240300010809'};

              var routeParams={weight:'time',tolerance:5,mindist:'0',xml:true,
                  infoxml:1,fullsearch:false,lang:'es',poiwkt:false,reorder:false};
              var lineStyle={strokeWidth: 3, strokeColor: "#045FB4", fillOpacity: 0.2};
              var drawParadaMarkers=true;
              cercalia.calculateRoute(stopList,routeParams,lineStyle,
                  drawParadaMarkers, mostrarReporte);
         }

         function mostrarReporte(data)
         {
            if(data.error) {
              alert(data.error.errorText);
            } else {
              cercalia.createReport(data.xml,'div_ruta');
            }
}


             4.5.5         createReport(xml,idElement,xsl_name)
Use the xsl_name template (if it is not specified use the template defined in the
config.xml) to the xml that is passed by parameter and the result is added to the
element with id idElement of the html.

Example: Calculate a route and generate a report.

         function calcularRuta ()
         {
            var stopList=new Array();
            stopList[0]={ctc:'ESP17240300056757'};
            stopList[1]={ctc:'ESP17240332252624'};
            stopList[2]={ctc:'ESP47240300010809'};

              var routeParams={weight:'time',tolerance:5,mindist:'0',xml:true,
                  infoxml:1,fullsearch:false,lang:'es',poiwkt:false,reorder:false};
              var lineStyle={strokeWidth: 3, strokeColor: "#045FB4", fillOpacity: 0.2};
              var drawParadaMarkers=true;
              cercalia.calculateRoute(stopList,routeParams,lineStyle,
                  drawParadaMarkers, mostrarReporte);
         }


Joaquim Botet i Sisó, 6              Avinguda Meridiana, 216, 1ª   tel 902 102255                    34/47
17003 Girona                         08027 Barcelona               www.nexusgeografics.com
         function mostrarReporte(data)
         {
            if(data.error) {
              alert(data.error.errorText);
            } else {
              cercalia.createReport(data.xml,'div_ruta');
            }
}


             4.5.6        createMapImage(routeId,lineStyle,routeParams,execu
                          te, poicats)

Returns the URL where there is a map image with the current size. The map is
shown centred with respect to the route indicated by the parameter routeId. The
colour (in hexadecimal format) and width of the line of the route will be indicated in
the lineStyle parameter (*).
The routeParams parameter should show the weight and tolerance attributes with
which you wish to get the route.
The execute parameter corresponds to the function that will be executed once the
image has been obtained. This function receives the URL of the resulting image as a
parameter.

If it receives a zero routeId value, the map image is calculated with the current
extension and without a route. The lineStyle and routeParams parameters will be
omitted.

If a value is given to the poicats parameter (a chain of POI categories separated by
commas), the corresponding points of interest in the indicated categories will appear.
This parameter may be omitted.

(*) The map server applies a transparency layer so we recommend increasing the intensity of the colour. It may
also be recommendable to enter a line width greater than 4 pixels.

See the definitions of lineStyle and routeParams in the description of the calculateRoute function.



Example: Calculate a route and open a new window with the generated image.

         function calcularRuta ()
         {
           var stopList=new Array();
           stopList[0]={ctc:'ESP17240300056757'};
           stopList[1]={ctc:'ESP17240332252624'};
           stopList[2]={ctc:'ESP47240300010809'};

             var routeParams={weight:'time',tolerance:5,mindist:'0',xml:true,
               infoxml:1,fullsearch:false,lang:'es',poiwkt:false,reorder:false};
             var lineStyle={strokeWidth: 3, strokeColor: "#045FB4", fillOpacity: 0.2};
             var drawParadaMarkers=true;
             cercalia.calculateRoute(stopList,routeParams,lineStyle,
               drawParadaMarkers, mostrarImagen);
         }

         function mostrarImagen(data)
         {
           var routeParams={weight:'time',tolerance:5 };
           var lineStyle={strokeWidth: 5, strokeColor: “#045FB4”};

             cercalia.createMapImage(data.ruta.id,lineStyle,routeParams,verRuta);
         }
Joaquim Botet i Sisó, 6              Avinguda Meridiana, 216, 1ª         tel 902 102255                  35/47
17003 Girona                         08027 Barcelona                     www.nexusgeografics.com
         function verRuta(url)
         {
                  var w =window.open(       url,
                                            "Imprimir",
                                            "width=800,height=620,scrollbars=yes,resizable=yes,toolbar=no,loca
                                            tion=no,directories=no,titlebar=yes,status=no,menubar=no");
         }




             4.5.7        calculateMultiRoute(stopList, routeParams, execute)

Calculate optimum routes specified by the stopList parameter and it sens back the
different weight (distance, time, money).

Can be used to calculate the distance and time between n points of origin, several
crossing points, and n destinations. In this way, we can solve such questions as what
is the vehicle of a fleet that takes less time to go to collect some goods and carry it to
your destination calculating time and distance.

stopList parameter specifies the list of stops. The first list object specifies the origin
and the last one specifies the destination. Objects between origin and destination
specify the stops. Each element of the list may specify by means of:

    •    An object poi
    •    An object geoentity
    •    An object mo
    •    A list of objects mo
    •    A coordinate: {x:<x> ,y:<y>, srs:<srs>}
    •    A list of coordinates: [{x:<x> ,y:<y>, srs:<srs>},{x:<x> ,y:<y>, srs:<srs>}]
    •    A geoentity code. Ex: {cityId: ESP17240300056757 }
    •    Interest point code: {poiId: C17240332252905}

The first three can be a objects solved from a geocodificaton or proximity.

routeparams parameter specify a list of options for a route calculate:




    Campo                  Descripción
    weight                List of weight used by the route calculate. The first of them specifies
                          the weight to reduce from the origin to the first stop, the second specify
                          the weight to reduce from the first stop to the second one and so on.
                          If there isn’t enough values the last value will be repeat it for the rest of
                          the stops. We can also specify a single value and this will be applied by
                          all stages.
                          Valor              Idioma


Joaquim Botet i Sisó, 6           Avinguda Meridiana, 216, 1ª      tel 902 102255                        36/47
17003 Girona                      08027 Barcelona                  www.nexusgeografics.com
                            distance          Route is calculated by distance
                            time              Route is calculated by time
                            money             Route is calculated by Money
    intoll                  List of integer or integers. Each integer controls if the stop may find (or
                            not) on a stretch toll.
                            If it is -1 the stop always will find it out of stretch toll. If we specify a
                            positive number it will be allow that a stop will be in a stretch toll.
                            If the integers are finished the last one it uses to the rest of the stops.
                            For example: intoll=[-1] all the stops will be out of stretch tolls.
    net                     Specify the net to calculate routes. We must only specify in special
                            cases.
    xml                     Boolean that indicates if we want inform about the xml route report
                            (false by default)

execute parameter defines the function that will call when the route is solved by the
resultCalculteRoute type parameter.

resultCalculateRouteCosts format:

     Answer               Field        Description
    error                 error        Object type error (If there isn’t error then it contents null)
    rutas                 routes       List of objects route
                          xml          xml document with the route report. If no ask for a report it
                                       will be null


route format:

     Field            Description
    id                Route id
    distance          Total distance route (in meters)
    time              Total time in the next format: hh:mm:ss.
    weight            Weight for the route (distance, time, toll)
    stoplist          List of stops (type of poi, geoentity o mo) ordered
                      according to route



           4.5.8           transformCoordinates (objlist,srs)

This function transforms the coordinates within a candidate, poi or geoentity object
or list of objects to the indicated reference system

cercalia.transformCoordinates(resultGeocoding.candidates,”EPSG:4326”);




           4.5.9           coordToPixel(obj)

Returns the pixel of the image that corresponds to the specified coordinates. The

Joaquim Botet i Sisó, 6            Avinguda Meridiana, 216, 1ª    tel 902 102255                     37/47
17003 Girona                       08027 Barcelona                www.nexusgeografics.com
three attributes of the parameter must be specified (srs, x and y).

       Parameter:
       obj - {Object} Object with the structure {x:...,y:...,srs:...}


Example:

         var obj={x:-3.808951, y:43.458308, srs:"EPSG:4326"};
         var pixel=cercalia.coordToPixel(obj);



           4.5.10         coordToPixel(obj,srs)

Returns the pixel of the image that corresponds to the specified coordinates. You
must specify the coordinate system used or you will not get a result.

  Parameters:
  obj - {Object} OpenLayers.LonLat type object (see: http://www.openlayers.org)
  srs - {String} Coordinate system used


Example:

         var obj= new OpenLayers.LonLat(-3.808951, 43.458308);
         var pixel=cercalia.coordToPixel(obj,"EPSG:4326");




5 Map style

The Cercalia net servers provide different styles of base cartography for maps.
Consult Nexus Geografics to satisfy your needs. The API also allows the use of
cartography from other sources (google, yahoo, ICC, etc…)

5.1 getStyle()
Returns the code of the type of cartography that the base map is using.



5.2 createWMSStyle (name, url, params, options)
It creates a new style of background cartography with the dates of WMS server.

    Parameter                     Description
    name                          Name of the new style of cartography.
    url                           URL of WMS Server
    params                        Object Key/Value with the necessary parameters to realize a
                                  GETMAP query to WMS server. If no parameters are
                                  specified, they have a value by default:

Joaquim Botet i Sisó, 6          Avinguda Meridiana, 216, 1ª     tel 902 102255            38/47
17003 Girona                     08027 Barcelona                 www.nexusgeografics.com
                          service: "WMS"
                          version: "1.1.1"
                          request: "GetMap”
                          styles: ""
                          exceptions: "application/vnd.ogc.se_inimage"
                          format: "image/jpeg"

                          They are obligatories:

                          srs
                          layers

    options               Hash table with extra options to set layers.

                          opacity: real number between 0.0 and 1.0 that specify the
                          layer’s opacity. By default: opaque (1.0)
                          encodeBBOX: true to encode parameter BBOX value (the
                          WMS standard advice that it mustn’t encode). False by default.
                          gutter: number of pixels ignored around image. 0 by default.
                          scales: list of scales in descending order for the WMS server.
                          Null by default (whatever scale is allowed)
                          resolutions: list of resolutions in descending order. If we don’t
                          specify a resolution it will calculate according to the extension,
                          maximum resolution, maximum scale, etc.
                          maxResolution: Real that indicates the maximum resolution.
                          360 deg/256 px by default (= level 0 in google maps).
                          minResolution: Real that indicates minimum resolution.
                          numZoomLevels: Integer that indicates the number of zoom
                          levels..
                          minscale: Real that indicates the minimum scale.
                          maxscale: Real that indicates the maximum scale.
                          displayOutsideMaxExtent: boolean that indicates if we can
                          get a map although it is outside of the extension. False by
                          default.
                          maxExtent: Array with four values that it show the maximum
                          extension of cartography. The center of the map never will be
                          out of this rectangle. Forthermore, if dsplayOutsideMaxExtent is
                          activated we will not receive maps outside of the extension.
                          minExtent: Array with four values that it show the minimum
                          extensión of the cartography, in the Web Mar Service
                          projection.
                          It is necessary to indicate some of the scale options that we
                          have. We should choose “scales”.


Example to get an orto 50 m from ICC (Institut Cartogràfic de Catalunya)



Joaquim Botet i Sisó, 6   Avinguda Meridiana, 216, 1ª   tel 902 102255                  39/47
17003 Girona              08027 Barcelona               www.nexusgeografics.com
   var params = {'layers':'mtc50m,', 'format':'image/jpeg',
                 'exceptions':'application/vnd.ogc.se_xml', 'srs':"EPSG:23031"};
   var options = {'opacity':1};
   cercalia.createWMSStyle("wmsICC",
         "http://shagrat.icc.es/lizardtech/iserv/ows?VERSION=1.1.0&service=WMS",
         params,options);
   cercalia.setStyle("wmsICC");




Joaquim Botet i Sisó, 6   Avinguda Meridiana, 216, 1ª   tel 902 102255             40/47
17003 Girona              08027 Barcelona               www.nexusgeografics.com
6 Annex: Geocodification without a map

There is the possibility to realize geocodifications without having to initialize the map.

We have to load the “cercaliageo.js” file in the page wher we want use the function
with the following instruction:

                              <script type='text/javascript' src='cercaliageo.js'></script>

WARNING: The page with this reference it will only be able to use the
geocoding function from the API. The other functions will return error.

Before using the geocoding we must initialize the API. Initialization consists of
reading a properties file and call the constructor of the cercaliaclient passing the
object by parameter with the properties.

          properties=new cercaliaProperties("cercalia/config.xml");
          cercalia = new cercaliaClient(properties);

Now we just can call the geocoding function:

          var search={poicat:'C008',city:'Barcelona',countryId:'ESP',poiName:'Citroën',num:10,rad:2000};
          clone(search,ultimaGeo);
          cercalia.geocoding(search,retornoGeocoding);


Example:
<script type='text/javascript' src='cercaliageo.js'></script>

function createAll()
{

          properties=new cercaliaProperties("cercalia/config.xml");
          cercalia = new cercaliaClient(properties);
          geocodingPois();
}

function geocodingPois()
{
     var search={poicat:'C008',city:'Barcelona',countryId:'ESP',poiName:'Citroën',num:10,rad:2000};
     clone(search,ultimaGeo);
     cercalia.geocoding(search, returnGeocoding);
}

function returnGeocoding(dades)
{
     var cont=' ';
    document.getElementById('emergent').style.top='-2000';

          if(dades.error)alert("Error: "+dades.error.errorText);
                    else
                    {
                                if(dades.candidates!=null && dades.candidates.length>=1)
                                {
                                          var i=0;
                                          var body_candidates=document.getElementById('body_candidates');
                                          var tr=null;
                                          var td=null;
                                          var a=null;



Joaquim Botet i Sisó, 6                  Avinguda Meridiana, 216, 1ª         tel 902 102255                 41/47
17003 Girona                             08027 Barcelona                     www.nexusgeografics.com
                                         var num=dades.num;
                                         if(!num || num>dades.total)num=dades.total;


          while(body_candidates.firstChild)body_candidates.removeChild(body_candidates.firstChild);

                                         var total = dades.total;
                                         if(dades.num && dades.num<total) total = dades.num;
                                         var ncand = parseInt(dades.numCand);
                                         var poscand = dades.pos;

                                       if(total>10)//Paginaremos resultado
                                       {
                                                    var tr_paginar=document.getElementById('paginador');
             var td2 = document.createElement('TD');
                                                    var cont_td = "";
                                                    while(tr_paginar.firstChild)tr_paginar.removeChild(tr_paginar.firstChild);
                                                    td2 = document.createElement('TD');
                                                    for(i=0;i<total;i=i+ncand)
                                                    {
                     if(poscand==i)
                                                               {
                                                                           cont_td += "&nbsp;|&nbsp;<a href=\"#\" style=\"text-
decoration:none;\"><b>"+((i/ncand)+1)+"</b></a>";
                               }
                                                               else
                                                               {
                                                                           cont_td += "&nbsp;|&nbsp;<a
href=\"javascript:buscarCandPagina('"+i+"',this);\" style=\"text-decoration:underline;\" >"+((i/ncand)+1)+"</a>";
                                                               }
                                                               if(i==(total-1)) cont_td += "&nbsp;|&nbsp;";
                                                    }

             td2.innerHTML=cont_td;
             tr_paginar.appendChild(td2);

                                         }

                                         for(i=0;i< dades.candidates.length;i++)
                                         {
                                                    tr=document.createElement('TR');
                                                    td=document.createElement('TD');
                                                    a=document.createElement('A');
                                                    a.appendChild(document.createTextNode(dades.candidates[i].desc));
                                                    a.href="#";
                                                    a.className="opDemo";
                                                    td.appendChild(a);
                                                    tr.appendChild(td);
                                                    body_candidates.appendChild(tr);
                                         }

                                         document.getElementById('emergent').style.top='50%';

                               }
                               else
                               {
                                         alert("No se han encontrado datos.");
                               }
                    }
}

function buscarCandPagina(poscand)
{
          var search={};
          clone(ultimaGeo,search);
          search.posCand=poscand;
          cercalia.geocoding(search,retornFerGeocoding);
}




7 Annex: Coordinates systems


Joaquim Botet i Sisó, 6                 Avinguda Meridiana, 216, 1ª              tel 902 102255                                   42/47
17003 Girona                            08027 Barcelona                          www.nexusgeografics.com
Possible coordinates system values (srs parameter):

    Value                 Coordinates system
    EPSG:4326             WGS 84/ LonLat
    EPSG:23030            ED50 /UTM zone 30N
    EPSG:23031            ED50 /UTM zone 31N
    EPSG:23032            ED50 /UTM zone 32N
    EPSG:23033            ED50 /UTM zone 33N
    EPSG:32627            WGS 84 / UTM zone 27N
    EPSG:32628            WGS 84 / UTM zone 28N
    EPSG:32629            WGS 84 / UTM zone 29N
    EPSG:32630            WGS 84 / UTM zone 30N
    EPSG:32631            WGS 84 / UTM zone 31N
    EPSG:32632            WGS 84 / UTM zone 32N
    EPSG:32633            WGS 84 / UTM zone 33N
    EPSG:32634            WGS 84 / UTM zone 34N
    EPSG:32635            WGS 84 / UTM zone 35N
    EPSG:32636            WGS 84 / UTM zone 36N
    EPSG:32637            WGS 84 / UTM zone 37N
    EPSG:54004            WGS 84 / World Mercator
    EPSG:102014           Europe Lambert Conformal Conic
    EPSG:900913           Google




8 Annex: customclick buttons 1/2
customClick<n> are buttons from the toolbar designed so that when you select and
click a point on the map is made a custom action.

In the file configuration and in the same context where you declare the cercalia object
we must define the “menuCustomClick{n}, that it will execute when we click on the
map. This function will receive an object like OpenLayers.Event that it containts the
map pixel where we have already clicked.

You can check the OpenLayers API documentation to see the specifications of the
OpenLayers.Event objects (http://www.openlayers.org).



8.1.1         getCoordFromPixel(pixel,srs)

This function is designed to call within menuCustomclick<n> function. It returns an
OpenLayers.LonLat object that containts the coordinates in the reference system
indicated by the parameter srs from the pixel. The pixel parameter must be a
parameter like OpenLayers.Pixel. See examples of use in the previous section.

Example: send a message with the geographic coordinates of the clicked point.

function menuCustomClick1(e) {
       alert("coord EPSG:4326   "
              +cercalia.getCoordFromPixel(e.xy,"EPSG:4326"));
}
Joaquim Botet i Sisó, 6            Avinguda Meridiana, 216, 1ª   tel 902 102255            43/47
17003 Girona                       08027 Barcelona               www.nexusgeografics.com
Example: send a message with Mercator coordinates of the clicked point.

function menuCustomClick1(e) {
       alert("coord EPSG:54004   "
              +cercalia.getCoordFromPixel(e.xy,"EPSG:54004"));
}




9 Annex: Editing tools
This annex explains how the               (draw) tool works, as well as how it interacts with the
methods for handling features.

In general, this tool allows you to draw features on the map with a personalized style
(colours, line style, etc.). Once these features have been created you can consult
information on them through the getFeatures and getFeaturesByState methods
described in this manual.
It also allows you to edit and therefore modify (edit vertices, rotate, move and
eliminate) the features created on the map with the createFeature function.

The following picture shows the utilities menu that opens up when you activate the
tool:


                                                            a)   Draw points
                                                            b)   Draw lines
                                                            c)   Draw polygons
                                                            d)   Draw circles
            a             b       c           d             e)   Edit vertices
                                                            f)   Scale feature
                                                            g)   Move feature
        e        f        g   h       i        j            h)   Rotate feature
                                                            i)   Eliminate feature
                                                            j)   Eliminate all features



The tool works quite intuitively. Its utility is activated each time you click on one of the
buttons. Therefore, when the map receives events from the mouse it will execute one
action or another, depending on the button activated.
In the case of option “j”, the utility does not remained activated but simply proceeds
to eliminate all the features created on the map (with the tool and/or createFeature
function).

When you activate one of the a, b, c or d utilities, the feature style personalization
options are shown. For example, in the case of d:




Joaquim Botet i Sisó, 6       Avinguda Meridiana, 216, 1ª           tel 902 102255            44/47
17003 Girona                  08027 Barcelona                       www.nexusgeografics.com
For these options to be applied, when you draw the figures on the map you have to
click on “APPLY” once the desired configuration has been selected.


a) Draw points
This utility allows you to draw points and personalize their size and colour.

b) Draw lines
This utility allows you to draw lines and personalize their size, colour and style
(continuous, broken, dotted, etc.).

c) Draw polygons
This utility allows you to draw polygons and personalize the colour and thickness of
the line, background colour, transparency and line style.

d) Draw circles
This utility allows you to draw personalized regular or irregular circles with colour and
line width, background colour, transparency and line style.

e) Edit vertices
This utility allows you to edit the vertices of your figures in order to modify your
feature.
If the figure has been created with the createFeature function, its condition will be
modified.

f) Scale feature
This utility allows you to modify the size of your figures.
If the figure has been created with the createFeature function, its condition will be
modified.

g) Move feature
This utility allows you to move your figures on the map.
If the figure has been created with the createFeature function, its condition will be
modified.

h) Rotate feature
This utility allows you to rotate your figures.
If the figure has been created with the createFeature function, its condition will be
modified.

i) Eliminate feature
This utility allows you to eliminate one or various selected features, both created with
the a, b, c and d utilities and resulting from the createFeature function. It requests
confirmation before carrying out the action.
The eliminated figures created with the createFeature function are stored in an
Joaquim Botet i Sisó, 6    Avinguda Meridiana, 216, 1ª   tel 902 102255              45/47
17003 Girona               08027 Barcelona               www.nexusgeografics.com
internal structure and their geometric information can be recovered using the
getFeatureByState method with the deleted parameter set at true and the others at
false.

j) Eliminate all the features
This utility allows you to eliminate all the figures on the map (those created with the
a, b, c and d utilities and those resulting from the createFeature function). It requests
confirmation before carrying out the action.
The eliminated figures created with the createFeature function are stored in an
internal structure and their geometric information can be recovered using the
getFeatureByState method with the deleted parameter set at true and the others at
false.

To eliminate all the figures permanently, use the deleteFeatures function explained in
the manual.

10 Annex: difference between version 1 and 2

This annex summarises the changes that have been made with respect to the first
version of the API and some steps are explained in order to enable you to migrate
projects started with the first version.

    •    Tolerance of crashed or inaccessible net servers has been incorporated. Now
        the initialisation script detects whether the net server it’s connecting to has
        crashed and it tries connecting to another.

    •    The possibility of clients communicating with a proxy servlet has been added.
        The proxy contains the distributor’s key and if this option is used domain
        access control in the Cercalia net server is not necessary.

    •    The Cercalia object initialisation code has been simplified. It is no longer
        necessary to define the barralat, foramapa, mapa div’s. The API will build
        them automatically

    •    The format of the XML configuration file has been modified so that it has
        clearer identifiers and new options have been added. The following table shows
        the equivalences between the parameters of the first version and the new
        version. See the section where the configuration file format is explained to see
        the valid values of each parameter.


                          Previous version (1.x)            Current version (2.0)
                          client                            client
                          initial_zoom                      map_zoom_level
                          menu_options                      panel_pages
                          buscar                            geocoding
                          proximidad                        proximity
                          rutas                             route
                          menu_initial                      panel_pages
                          barralat_visible                  panel_status

Joaquim Botet i Sisó, 6       Avinguda Meridiana, 216, 1ª         tel 902 102255            46/47
17003 Girona                  08027 Barcelona                     www.nexusgeografics.com
                          barralat_maxim                   panel_status
                          zoombar_visible                  zoombar_status
                          overview_map_maxim               overview_map_status
                          panel_options                    toolbar_tools
                          language                         language
                          cart_layer                       map_style
                          zoombar_small                    zoombar_status
                          overview_map_visible             overview_map_status
                          extent                           map_extent


    •    The gotoPoiCode function has been replaced with the getPoi function. This
        function returns all the data from one or more points of interest, but unlike the
        previous version, it does not create markers, nor does it centre the map on
        them.

    •    The pois function has been replaced with the showPois function. Unlike in the
        previous version, only the points of interest whose status we want to change
        are passed. Those categories which are not specified will maintain their
        previous status.

    •    The activateTool function has been added to enable the selection of the
        activated tool code.

    •    The transformCoordinates method has been added which transforms the
        coordinates of a list of candidates, points of interest or geoentities to the
        coordinates system specified.

    •    The createMarkers method has been added which allows the creation of
        geocoding, proximity, etc.., response markers.

    •    The moveMarker method has been modified adding an optional parameter to
        change the marker’s popup content dynamically. Now the moveMarker
        function can be used to refresh the status of a marker periodically and
        dynamically without the loss of memory in the browser.

    •    Possibility of working with Google Maps cartography. The setStyle method
        has been added to change from one style of cartography to another (cercalia
        and Google Maps styles - streets, satellite, hybrid –). A default cartography
        may also be indicated in the map_style parameter of the configuration file.
        According to the value of this parameter one style of cartography or another will
        be viewed when loading the page.

    •    The methods which appear in the current API allow the use of all the previous
        version’s functionalities. The functions which are not in the manual have been
        eliminated or will not be available to new clients. For example, the proximity
        function indicating coordinates can be used instead of the previous
        inverseGeocoding function.




Joaquim Botet i Sisó, 6      Avinguda Meridiana, 216, 1ª        tel 902 102255            47/47
17003 Girona                 08027 Barcelona                    www.nexusgeografics.com

								
To top