2. GSMap Object

2.1. Example HTML Code

The following minimal skeleton code shows the basic structure of an GSAPI application:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html>
    <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>infoGrips GeoShop GSAPI Example</title>

    <script type="text/JavaScript">
(3)    function GSAPIInitializedCallback() {

          // check browser
          if (!GSBrowserCheck()) return;

          // create user object GSUser
          var user = new GSUser();
          
          user.login(<USER>,<PASSWORD>, function() {
                // create map object GSMap
                var map = new GSMap("map");

                // set user for authentification of GSMap functions
                map.setUser(user);

                // add zoom controls to GSMap
                var zctrl = new GSMapZoomSliderControl();
                zctrl.setSliderResolution(<MINRES>,<MAXRES>.<STEPS>,<ACTSTEP>);
                map.addZoomControl(zctrl);

                // add tools to GSMap
                var tools = new GSMapTools();
                tools.addInfoTool();
                tools.setInfoToolHandler(MyInfoToolHandler);
                tools.addSelectionTool();
                tools.setSelectionToolHandler(MySelectionToolHandler);
                map.addTools(tools);

                // display data in the map with a given center
                map.setCenter(<X-COORD>,<Y-COORD>);
          }, function(errorMessage) {
             alert(errorMessage);
          });
       }
    </script>
(1) <script type="text/javascript" src="<SERVER-URL>/gsapi2/gsapi.js"></script>
(2) <script type="text/JavaScript">
        function MyInfoToolHandler(objects){
           // user handler funcion for InfoTool events
        }
        function MySelectionToolHandler(objects){
           // user handler function for SelectionTool events
        }
    </script>
    </head>
    <body>
(4)    <DIV id="map" style="position:absolute; width:500px; height:300px; 
                            background-color: #CCCCCC; left: 100px; top: 100px;"> 
       </DIV>
    </body>
    </html>

Description:

  1. To use the GSAPI the JavaScript library gsapi.js has to be included in the HTML page. The library is loaded from the GeoShop Server at <SERVER-URL>. If the GSAPI resides on the same server as the main page, the path can be set relativ to the main page,

  2. The user can specify handler functions to handle InfoTool or SelectionTool events.

  3. The JavaScript-function GSAPIInitializedCallback() is called after the necessary Javascript-Files for the GSAPI are loaded. In this example it creates the Map object and initializes the GUI controls.

  4. The HTML DIV element determines the size and position of the GSMap object in the HTML page.

2.2. GSMap Methods

ConstructorGSMap(String divid)
DescriptionCreates a new GSMap object. The divid argument has to correspond to the id= of a DIV-element on the HTML page.
Example
var map = new GSMap("map");
MethodsetServer(String server)
DescriptionSets the GeoShop Server which delivers the data for the map. If the GeoShop Server has the same location as the map html, the server must not be set.
Example
map.setServer("http://www.myserver.com");
MethodsetIconUrl(String url)
DescriptionSets the url for the icons of the map. If the icons of the GSAPI are used, the icon url has not to be defined. More about the icons see later.
Example
map.setIconUrl("http://www.myserver.com/icons");
MethodsetIconExtension(String extension)
DescriptionSets the extension for the icons of the map. If the icons of the GSAPI are used, the icon extension has not to be defined. More about the icons see later.
Example
map.setIconExtension("gif");
MethodsetUser(String user,String password)
DescriptionSets the map object to a certain GeoShop user/password. The user must exist on the GeoShop server and must have privileges to access maps.
Example
map.setUser("test","test");
MethodsetLanguage(String language)
DescriptionSets the language of the map. For example for the tooltips. Valid value: EN,DE,FR,IT.
Example
map.setLanguage("DE");
MethodString getLanguage()
DescriptionDelivers the language of the map.
Example
var language = map.getLanguage();
MethodsetTileSize(Integer tilesize)
DescriptionSets the size of the tiles of the map.
Example
map.setTileSize(300);
MethodInteger getTileSize()
DescriptionDelivers the size of the tiles of the map.
Example
var tilesize = map.getTileSize();
MethodsetTileBorder(Boolean status)
DescriptionDisplays a border around each tile of the map. Can be used to see the tiles to find the best size of the tiles.
Example
map.setTileBorder(true);
MethodBoolean getTileBorder()
DescriptionDelivers the tile border setting.
Example
var border = map.getTileBorder();
MethodsetTileBackgroundColor(String color)
DescriptionSets the background color of the tiles while the image is loaded and is not displayed already. The value of the color must be set as a RGB-HTML hexadecimal value like #RRGGBB. RR=red, GG=green,BB=blue, i.e. #FF0000 for the color red.
Example
map.setTileBackgroundColor("#FFFFFF");
MethodString getTileBackgroundColor()
DescriptionDelivers the background color of the tiles.
Example
var color = map.getTileBackgroundColor();
MethodsetTileResetMode(Boolean status)
DescriptionSets the tile reset mode. By default this mode is activ. If this mode is activ, for each command zoom in, zoom out, query, selection or info the raster of the tiles for the view is reseted. This mode makes only sense if the size of the tiles is bigger than the size of the map. In this case this mode causes that only one image has to be loaded. If the size of the tiles is smaller than the size of the map this mode should be deactivated.
Example
map.setTileResetMode(false);
MethodBoolean getTileResetMode()
DescriptionDelivers if the tile reset mode is activated or not activated.
Example
var mode = map.getTileResetMode();
MethodsetPanAccelerationMode(Boolean status)
DescriptionSets the pan acceleration mode. By default this mode is not activ. If this mode is activ, if you pan - mouse down and move - and the mouse goes up while moving, the map keeps moving for a while.
Example
map.setPanAccelerationMode(true);
MethodBoolean getPanAccelerationMode()
DescriptionDelivers if the tile reset mode is activated or not activated.
Example
var mode = map.getPanAccelerationMode();
MethodsetView(String view)
DescriptionDisplays a GeoShop view in the map component. Without setView() the default view of the user is displayed. The user needs to have enough privileges to access to the GeoShop view.
Example
map.setView("av");
MethodString getView()
DescriptionDelivers the view of the map.
Example
var view = map.getView();
MethodsetZoomFactor(Float zoomfactor)
DescriptionSets the zoom factor for zoom in and zoom out. A zoom factor of 2.0 doubles the range of the map by a zoom out. A zoom factor of 2.0 halves the range of the map by a zoom in. If a zoom control object of type GSMapZoomSliderControl is set, the zoom factor is given by the the zoom control object.
Example
map.setZoomFactor(2.0);
MethodFloat getZoomFactor()
DescriptionDelivers the zoom factor of the map.
Example
var factor = map.getZoomFactor();
MethodsetZoomMoveFactor(Float zoommovefactor)
DescriptionSets the zoom move factor for zoom up, down, left and right of the map. A zoom factor of 0.25 moves the range of the map by a factor of 0.25 of the height or the width.
Example
map.setZoomMoveFactor(0.25);
MethodFloat getZoomMoveFactor()
DescriptionDelivers the zoom move factor of the map
Example
var factor = map.getZoomMoveFactor();
MethodsetResolution(Float resolution)
DescriptionSets the resolution of the map. The resolution determines the size of the displayed area. Resolution is specified in meter / pixel. Larger values display larger areas, whereas smaller values display smaller areas. If a zoom control object of type GSMapZoomSliderControl is set, the resolution is adjusted to a valid resolution of the zoom control object.
Example
map.setResolution(0.1);
MethodFloat getResolution()
DescriptionDelivers the actual resolution of the map.
Example
var r = map.getResolution();
MethodsetCenter(Float x, Float y)
DescriptionCenters the map view around a given x/y coordinate. This function causes to update the data in the the map.
Example
map.setCenter(600000.0,20000.0);
MethodFloat getCenterX()
DescriptionDelivers the actual center x coordinate of the map.
Example
var x = map.getCenterX();
MethodFloat getCenterY()
DescriptionDelivers the actual center y coordinate of the map.
Example
var y = map.getCenterY();
MethodsetRange(Float minx, Float miny, Float maxx, Float maxy)
DescriptionPositions the map between minx/miny and maxx/maxy. This function causes to update the data in the the map.
Example
map.setRange(600000.0,200000,650000.0,250000.0);
MethodFloat getRangeMinX()
DescriptionDelivers the X-coordinate of the left side of the map.
Example
var minx=map.getRangeMinX();
MethodFloat getRangeMinY()
DescriptionDelivers the Y-coordinate of the lower side of the map.
Example
var miny=map.getRangeMinY();
MethodFloat getRangeMaxX()
DescriptionDelivers the X-coordinate of the right side of the map.
Example
var maxx=map.getRangeMaxX();
MethodFloat getRangeMaxY()
DescriptionDelivers the Y-coordinate of the upper side of the map.
Example
var maxy=map.getRangeMaxY();
MethodzoomUp()
DescriptionMoves the range of the map up by the zoom move factor. This function causes to update the data in the the map.
Example
map.zoomUp();
MethodzoomDown()
DescriptionMoves the range of the map down by the zoom move factor. This function causes to update the data in the the map.
Example
map.zoomDown();
MethodzoomLeft()
DescriptionMoves the range of the map left by the zoom move factor. This function causes to update the data in the the map.
Example
map.zoomLeft();
MethodzoomRight()
DescriptionMoves the range of the map right by the zoom move factor. This function causes to update the data in the the map.
Example
map.zoomRight();
MethodzoomInCenter()
DescriptionZooms in at the center of the map by the zoom factor. This function causes to update the data in the the map.
Example
map.zoomInCenter();
MethodzoomOutCenter()
DescriptionZooms out at the center of the map by the zoom factor. This function causes to update the data in the the map.
Example
map.zoomOutCenter();
MethodFloat update()
DescriptionUpdates the data in the map with the actual settings. Can be used if properties are changed which do not update the map it selves.
Example
map.update();
MethodaddZoomControl(GSMapZoomSliderControl zoomcontrol)
DescriptionAdds a zoom control object to the map object (i.e. zoom in, zoom out, etc.).
Example
map.addZoomControl(new GSMapZoomSliderControl());
MethodsendQuery(String query,String arguments, function successCallback(Boolean), function errorCallback(String))
DescriptionSends a query to the GeoShop server. The arguments have to be submitted in the same format as in WebClient function image2, i.e. "gemeinde=Bern&nummer=500". If objects are found successCallback() is called asynchronously with true else with false. Found objects are displayed in center of the GSMap object.
Example
map.sendQuery("parzelle","gemeinde=Bern&nummer=500", function(found) {
      if (found) {
         // object found
      }
      else {
         // no object found 
      };
   }, function(errorMessage) {
      // some error occured
   }
);
MethodresetQuery()
DescriptionResets the query result. The highlighted object is not highlighted anymore.
Example
map.resetQuery();
MethodplaceSelectionBox()
DescriptionStarts the placement of a selection box. The user can digitize the box by clicking into the map (2 points).
Example
map.placeSelectionBox();
MethodplaceSelectionPolygon()
DescriptionStarts the placement of a selection polygon. The user can digitize the polygon by clicking into the map. A double click closes the polygon.
Example
map.placeSelectionPolygon();
MethodGSPolygon getSelectionPolygon()
DescriptionReturns the recently digitized selection polygon or null if no selection polygon exists. The selection polygon can be used as GSOrder parameter.
Example
var selection = map.getSelectionPolygon();
MethodclearSelectionPolygon();
DescriptionClears the selection polygon.
Example
map.clearSelectionPolygon();
MethodgetInfo(Float x, Float y, String classes, function successCallback(Array), function errorCallback(String))
DescriptionReturns asynchronously an array of objects in successCallback() for the point x, y and the selected classes. See GSMapTools.setInfoToolClasses how to use the argument classes. See GSMapTools.setInfoToolHandler how to process the returned array of objects.
Example
map.getInfo(675500.000,245500.000,"*", function(objects) {
      // display object information
   }, function(errorMessage) {
      // some error occured
   }
);
MethodsetInfoSize(Float size)
DescriptionBy default the method getInfo returns only objects which are within the range of the actual map and where Information is available for the selected size of the map . That means x, y must be within getRangeMinX/Y() and getRangeMaxX/Y() and the Information must be available for this size . With this method the size can be set by the size for a side of a square and the point x,y for the method getInfo must not be within an actual map.
Example
map.setInfoSize(100.0);
MethodresetInfo()
DescriptionResets the getInfo method so that no objects are selected and the method setInfoSize is reset to the default behaviour.
Example
map.resetInfo();
MethodgetSelection(Float x, Float y, String classes, function successCallback(Array), function errorCallback(String))
DescriptionReturns asynchronously an array of objects in successCallback() for the point x, y and the selected classes. See GSMapTools.setInfoToolClasses how to use the argument classes. See GSMapTools.setInfoToolHandler how to process the returned array of objects. If a new selection should be started, the method resetSelection() should be called first to reset the array of objects. Repeating calls of getSelection with other points x.y add the new found objects to the existing array of objetcs. If an already selected object is selected by another call of the method again, the object is removed (deselected) from the array of objects.
Example
map.getSelection(675500.000,245500.000,"*", function(objects) {
      // do something with objects
   }, function(errorMessage) {
      // some error occured
   }
);
MethodsetSelectionSize(Float distance)
DescriptionBy default the method getSelection returns only objects which are within the range of the actual map and where Information is available for the selected size of the map . That means x, y must be within getRangeMinX/Y() and getRangeMaxX/Y() and the Information must be available for this size . With this method the size can be set by the size for a side of a square and the point x,y for the method getSelection must not be within an actual map.
Example
map.setSelectionSize(100.0);
MethodsetSelectionDeselection(Boolean status)
DescriptionThe possibility of a deselection of selected objects can be switched off by the call of map.setSelectionDeselection(false). A once selected objects stays selected.
Example
map.setSelectionDeselection(false);
MethodresetSelection()
DescriptionResets the getSelection method so that no objects are selected and the method setSelectionSize is reset to the default behaviour.
Example
map.resetSelection();

2.3. GSMapZoomSliderControl Methods

ConstructorGSMapZoomSliderControl()
DescriptionCreates a new GSMapZoomSliderControl object. The GSMapZoomSliderControl is represented on the map like the zoom control in Google maps.
Example
var zctrl = new GSMapZoomSliderControl();
MethodsetSliderResolution(Float minresolution, Float maxresolution, int steps, int actstep)
DescriptionSets the resolution range of the zoom slider. Sets the steps between minresolution and maxresolution and the actual step to display. Resolution values are specified in meter / pixel units.
Example
zctrl.setSliderResolution(1.0,1000.0, 20, 10);
MethodsetZoomDoubleClicktoCenter(Boolean status)
DescriptionIf true a double click of left/right button sets the point of the mouse to the center and zooms in/out. If false a double click of left/right button zooms in/out around the point of the mouse. Default is false .
Example
zctrl.setZoomDoubleClicktoCenter(true)

The Object GSMapZoomSliderControl uses icons for the user interface. Self designed icons can be used. The url for the icons has to be set with the method GSMap.setIconUrl(<url>). The Extension for the icons has to be set with the method GSMap.setIconExtension(<extension>). Possible icons are:

Icon nameslidercontrol.gif
Size54x54
DescriptionIs the Icon with the zoom left, right, top, down and back elements. The size of the icons is divided into a 3x3 matrix. The fields of the matrix are used like: [0,1]=zoom up, [1,0]=zoom left, [1,1]=zoom back, [1,2]=zoom right, [2,1]=zoom down.
Icon namesliderzoomin.gif
Size24x24
DescriptionIs the Icon for the zoom in button.
Icon namesliderzoomout.gif
Size24x24
DescriptionIs the Icon for the zoom out button.
Icon namesliderbar.gif
Size12x272
DescriptionIs the Icon for slider bar.
Icon namesliderpoint.gif
Size6x6
DescriptionIs the Icon for the points on the slider bar which indicates the steps on the slider bar.
Icon namesliderpusher.gif
Size18x12
DescriptionIs the Icon for the slider pusher, which can be moved on the slider bar to changed the zoom factor.

2.4. GSMapTools Methods

ConstructorGSMapTools()
DescriptionCreates a new GSMapTools object. The GSMapTools object is represented in the map as a set of icon buttons (info button, selection button).
Example
var tools = new GSMapTools();
MethodaddInfoTool()
DescriptionCreates an info tool in the tool box. After pressing the InfoTool button, objects are selected by clicking on the map. The InfoTool button changes color to indicate, that the Map is in selection mode. Selected objects are highlighted in the map.When info is finished the user has to click on the infoTool button again. The queried results are sent as an array of objects to the info tool handler function for further processing. Each new selection clears the existing array of objects and adds the new objects. Note: Not needed by EGRIS application.
Example
tools.addInfoTool();
MethodsetInfoToolHandler(Function myfunction)
DescriptionSets the info tool handler function. This function is a user function which handles the selected objects. The function is called each time an object is selected. The function receives the objects as an array of objects. Each object contains the attributes of the object.
Example
tools.setInfoToolHandler(myfunction);
:
function myfunction (objects)
{
   if (objects == null) return;

   alert("Objects found:" + objects.length);
 
   for (i=0;i<objects.length;i++) {
      o = objects[i];

      message = 'Object '+ (i+1) + ':\n'
      for (a in o) message = message + a + '=' + o[a] + '\n';

      alert(message);
   }
}
MethodsetInfoToolClasses(String myclasses)
DescriptionSets the info tool classes. Only objects of the classes are returned by a selection. The classes must be available in the actual view of the map. To define a single class, call the function with a single class. To define multiple classes, call the function with the classes separated by commas. To define all classes, call the function with "*" .
Example
tools.setInfoToolClasses("Abwasser,Wasser");
MethodaddSelectionTool()
DescriptionCreates a selection tool for a given layer in the tool box. After pressing the SelectionTool button, objects are selected by clicking on the map. The SelectionTool button changes color to indicate, that the Map is in selection mode. Selected objects are highlighted in the map. When selection is finished the user has to click on the SelectionTool button again. Each time the user selects an object, all selected objects are sent as an array of objects to the selection tool handler function for further processing.
Example
tools.addSelectionTool();
MethodsetSelectionToolHandler(Function myfunction)
DescriptionSets the selection tool handler function. This function is a user function which handles the selected objects. The function is called each time an object is selected. The function receives the objects as an array of objects. Each object contains the attributes of the object.
Example
tools.setSelectionToolHandler(myfunction);
:
function myfunction (objects)
{
   // see also setInfoToolHandler 
}
MethodsetSelectionToolClasses(String myclasses)
DescriptionSets the selection tool classes. Only objects of the classes are returned by a selection. The classes must be available in the actual view of the map. To define a single class, call the function with a single class. To define multiple classes, call the function with the classes separated by commas. To define all classes, call the function with "*" .
Example
tools.setSelectionToolClasses("Parzelle");

The Object GSMapTools uses icons for the user interface. Self designed icons can be used. The url for the icons has to be set with the method GSMap.setIconUrl(<url>) . The Extension for the icons has to be set with the method GSMap.setIconExtension(<extension>). Possible icons are:

Icon nameinfo1.gif, info2.gif
Size24x24
DescriptionIs the Icon for the Info Button. Not selected state: info1.gif . Selected state: info2.gif .
Icon nameselection1.gif, selection2.gif
Size24x24
DescriptionIs the Icon for the Selection Button. Not selected state: selection1.gif . Selected state: selection2.gif .