openlayers/lib/OpenLayers/Layer/MapServer.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
   2  * license.  See http://svn.openlayers.org/trunk/openlayers/license.txt for the
   3  * full text of the license. */
   4
   5 /**
   6  * @requires OpenLayers/Layer/Grid.js
   7  */
   8
   9 /**
  10  * Class: OpenLayers.Layer.MapServer
  11  * Instances of OpenLayers.Layer.MapServer are used to display
  12  * data from a MapServer CGI instance.
  13  *
  14  * Inherits from:
  15  *  - <OpenLayers.Layer.Grid>
  16  */
  17 OpenLayers.Layer.MapServer = OpenLayers.Class(OpenLayers.Layer.Grid, {
  18
  19     /**
  20      * Constant: DEFAULT_PARAMS
  21      * {Object} Hashtable of default parameter key/value pairs
  22      */
  23     DEFAULT_PARAMS: {
  24         mode: "map",
  25         map_imagetype: "png"
  26     },
  27
  28     /**
  29      * Constructor: OpenLayers.Layer.MapServer
  30      * Create a new MapServer layer object
  31      *
  32      * Parameters:
  33      * name - {String} A name for the layer
  34      * url - {String} Base url for the MapServer CGI
  35      *       (e.g. http://www2.dmsolutions.ca/cgi-bin/mapserv)
  36      * params - {Object} An object with key/value pairs representing the
  37      *          GetMap query string parameters and parameter values.
  38      * options - {Ojbect} Hashtable of extra options to tag onto the layer
  39      */
  40     initialize: function(name, url, params, options) {
  41         var newArguments = [];
  42         newArguments.push(name, url, params, options);
  43         OpenLayers.Layer.Grid.prototype.initialize.apply(this, newArguments);
  44
  45         this.params = OpenLayers.Util.applyDefaults(
  46             this.params, this.DEFAULT_PARAMS
  47         );
  48
  49         // unless explicitly set in options, if the layer is transparent,
  50         // it will be an overlay
  51         if (options == null || options.isBaseLayer == null) {
  52             this.isBaseLayer = ((this.params.transparent != "true") &&
  53                                 (this.params.transparent != true));
  54         }
  55     },
  56
  57     /**
  58      * Method: clone
  59      * Create a clone of this layer
  60      *
  61      * Returns:
  62      * {<OpenLayers.Layer.MapServer>} An exact clone of this layer
  63      */
  64     clone: function (obj) {
  65         if (obj == null) {
  66             obj = new OpenLayers.Layer.MapServer(this.name,
  67                                            this.url,
  68                                            this.params,
  69                                            this.options);
  70         }
  71         //get all additions from superclasses
  72         obj = OpenLayers.Layer.Grid.prototype.clone.apply(this, [obj]);
  73
  74         // copy/set any non-init, non-simple values here
  75
  76         return obj;
  77     },
  78
  79     /**
  80      * Method: addTile
  81      * Creates a tile, initializes it, and adds it to the layer div.
  82      *
  83      * Parameters:
  84      * bounds - {<OpenLayers.Bounds>}
  85      * position - {<OpenLayers.Pixel>}
  86      *
  87      * Returns:
  88      * {<OpenLayers.Tile.Image>} The added OpenLayers.Tile.Image
  89      */
  90     addTile:function(bounds,position) {
  91         return new OpenLayers.Tile.Image(this, position, bounds,
  92                                          null, this.tileSize);
  93     },
  94
  95     /**
  96      * Method: getURL
  97      * Return a query string for this layer
  98      *
  99      * Parameters:
 100      * bounds - {<OpenLayers.Bounds>} A bounds representing the bbox
 101      *                                for the request
 102      *
 103      * Returns:
 104      * {String} A string with the layer's url and parameters and also
 105      *          the passed-in bounds and appropriate tile size specified
 106      *          as parameters.
 107      */
 108     getURL: function (bounds) {
 109         bounds = this.adjustBounds(bounds);
 110         // Make a list, so that getFullRequestString uses literal ","
 111         var extent = [bounds.left, bounds. bottom, bounds.right, bounds.top];
 112
 113         var imageSize = this.getImageSize();
 114
 115         // make lists, so that literal ','s are used
 116         var url = this.getFullRequestString(
 117                      {mapext:   extent,
 118                       imgext:   extent,
 119                       map_size: [imageSize.w, imageSize.h],
 120                       imgx:     imageSize.w / 2,
 121                       imgy:     imageSize.h / 2,
 122                       imgxy:    [imageSize.w, imageSize.h]
 123                       });
 124
 125         return url;
 126     },
 127
 128     /**
 129      * Method: getFullRequestString
 130      * combine the layer's url with its params and these newParams.
 131      *
 132      * Parameter:
 133      * newParams - {Object} New parameters that should be added to the
 134      *                      request string.
 135      * altUrl - {String} (optional) Replace the URL in the full request
 136      *                              string with the provided URL.
 137      *
 138      * Returns:
 139      * {String} A string with the layer's url and parameters embedded in it.
 140      */
 141     getFullRequestString:function(newParams, altUrl) {
 142         // use layer's url unless altUrl passed in
 143         var url = (altUrl == null) ? this.url : altUrl;
 144
 145         // create a new params hashtable with all the layer params and the
 146         // new params together. then convert to string
 147         var allParams = OpenLayers.Util.extend({}, this.params);
 148         allParams = OpenLayers.Util.extend(allParams, newParams);
 149         var paramsString = OpenLayers.Util.getParameterString(allParams);
 150
 151         // if url is not a string, it should be an array of strings,
 152         // in which case we will deterministically select one of them in
 153         // order to evenly distribute requests to different urls.
 154         if (url instanceof Array) {
 155             url = this.selectUrl(paramsString, url);
 156         }
 157
 158         // ignore parameters that are already in the url search string
 159         var urlParams = OpenLayers.Util.upperCaseObject(
 160                             OpenLayers.Util.getParameters(url));
 161         for(var key in allParams) {
 162             if(key.toUpperCase() in urlParams) {
 163                 delete allParams[key];
 164             }
 165         }
 166         paramsString = OpenLayers.Util.getParameterString(allParams);
 167
 168         // requestString always starts with url
 169         var requestString = url;
 170
 171         // MapServer needs '+' seperating things like bounds/height/width.
 172         //   Since typically this is URL encoded, we use a slight hack: we
 173         //  depend on the list-like functionality of getParameterString to
 174         //  leave ',' only in the case of list items (since otherwise it is
 175         //  encoded) then do a regular expression replace on the , characters
 176         //  to '+'
 177         //
 178         paramsString = paramsString.replace(/,/g, "+");
 179
 180         if (paramsString != "") {
 181             var lastServerChar = url.charAt(url.length - 1);
 182             if ((lastServerChar == "&") || (lastServerChar == "?")) {
 183                 requestString += paramsString;
 184             } else {
 185                 if (url.indexOf('?') == -1) {
 186                     //serverPath has no ? -- add one
 187                     requestString += '?' + paramsString;
 188                 } else {
 189                     //serverPath contains ?, so must already have paramsString at the end
 190                     requestString += '&' + paramsString;
 191                 }
 192             }
 193         }
 194         return requestString;
 195     },
 196
 197     CLASS_NAME: "OpenLayers.Layer.MapServer"
 198 });