openlayers/lib/OpenLayers/Format/WMC.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/Format/XML.js
   7  */
   8
   9 /**
  10  * Class: OpenLayers.Format.WMC
  11  * Read and write Web Map Context documents.
  12  *
  13  * Inherits from:
  14  *  - <OpenLayers.Format.XML>
  15  */
  16 OpenLayers.Format.WMC = OpenLayers.Class({
  17
  18     /**
  19      * APIProperty: defaultVersion
  20      * {String} Version number to assume if none found.  Default is "1.1.0".
  21      */
  22     defaultVersion: "1.1.0",
  23
  24     /**
  25      * APIProperty: version
  26      * {String} Specify a version string if one is known.
  27      */
  28     version: null,
  29
  30     /**
  31      * Property: layerOptions
  32      * {Object} Default options for layers created by the parser. These
  33      *     options are overridden by the options which are read from the
  34      *     capabilities document.
  35      */
  36     layerOptions: null,
  37
  38     /**
  39      * Property: layerParams
  40      * {Object} Default parameters for layers created by the parser. This
  41      *     can be used to override DEFAULT_PARAMS for OpenLayers.Layer.WMS.
  42      */
  43     layerParams: null,
  44
  45     /**
  46      * Property: parser
  47      * {Object} Instance of the versioned parser.  Cached for multiple read and
  48      *     write calls of the same version.
  49      */
  50     parser: null,
  51
  52     /**
  53      * Constructor: OpenLayers.Format.WMC
  54      * Create a new parser for WMC docs.
  55      *
  56      * Parameters:
  57      * options - {Object} An optional object whose properties will be set on
  58      *     this instance.
  59      */
  60     initialize: function(options) {
  61         OpenLayers.Util.extend(this, options);
  62         this.options = options;
  63     },
  64
  65     /**
  66      * APIMethod: read
  67      * Read WMC data from a string, and return an object with map properties
  68      *     and a list of layers.
  69      *
  70      * Parameters:
  71      * data - {String} or {DOMElement} data to read/parse.
  72      * options - {Object} The options object must contain a map property.  If
  73      *     the map property is a string, it must be the id of a dom element
  74      *     where the new map will be placed.  If the map property is an
  75      *     <OpenLayers.Map>, the layers from the context document will be added
  76      *     to the map.
  77      *
  78      * Returns:
  79      * {<OpenLayers.Map>} A map based on the context.
  80      */
  81     read: function(data, options) {
  82         if(typeof data == "string") {
  83             data = OpenLayers.Format.XML.prototype.read.apply(this, [data]);
  84         }
  85         var root = data.documentElement;
  86         var version = this.version;
  87         if(!version) {
  88             version = root.getAttribute("version");
  89             if(!version) {
  90                 version = this.defaultVersion;
  91             }
  92         }
  93         if(!this.parser || this.parser.VERSION != version) {
  94             var format = OpenLayers.Format.WMC[
  95                 "v" + version.replace(/\./g, "_")
  96             ];
  97             if(!format) {
  98                 throw "Can't find a WMC parser for version " +
  99                       version;
 100             }
 101             this.parser = new format(this.options);
 102         }
 103         var context = this.parser.read(data, options);
 104         var map;
 105         if(options.map) {
 106             this.context = context;
 107             if(options.map instanceof OpenLayers.Map) {
 108                 map = this.mergeContextToMap(context, options.map);
 109             } else {
 110                 map = this.contextToMap(context, options.map);
 111             }
 112         } else {
 113             // not documented as part of the API, provided as a non-API option
 114             map = context;
 115         }
 116         return map;
 117     },
 118
 119     /**
 120      * Method: contextToMap
 121      * Create a map given a context object.
 122      *
 123      * Parameters:
 124      * context - {Object} The context object.
 125      * id - {String | Element} The dom element or element id that will contain
 126      *     the map.
 127      *
 128      * Returns:
 129      * {<OpenLayers.Map>} A map based on the context object.
 130      */
 131     contextToMap: function(context, id) {
 132         var map = new OpenLayers.Map(id, {
 133             maxExtent: context.maxExtent,
 134             projection: context.projection
 135         });
 136         map.addLayers(context.layers);
 137         map.setCenter(
 138             context.bounds.getCenterLonLat(),
 139             map.getZoomForExtent(context.bounds, true)
 140         );
 141         return map;
 142     },
 143
 144     /**
 145      * Method: mergeContextToMap
 146      * Add layers from a context object to a map.
 147      *
 148      * Parameters:
 149      * context - {Object} The context object.
 150      * map - {<OpenLayers.Map>} The map.
 151      *
 152      * Returns:
 153      * {<OpenLayers.Map>} The same map with layers added.
 154      */
 155     mergeContextToMap: function(context, map) {
 156         map.addLayers(context.layers);
 157         return map;
 158     },
 159
 160     /**
 161      * APIMethod: write
 162      * Write a WMC document given a map.
 163      *
 164      * Parameters:
 165      * obj - {<OpenLayers.Map> | Object} A map or context object.
 166      * options - {Object} Optional configuration object.
 167      *
 168      * Returns:
 169      * {String} A WMC document string.
 170      */
 171     write: function(obj, options) {
 172         if(obj.CLASS_NAME == "OpenLayers.Map") {
 173             obj = this.mapToContext(obj);
 174         }
 175         var version = (options && options.version) ||
 176                       this.version || this.defaultVersion;
 177         if(!this.parser || this.parser.VERSION != version) {
 178             var format = OpenLayers.Format.WMC[
 179                 "v" + version.replace(/\./g, "_")
 180             ];
 181             if(!format) {
 182                 throw "Can't find a WMS capabilities parser for version " +
 183                       version;
 184             }
 185             this.parser = new format(this.options);
 186         }
 187         var wmc = this.parser.write(obj, options);
 188         return wmc;
 189     },
 190
 191     /**
 192      * Method: mapToContext
 193      * Create a context object given a map.
 194      *
 195      * Parameters:
 196      * map - {<OpenLayers.Map>} The map.
 197      *
 198      * Returns:
 199      * {Object} A context object.
 200      */
 201     mapToContext: function(map) {
 202         var context = {
 203             bounds: map.getExtent(),
 204             maxExtent: map.maxExtent,
 205             projection: map.projection,
 206             layers: map.layers,
 207             size: map.getSize()
 208         };
 209         return context;
 210     },
 211
 212     CLASS_NAME: "OpenLayers.Format.WMC"
 213
 214 });