diff --git a/API-&-Defaults-Discussion.md b/API-&-Defaults-Discussion.md index 330b064..3121a45 100644 --- a/API-&-Defaults-Discussion.md +++ b/API-&-Defaults-Discussion.md @@ -1,5 +1,7 @@ OpenLayers 3 should provide an API that makes it easy to accomplish common use cases. People who do not need to leverage the full functionality should be provided fast lanes for a leaner and easy to use configuration. Defaults should be set in the right places to avoid duplicated code. +This document is work in progress. At the time of writing, it reflects @ahocevar's thoughts on a few aspects of the library that come to mind when thinking about API and defaults. + ## Map with WMS layer (tiled) in default projection (EPSG:3857) new ol.Map({ @@ -23,7 +25,6 @@ OpenLayers 3 should provide an API that makes it easy to accomplish common use c new ol.Map({ layers: [ - // suitable layer type can be chosen based on the source new ol.source.TiledWMS({ url: '/geoserver/wms', params: { @@ -31,10 +32,11 @@ OpenLayers 3 should provide an API that makes it easy to accomplish common use c } }) ], - // would be even nicer to provide center and zoom as direct map config options view: { projection: { code: 'EPSG:31256', + units: 'meters', + // validity extent from http://spatialreference.org/ extent: [-115317.3972, 151511.8020, 64307.1064, 432456.2246] }, center: [47, 15], @@ -42,4 +44,44 @@ OpenLayers 3 should provide an API that makes it easy to accomplish common use c } }); -The layer source should not need a projection configuration - it should get it from the view. With the projection's extent, the layer source should be able to create a default tile grid. \ No newline at end of file +The layer source should not need a projection configuration - it should get it from the view. With the projection's extent, the layer source should be able to create a default tile grid. The map's zoom levels will be derived from the projection's extent as well. + +## Map with custom projection and single image WMS layer + +Exactly the same as above, only with `ol.source.SingleImageWMS` instead of `ol.Source.TiledWMS`. It should not be necessary to configure the layer source with a resolutions array, and a single image source should be able to serve any resolution that the map uses. + +## Map with custom projection, WMS layer with custom tile grid + + + new ol.Map({ + layers: [ + new ol.source.TiledWMS({ + url: '/geoserver/wms', + params: { + 'LAYERS': 'usa:states' // would be nice without quotes for the key + }, + tileGrid: { + maxExtent: [-100000, 160000, 60000, 430000], + resolutions: [1000, 500, 200, 100, 50, 20, 10, 5, 2, 1] + } + }) + ], + view: { + projection: { + code: 'EPSG:31256', + units: 'meters', + // validity extent from http://spatialreference.org/ + extent: [-115317.3972, 151511.8020, 64307.1064, 432456.2246] + }, + center: [47, 15], + zoom: 3 + } + }); + +Since the TileGrid is a very complex thing, and most use cases except ArcGISCache and WMTS use the same grid extent for each resolution, it makes sense to provide a convenience configuration with a common maxExtent and a set of resolutions. + +## Thoughts on defaults + +Looking at the current code, there are still more than one places with Web Mercator related defaults. The central place for projection related defaults should be the `ol.projection` package. If layer sources can lazily create a TileGrid upon rendering, it will be possible to use map defaults for layer sources. + +The concept of user projections works best in the context of a map. Classes like Coordinate or Extent do not necessarily need to know about the user projection if the map (or the view) provides extent and center related getters. \ No newline at end of file