openlayers/lib/OpenLayers/Layer/WMS.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 /**
   7  * @requires OpenLayers/Layer/Grid.js
   8  * @requires OpenLayers/Tile/Image.js
   9  */
  10
  11 /**
  12  * Class: OpenLayers.Layer.WMS
  13  * Instances of OpenLayers.Layer.WMS are used to display data from OGC Web
  14  *     Mapping Services. Create a new WMS layer with the <OpenLayers.Layer.WMS>
  15  *     constructor.
  16  *
  17  * Inherits from:
  18  *  - <OpenLayers.Layer.Grid>
  19  */
  20 OpenLayers.Layer.WMS = OpenLayers.Class(OpenLayers.Layer.Grid, {
  21
  22     /**
  23      * Constant: DEFAULT_PARAMS
  24      * {Object} Hashtable of default parameter key/value pairs
  25      */
  26     DEFAULT_PARAMS: { service: "WMS",
  27                       version: "1.1.1",
  28                       request: "GetMap",
  29                       styles: "",
  30                       exceptions: "application/vnd.ogc.se_inimage",
  31                       format: "image/jpeg"
  32                      },
  33
  34     /**
  35      * Property: reproject
  36      * *Deprecated*. See http://trac.openlayers.org/wiki/SphericalMercator
  37      * for information on the replacement for this functionality.
  38      * {Boolean} Try to reproject this layer if its coordinate reference system
  39      *           is different than that of the base layer.  Default is true.
  40      *           Set this in the layer options.  Should be set to false in
  41      *           most cases.
  42      */
  43     reproject: false,
  44
  45     /**
  46      * APIProperty: isBaseLayer
  47      * {Boolean} Default is true for WMS layer
  48      */
  49     isBaseLayer: true,
  50
  51     /**
  52      * APIProperty: encodeBBOX
  53      * {Boolean} Should the BBOX commas be encoded? The WMS spec says 'no',
  54      * but some services want it that way. Default false.
  55      */
  56     encodeBBOX: false,
  57
  58     /**
  59      * APIProperty: noMagic
  60      * {Boolean} If true, the image format will not be automagicaly switched
  61      *     from image/jpeg to image/png or image/gif when using
  62      *     TRANSPARENT=TRUE. Also isBaseLayer will not changed by the
  63      *     constructor. Default false.
  64      */
  65     noMagic: false,
  66
  67     /**
  68      * Constructor: OpenLayers.Layer.WMS
  69      * Create a new WMS layer object
  70      *
  71      * Example:
  72      * (code)
  73      * var wms = new OpenLayers.Layer.WMS("NASA Global Mosaic",
  74      *                                    "http://wms.jpl.nasa.gov/wms.cgi",
  75      *                                    {layers: "modis,global_mosaic"});
  76      * (end)
  77      *
  78      * Parameters:
  79      * name - {String} A name for the layer
  80      * url - {String} Base url for the WMS
  81      *                (e.g. http://wms.jpl.nasa.gov/wms.cgi)
  82      * params - {Object} An object with key/value pairs representing the
  83      *                   GetMap query string parameters and parameter values.
  84      * options - {Ojbect} Hashtable of extra options to tag onto the layer
  85      */
  86     initialize: function(name, url, params, options) {
  87         var newArguments = [];
  88         //uppercase params
  89         params = OpenLayers.Util.upperCaseObject(params);
  90         newArguments.push(name, url, params, options);
  91         OpenLayers.Layer.Grid.prototype.initialize.apply(this, newArguments);
  92         OpenLayers.Util.applyDefaults(
  93                        this.params,
  94                        OpenLayers.Util.upperCaseObject(this.DEFAULT_PARAMS)
  95                        );
  96
  97
  98         //layer is transparent
  99         if (!this.noMagic && this.params.TRANSPARENT &&
 100             this.params.TRANSPARENT.toString().toLowerCase() == "true") {
 101
 102             // unless explicitly set in options, make layer an overlay
 103             if ( (options == null) || (!options.isBaseLayer) ) {
 104                 this.isBaseLayer = false;
 105             }
 106
 107             // jpegs can never be transparent, so intelligently switch the
 108             //  format, depending on teh browser's capabilities
 109             if (this.params.FORMAT == "image/jpeg") {
 110                 this.params.FORMAT = OpenLayers.Util.alphaHack() ? "image/gif"
 111                                                                  : "image/png";
 112             }
 113         }
 114
 115     },
 116
 117     /**
 118      * Method: destroy
 119      * Destroy this layer
 120      */
 121     destroy: function() {
 122         // for now, nothing special to do here.
 123         OpenLayers.Layer.Grid.prototype.destroy.apply(this, arguments);
 124     },
 125
 126
 127     /**
 128      * Method: clone
 129      * Create a clone of this layer
 130      *
 131      * Returns:
 132      * {<OpenLayers.Layer.WMS>} An exact clone of this layer
 133      */
 134     clone: function (obj) {
 135
 136         if (obj == null) {
 137             obj = new OpenLayers.Layer.WMS(this.name,
 138                                            this.url,
 139                                            this.params,
 140                                            this.options);
 141         }
 142
 143         //get all additions from superclasses
 144         obj = OpenLayers.Layer.Grid.prototype.clone.apply(this, [obj]);
 145
 146         // copy/set any non-init, non-simple values here
 147
 148         return obj;
 149     },
 150
 151     /**
 152      * Method: getURL
 153      * Return a GetMap query string for this layer
 154      *
 155      * Parameters:
 156      * bounds - {<OpenLayers.Bounds>} A bounds representing the bbox for the
 157      *                                request.
 158      *
 159      * Returns:
 160      * {String} A string with the layer's url and parameters and also the
 161      *          passed-in bounds and appropriate tile size specified as
 162      *          parameters.
 163      */
 164     getURL: function (bounds) {
 165         bounds = this.adjustBounds(bounds);
 166
 167         var imageSize = this.getImageSize();
 168         var newParams = {
 169             'BBOX': this.encodeBBOX ?  bounds.toBBOX() : bounds.toArray(),
 170             'WIDTH': imageSize.w,
 171             'HEIGHT': imageSize.h
 172         };
 173         var requestString = this.getFullRequestString(newParams);
 174         return requestString;
 175     },
 176
 177     /**
 178      * Method: addTile
 179      * addTile creates a tile, initializes it, and adds it to the layer div.
 180      *
 181      * Parameters:
 182      * bounds - {<OpenLayers.Bounds>}
 183      * position - {<OpenLayers.Pixel>}
 184      *
 185      * Returns:
 186      * {<OpenLayers.Tile.Image>} The added OpenLayers.Tile.Image
 187      */
 188     addTile:function(bounds,position) {
 189         return new OpenLayers.Tile.Image(this, position, bounds,
 190                                          null, this.tileSize);
 191     },
 192
 193     /**
 194      * APIMethod: mergeNewParams
 195      * Catch changeParams and uppercase the new params to be merged in
 196      *     before calling changeParams on the super class.
 197      *
 198      *     Once params have been changed, the tiles will be reloaded with
 199      *     the new parameters.
 200      *
 201      * Parameters:
 202      * newParams - {Object} Hashtable of new params to use
 203      */
 204     mergeNewParams:function(newParams) {
 205         var upperParams = OpenLayers.Util.upperCaseObject(newParams);
 206         var newArguments = [upperParams];
 207         return OpenLayers.Layer.Grid.prototype.mergeNewParams.apply(this,
 208                                                              newArguments);
 209     },
 210
 211     /**
 212      * APIMethod: getFullRequestString
 213      * Combine the layer's url with its params and these newParams.
 214      *
 215      *     Add the SRS parameter from projection -- this is probably
 216      *     more eloquently done via a setProjection() method, but this
 217      *     works for now and always.
 218      *
 219      * Parameters:
 220      * newParams - {Object}
 221      * altUrl - {String} Use this as the url instead of the layer's url
 222      *
 223      * Returns:
 224      * {String}
 225      */
 226     getFullRequestString:function(newParams, altUrl) {
 227         var projectionCode = this.map.getProjection();
 228         this.params.SRS = (projectionCode == "none") ? null : projectionCode;
 229
 230         return OpenLayers.Layer.Grid.prototype.getFullRequestString.apply(
 231                                                     this, arguments);
 232     },
 233
 234     CLASS_NAME: "OpenLayers.Layer.WMS"
 235 });