1## Upgrade notes 2 3### v4.6.0 4 5#### Renamed `exceedLength` option of `ol.style.Text` to `overflow` 6 7To update your applications, simply replace `exceedLength` with `overflow`. 8 9#### Deprecation of `ol.source.ImageVector` 10 11Rendering vector sources as image is now directly supported by `ol.layer.Vector` with the new `renderMode: 'image'` configuration option. Change code like this: 12 13```js 14new ol.layer.Image({ 15 source: new ol.source.ImageVector({ 16 style: myStyle, 17 source: new ol.source.Vector({ 18 url: 'my/data.json', 19 format: new ol.format.GeoJSON() 20 }) 21 }) 22}); 23``` 24to: 25 26```js 27new ol.layer.Vector({ 28 renderMode: 'image', 29 style: myStyle, 30 source: new ol.source.Vector({ 31 url: 'my/data.json', 32 format: new ol.format.GeoJSON() 33 }) 34}); 35``` 36 37 38### v4.5.0 39 40#### Removed GeoJSON crs workaround for GeoServer 41 42Previous version of GeoServer returned invalid crs in GeoJSON output. The workaround in `ol.format.GeoJSON` used to read this crs code is now removed. 43 44#### Deprecation of `ol.Attribution` 45 46`ol.Attribution` is deprecated and will be removed in the next major version. Instead, you can construct a source with a string attribution or an array of strings. For dynamic attributions, you can provide a function that gets called with the current frame state. 47 48Before: 49```js 50var source = new ol.source.XYZ({ 51 attributions: [ 52 new ol.Attribution({html: 'some attribution'}) 53 ] 54}); 55``` 56 57After: 58```js 59var source = new ol.source.XYZ({ 60 attributions: 'some attribution' 61}); 62``` 63 64In addition to passing a string or an array of strings for the `attributions` option, you can also pass a function that will get called with the current frame state. 65```js 66var source = new ol.source.XYZ({ 67 attributions: function(frameState) { 68 // inspect the frame state and return attributions 69 return 'some attribution'; // or ['multiple', 'attributions'] or null 70 } 71}); 72``` 73 74### v4.4.0 75 76#### Behavior change for polygon labels 77 78Polygon labels are now only rendered when the label does not exceed the polygon at the label position. To get the old behavior, configure your `ol.style.Text` with `exceedLength: true`. 79 80#### Minor change for custom `tileLoadFunction` with `ol.source.VectorTile` 81 82It is no longer necessary to set the projection on the tile. Instead, the `readFeatures` method must be called with the tile's extent as `extent` option and the view's projection as `featureProjection`. 83 84Before: 85```js 86tile.setLoader(function() { 87 var data = // ... fetch data 88 var format = tile.getFormat(); 89 tile.setFeatures(format.readFeatures(data)); 90 tile.setProjection(format.readProjection(data)); 91 // uncomment the line below for ol.format.MVT only 92 //tile.setExtent(format.getLastExtent()); 93}); 94``` 95 96After: 97```js 98tile.setLoader(function() { 99 var data = // ... fetch data 100 var format = tile.getFormat(); 101 tile.setFeatures(format.readFeatures(data, { 102 featureProjection: map.getView().getProjection(), 103 // uncomment the line below for ol.format.MVT only 104 //extent: tile.getExtent() 105 })); 106); 107``` 108 109#### Deprecation of `ol.DeviceOrientation` 110 111`ol.DeviceOrientation` is deprecated and will be removed in the next major version. 112The device-orientation example has been updated to use the (gyronorm.js)[https://github.com/dorukeker/gyronorm.js] library. 113 114 115### v4.3.0 116 117#### `ol.source.VectorTile` no longer requires a `tileGrid` option 118 119By default, the `ol.source.VectorTile` constructor creates an XYZ tile grid (in Web Mercator) for 512 pixel tiles and assumes a max zoom level of 22. If you were creating a vector tile source with an explicit `tileGrid` option, you can now remove this. 120 121Before: 122```js 123var source = new ol.source.VectorTile({ 124 tileGrid: ol.tilegrid.createXYZ({tileSize: 512, maxZoom: 22}), 125 url: url 126}); 127``` 128 129After: 130```js 131var source = new ol.source.VectorTile({ 132 url: url 133}); 134``` 135 136If you need to change the max zoom level, you can pass the source a `maxZoom` option. If you need to change the tile size, you can pass the source a `tileSize` option. If you need a completely custom tile grid, you can still pass the source a `tileGrid` option. 137 138#### `ol.interaction.Modify` deletes with `alt` key only 139 140To delete features with the modify interaction, press the `alt` key while clicking on an existing vertex. If you want to configure the modify interaction with a different delete condition, use the `deleteCondition` option. For example, to allow deletion on a single click with no modifier keys, configure the interaction like this: 141```js 142var interaction = new ol.interaction.Modify({ 143 source: source, 144 deleteCondition: function(event) { 145 return ol.events.condition.noModifierKeys(event) && ol.events.condition.singleClick(event); 146 } 147}); 148``` 149 150The motivation for this change is to make the modify, draw, and snap interactions all work well together. Previously, the use of these interactions with the default configuration would make it so you couldn't reliably add new vertices (click with no modifier) and delete existing vertices (click with no modifier). 151 152#### `ol.source.VectorTile` no longer has a `tilePixelRatio` option 153 154The `tilePixelRatio` option was only used for tiles in projections with `tile-pixels` as units. For tiles read with `ol.format.MVT` and the default tile loader, or tiles with the default pixel size of 4096 pixels, no changes are necessary. For the very rare cases that do not fall under these categories, a custom `tileLoadFunction` now needs to be configured on the `ol.source.VectorTile`. In addition to calling `tile.setFeatures()` and `tile.setProjection()`, it also needs to contain code like the following: 155```js 156var extent = tile.getFormat() instanceof ol.format.MVT ? 157 tile.getLastExtent() : 158 [0, 0, tilePixelRatio * tileSize, tilePixelRatio * tileSize]; 159tile.setExtent(extent); 160``` 161 162#### `ol.animate` now takes the shortest arc for rotation animation 163 164Usually rotation animations should animate along the shortest arc. There are rare occasions where a spinning animation effect is desired. So if you previously had something like 165```js 166map.getView().animate({ 167 rotation: 2 * Math.PI, 168 duration: 2000 169}); 170``` 171we recommend to split the animation into two parts and use different easing functions. The code below results in the same effect as the snippet above did with previous versions: 172```js 173map.getView().animate({ 174 rotation: Math.PI, 175 easing: ol.easing.easeIn 176}, { 177 rotation: 2 * Math.PI, 178 easing: ol.easing.easeOut 179}); 180``` 181 182### v4.2.0 183 184#### Return values of two `ol.style.RegularShape` getters have changed 185 186To provide a more consistent behaviour the following getters now return the same value that was given to constructor: 187 188`ol.style.RegularShape#getPoints` does not return the double amount of points anymore if a radius2 is set. 189 190`ol.style.RegularShape#getRadius2` will return `undefined` if no radius2 is set. 191 192### v4.1.0 193 194#### Adding duplicate layers to a map throws 195 196Previously, you could do this: 197```js 198map.addLayer(layer); 199map.addLayer(layer); 200``` 201 202However, after adding a duplicate layer, things failed if you tried to remove that layer. 203 204Now, `map.addLayer()` throws if you try adding a layer that has already been added to the map. 205 206#### Simpler `constrainResolution` configuration 207 208The `constrainResolution` configuration for `ol.interaction.PinchZoom` and `ol.interaction.MouseWheelZoom` 209can now be set directly with an option in `ol.interaction.defaults`: 210```js 211ol.interaction.defaults({ 212 constrainResolution: true 213}); 214``` 215 216### v4.0.0 217 218#### Simpler `ol.source.Zoomify` `url` configuration 219 220Instead specifying a base url, the `url` for the `ol.source.Zoomify` source can now be a template. The `{TileGroup}`, `{x}`, `{y}`, `{z}` and placeholders must be included in the `url` in this case. the `url` can now also include subdomain placeholders: 221```js 222new ol.source.Zoomify({ 223 url: 'https://{a-f}.example.com/cgi-bin/iipsrv.fcgi?zoomify=/a/b/{TileGroup}/{z}-{x}-{y}.jpg' 224}); 225``` 226 227#### Removal of deprecated methods 228 229The deprecated `ol.animation` functions and `map.beforeRender()` method have been removed. Use `view.animate()` instead. 230 231The `unByKey()` method has been removed from `ol.Observable` instances. Use the `ol.Observable.unByKey()` static function instead. 232```js 233var key = map.on('moveend', function() { ...}); 234map.unByKey(key); 235``` 236New code: 237```js 238var key = map.on('moveend', function() { ...}); 239ol.Observable.unByKey(key); 240``` 241 242#### Simplified `ol.View#fit()` API 243 244In most cases, it is no longer necessary to provide an `ol.Size` (previously the 2nd argument) to `ol.View#fit()`. By default, the size of the first map that uses the view will be used. If you want to specify a different size, it goes in the options now (previously the 3rd argument, now the 2nd). 245 246Most common use case - old API: 247```js 248map.getView().fit(extent, map.getSize()); 249``` 250Most common use case - new API: 251```js 252map.getView().fit(extent); 253``` 254Advanced use - old API: 255```js 256map.getView().fit(extent, [200, 100], {padding: 10}); 257``` 258Advanced use - new API: 259```js 260map.getView().fit(extent, {size: [200, 100], padding 10}); 261``` 262 263#### Removed build flags (`@define`) 264 265The `ol.DEBUG`, `ol.ENABLE_TILE`, `ol.ENABLE_IMAGE`, `ol.ENABLE_VECTOR`, and `ol.ENABLE_VECTOR_TILE` build flags are no longer necessary and have been removed. If you were using these in a `define` array for a custom build, you can remove them. 266 267If you leave `ol.ENABLE_WEBGL` set to `true` in your build, you should set `ol.DEBUG_WEBGL` to `false` to avoid including debuggable shader sources. 268 269 270### v3.20.0 271 272#### Use `view.animate()` instead of `map.beforeRender()` and `ol.animation` functions 273 274The `map.beforeRender()` and `ol.animation` functions have been deprecated in favor of a new `view.animate()` function. Use of the deprecated functions will result in a warning during development. These functions are subject to removal in an upcoming release. 275 276For details on the `view.animate()` method, see the API docs and the view animation example. Upgrading should be relatively straightforward. For example, if you wanted to have an animated pan, zoom, and rotation previously, you might have done this: 277 278```js 279var zoom = ol.animation.zoom({ 280 resolution: view.getResolution() 281}); 282var pan = ol.animation.pan({ 283 source: view.getCenter() 284}); 285var rotate = ol.animation.rotate({ 286 rotation: view.getRotation() 287}); 288 289map.beforeRender(zoom, pan, rotate); 290 291map.setZoom(1); 292map.setCenter([0, 0]); 293map.setRotation(Math.PI); 294``` 295 296Now, the same can be accomplished with this: 297```js 298view.animate({ 299 zoom: 1, 300 center: [0, 0], 301 rotation: Math.PI 302}); 303``` 304 305#### `ol.Map#forEachFeatureAtPixel` and `ol.Map#hasFeatureAtPixel` parameters have changed 306 307If you are using the layer filter of one of these methods, please note that you now have to pass in the layer filter via an `ol.AtPixelOptions` object. If you are not using the layer filter the usage has not changed. 308 309Old syntax: 310```js 311map.forEachFeatureAtPixel(pixel, callback, callbackThis, layerFilterFn, layerFilterThis); 312 313map.hasFeatureAtPixel(pixel, layerFilterFn, layerFilterThis); 314``` 315 316New syntax: 317```js 318map.forEachFeatureAtPixel(pixel, callback.bind(callbackThis), { 319 layerFilter: layerFilterFn.bind(layerFilterThis) 320}); 321 322map.hasFeatureAtPixel(pixel, { 323 layerFilter: layerFilterFn.bind(layerFilterThis) 324}); 325``` 326 327This change is due to the introduction of the `hitTolerance` parameter which can be passed in via this `ol.AtPixelOptions` object, too. 328 329#### Use `ol.proj.getPointResolution()` instead of `projection.getPointResolution()` 330 331The experimental `getPointResolution` method has been removed from `ol.Projection` instances. Since the implementation of this method required an inverse transform (function for transforming projected coordinates to geographic coordinates) and `ol.Projection` instances are not constructed with forward or inverse transforms, it does not make sense that a projection instance can always calculate the point resolution. 332 333As a substitute for the `projection.getPointResolution()` function, a `ol.proj.getPointResolution()` function has been added. To upgrade, you will need to change things like this: 334```js 335projection.getPointResolution(resolution, point); 336``` 337 338into this: 339```js 340ol.proj.getPointResolution(projection, resolution, point); 341``` 342 343Note that if you were previously creating a projection with a `getPointResolution` function in the constructor (or calling `projection.setGetPointResolution()` after construction), this function will be used by `ol.proj.getPointResolution()`. 344 345#### `ol.interaction.PinchZoom` no longer zooms to a whole-number zoom level after the gesture ends 346 347The old behavior of `ol.interaction.PinchZoom` was to zoom to the next integer zoom level after the user ends the gesture. 348 349Now the pinch zoom keeps the user selected zoom level even if it is a fractional zoom. 350 351To get the old behavior set the new `constrainResolution` parameter to `true` like this: 352```js 353new ol.interaction.PinchZoom({constrainResolution: true}) 354``` 355 356See the new `pinch-zoom` example for a complete implementation. 357 358### v3.19.1 359 360#### `ol.style.Fill` with `CanvasGradient` or `CanvasPattern` 361 362The origin for gradients and patterns has changed from `[0, 0]` to the top-left 363corner of the extent of the geometry being filled. 364 365### v3.19.0 366 367#### `ol.style.Fill` with `CanvasGradient` or `CanvasPattern` 368 369Previously, gradients and patterns were aligned with the canvas, so they did not 370move and rotate with the map. This was changed to a more expected behavior by anchoring the fill to the map origin (usually at map coordinate `[0, 0]`). 371 372#### `goog.DEBUG` define was renamed to `ol.DEBUG` 373 374As last step in the removal of the dependency on Google Closure Library, the `goog.DEBUG` compiler define was renamed to `ol.DEBUG`. Please change accordingly in your custom build configuration json files. 375 376#### `ol.format.ogc.filter` namespace was renamed to `ol.format.filter` 377 378`ol.format.ogc.filter` was simplified to `ol.format.filter`; to upgrade your code, simply remove the `ogc` string from the name. 379For example: `ol.format.ogc.filter.and` to `ol.format.filter.and`. 380 381#### Changes only relevant to those who compile their applications together with the Closure Compiler 382 383A number of internal types have been renamed. This will not affect those who use the API provided by the library, but if you are compiling your application together with OpenLayers and using type names, you'll need to do the following: 384 385 * rename `ol.CollectionProperty` to `ol.Collection.Property` 386 * rename `ol.DeviceOrientationProperty` to `ol.DeviceOrientation.Property` 387 * rename `ol.DragBoxEvent` to `ol.interaction.DragBox.Event` 388 * rename `ol.DragBoxEventType` to `ol.interaction.DragBox.EventType` 389 * rename `ol.GeolocationProperty` to `ol.Geolocation.Property` 390 * rename `ol.OverlayPositioning` to `ol.Overlay.Positioning` 391 * rename `ol.OverlayProperty` to `ol.Overlay.Property` 392 * rename `ol.control.MousePositionProperty` to `ol.control.MousePosition.Property` 393 * rename `ol.format.IGCZ` to `ol.format.IGC.Z` 394 * rename `ol.interaction.InteractionProperty` to `ol.interaction.Interaction.Property` 395 * rename `ol.interaction.DrawMode` to `ol.interaction.Draw.Mode` 396 * rename `ol.interaction.DrawEvent` to `ol.interaction.Draw.Event` 397 * rename `ol.interaction.DrawEventType` to `ol.interaction.Draw.EventType` 398 * rename `ol.interaction.ExtentEvent` to `ol.interaction.Extent.Event` 399 * rename `ol.interaction.ExtentEventType` to `ol.interaction.Extent.EventType` 400 * rename `ol.interaction.DragAndDropEvent` to `ol.interaction.DragAndDrop.Event` 401 * rename `ol.interaction.DragAndDropEventType` to `ol.interaction.DragAndDrop.EventType` 402 * rename `ol.interaction.ModifyEvent` to `ol.interaction.Modify.Event` 403 * rename `ol.interaction.SelectEvent` to `ol.interaction.Select.Event` 404 * rename `ol.interaction.SelectEventType` to `ol.interaction.Select.EventType` 405 * rename `ol.interaction.TranslateEvent` to `ol.interaction.Translate.Event` 406 * rename `ol.interaction.TranslateEventType` to `ol.interaction.Translate.EventType` 407 * rename `ol.layer.GroupProperty` to `ol.layer.Group.Property` 408 * rename `ol.layer.HeatmapLayerProperty` to `ol.layer.Heatmap.Property` 409 * rename `ol.layer.TileProperty` to `ol.layer.Tile.Property` 410 * rename `ol.layer.VectorTileRenderType` to `ol.layer.VectorTile.RenderType` 411 * rename `ol.MapEventType` to `ol.MapEvent.Type` 412 * rename `ol.MapProperty` to `ol.Map.Property` 413 * rename `ol.ModifyEventType` to `ol.interaction.Modify.EventType` 414 * rename `ol.RendererType` to `ol.renderer.Type` 415 * rename `ol.render.EventType` to `ol.render.Event.Type` 416 * rename `ol.source.ImageEvent` to `ol.source.Image.Event` 417 * rename `ol.source.ImageEventType` to `ol.source.Image.EventType` 418 * rename `ol.source.RasterEvent` to `ol.source.Raster.Event` 419 * rename `ol.source.RasterEventType` to `ol.source.Raster.EventType` 420 * rename `ol.source.TileEvent` to `ol.source.Tile.Event` 421 * rename `ol.source.TileEventType` to `ol.source.Tile.EventType` 422 * rename `ol.source.VectorEvent` to `ol.source.Vector.Event` 423 * rename `ol.source.VectorEventType` to `ol.source.Vector.EventType` 424 * rename `ol.source.wms.ServerType` to `ol.source.WMSServerType` 425 * rename `ol.source.WMTSRequestEncoding` to `ol.source.WMTS.RequestEncoding` 426 * rename `ol.style.IconAnchorUnits` to `ol.style.Icon.AnchorUnits` 427 * rename `ol.style.IconOrigin` to `ol.style.Icon.Origin` 428 429### v3.18.0 430 431#### Removal of the DOM renderer 432 433The DOM renderer has been removed. Instead, the Canvas renderer should be used. If you were previously constructing a map with `'dom'` as the `renderer` option, you will see an error message in the console in debug mode and the Canvas renderer will be used instead. To remove the warning, remove the `renderer` option from your map constructor. 434 435#### Changes in the way assertions are handled 436 437Previously, minified builds of the library did not have any assertions. This caused applications to fail silently or with cryptic stack traces. Starting with this release, developers get notified of many runtime errors through the new `ol.AssertionError`. This error has a `code` property. The meaning of the code can be found on https://openlayers.org/en/latest/doc/errors/. There are additional console assertion checks in debug mode when the `goog.DEBUG` compiler flag is `true`. As this is `true` by default, it is recommended that those creating custom builds set this to `false` so these assertions are stripped.' 438 439#### Removal of `ol.ENABLE_NAMED_COLORS` 440 441This option was previously needed to use named colors with the WebGL renderer but is no longer needed. 442 443#### KML format now uses URL() 444 445The URL constructor is supported by all modern browsers, but not by older ones, such as IE. To use the KML format in such older browsers, a URL polyfill will have to be loaded before use. 446 447#### Changes only relevant to those who compile their applications together with the Closure Compiler 448 449A number of internal types have been renamed. This will not affect those who use the API provided by the library, but if you are compiling your application together with OpenLayers and using type names, you'll need to do the following: 450 451 * rename `ol.CollectionEventType` to `ol.Collection.EventType` 452 * rename `ol.CollectionEvent` to `ol.Collection.Event` 453 * rename `ol.ViewHint` to `ol.View.Hint` 454 * rename `ol.ViewProperty` to `ol.View.Property` 455 * rename `ol.render.webgl.imagereplay.shader.Default.Locations` to `ol.render.webgl.imagereplay.defaultshader.Locations` 456 * rename `ol.render.webgl.imagereplay.shader.DefaultFragment` to `ol.render.webgl.imagereplay.defaultshader.Fragment` 457 * rename `ol.render.webgl.imagereplay.shader.DefaultVertex` to `ol.render.webgl.imagereplay.defaultshader.Vertex` 458 * rename `ol.renderer.webgl.map.shader.Default.Locations` to `ol.renderer.webgl.defaultmapshader.Locations` 459 * rename `ol.renderer.webgl.map.shader.Default.Locations` to `ol.renderer.webgl.defaultmapshader.Locations` 460 * rename `ol.renderer.webgl.map.shader.DefaultFragment` to `ol.renderer.webgl.defaultmapshader.Fragment` 461 * rename `ol.renderer.webgl.map.shader.DefaultVertex` to `ol.renderer.webgl.defaultmapshader.Vertex` 462 * rename `ol.renderer.webgl.tilelayer.shader.Fragment` to `ol.renderer.webgl.tilelayershader.Fragment` 463 * rename `ol.renderer.webgl.tilelayer.shader.Locations` to `ol.renderer.webgl.tilelayershader.Locations` 464 * rename `ol.renderer.webgl.tilelayer.shader.Vertex` to `ol.renderer.webgl.tilelayershader.Vertex` 465 * rename `ol.webgl.WebGLContextEventType` to `ol.webgl.ContextEventType` 466 * rename `ol.webgl.shader.Fragment` to `ol.webgl.Fragment` 467 * rename `ol.webgl.shader.Vertex` to `ol.webgl.Vertex` 468 469### v3.17.0 470 471#### `ol.source.MapQuest` removal 472 473Because of changes at MapQuest (see: https://lists.openstreetmap.org/pipermail/talk/2016-June/076106.html) we had to remove the MapQuest source for now (see https://github.com/openlayers/openlayers/issues/5484 for details). 474 475#### `ol.interaction.ModifyEvent` changes 476 477The event object previously had a `mapBrowserPointerEvent` property, which has been renamed to `mapBrowserEvent`. 478 479#### Removal of ol.raster namespace 480 481Users compiling their code with the library and using types in the `ol.raster` namespace should note that this has now been removed. `ol.raster.Pixel` has been deleted, and the other types have been renamed as follows, and your code may need changing if you use these: 482* `ol.raster.Operation` to `ol.RasterOperation` 483* `ol.raster.OperationType` to `ol.RasterOperationType` 484 485#### All typedefs now in ol namespace 486 487Users compiling their code with the library should note that the following typedefs have been renamed; your code may need changing if you use these: 488* ol.events.ConditionType to ol.EventsConditionType 489* ol.events.EventTargetLike to ol.EventTargetLike 490* ol.events.Key to ol.EventsKey 491* ol.events.ListenerFunctionType to ol.EventsListenerFunctionType 492* ol.interaction.DragBoxEndConditionType to ol.DragBoxEndConditionType 493* ol.interaction.DrawGeometryFunctionType to ol.DrawGeometryFunctionType 494* ol.interaction.SegmentDataType to ol.ModifySegmentDataType 495* ol.interaction.SelectFilterFunction to ol.SelectFilterFunction 496* ol.interaction.SnapResultType to ol.SnapResultType 497* ol.interaction.SnapSegmentDataType to ol.SnapSegmentDataType 498* ol.proj.ProjectionLike to ol.ProjectionLike 499* ol.style.AtlasBlock to ol.AtlasBlock 500* ol.style.AtlasInfo to ol.AtlasInfo 501* ol.style.AtlasManagerInfo to ol.AtlasManagerInfo 502* ol.style.CircleRenderOptions to ol.CircleRenderOptions 503* ol.style.ImageOptions to ol.StyleImageOptions 504* ol.style.GeometryFunction to ol.StyleGeometryFunction 505* ol.style.RegularShapeRenderOptions to ol.RegularShapeRenderOptions 506* ol.style.StyleFunction to ol.StyleFunction 507 508### v3.16.0 509 510#### Rendering change for tile sources 511 512Previously, if you called `source.setUrl()` on a tile source, all currently rendered tiles would be cleared before new tiles were loaded and rendered. This clearing of the map is undesirable if you are trying to smoothly update the tiles used by a source. This behavior has now changed, and calling `source.setUrl()` (or `source.setUrls()`) will *not* clear currently rendered tiles before loading and rendering new tiles. Instead, previously rendered tiles remain rendered until new tiles have loaded and can replace them. If you want to achieve the old behavior (render a blank map before loading new tiles), you can call `source.refresh()` or you can replace the old source with a new one (using `layer.setSource()`). 513 514#### Move of typedefs out of code and into separate file 515 516This change should not affect the great majority of application developers, but it's possible there are edge cases when compiling application code together with the library which cause compiler errors or warnings. In this case, please raise a GitHub issue. `goog.require`s for typedefs should not be necessary. 517Users compiling their code with the library should note that the following API `@typedef`s have been renamed; your code may need changing if you use these: 518* `ol.format.WFS.FeatureCollectionMetadata` to `ol.WFSFeatureCollectionMetadata` 519* `ol.format.WFS.TransactionResponse` to `ol.WFSTransactionResponse` 520 521#### Removal of `opaque` option for `ol.source.VectorTile` 522 523This option is no longer needed, so it was removed from the API. 524 525#### XHR loading for `ol.source.TileUTFGrid` 526 527The `ol.source.TileUTFGrid` now uses XMLHttpRequest to load UTFGrid tiles by default. This works out of the box with the v4 Mapbox API. To work with the v3 API, you must use the new `jsonp` option on the source. See the examples below for detail. 528 529```js 530// To work with the v4 API 531var v4source = new ol.source.TileUTFGrid({ 532 url: 'https://api.tiles.mapbox.com/v4/example.json?access_token=' + YOUR_KEY_HERE 533}); 534 535// To work with the v3 API 536var v3source = new ol.source.TileUTFGrid({ 537 jsonp: true, // <--- this is required for v3 538 url: 'http://api.tiles.mapbox.com/v3/example.json' 539}); 540``` 541 542### v3.15.0 543 544#### Internet Explorer 9 support 545 546As of this release, OpenLayers requires a `classList` polyfill for IE 9 support. See https://cdn.polyfill.io/v2/docs/features#Element_prototype_classList. 547 548#### Immediate rendering API 549 550Listeners for `precompose`, `render`, and `postcompose` receive an event with a `vectorContext` property with methods for immediate vector rendering. The previous geometry drawing methods have been replaced with a single `vectorContext.drawGeometry(geometry)` method. If you were using any of the following experimental methods on the vector context, replace them with `drawGeometry`: 551 552 * Removed experimental geometry drawing methods: `drawPointGeometry`, `drawLineStringGeometry`, `drawPolygonGeometry`, `drawMultiPointGeometry`, `drawMultiLineStringGeometry`, `drawMultiPolygonGeometry`, and `drawCircleGeometry` (all have been replaced with `drawGeometry`). 553 554In addition, the previous methods for setting style parts have been replaced with a single `vectorContext.setStyle(style)` method. If you were using any of the following experimental methods on the vector context, replace them with `setStyle`: 555 556 * Removed experimental style setting methods: `setFillStrokeStyle`, `setImageStyle`, `setTextStyle` (all have been replaced with `setStyle`). 557 558Below is an example of how the vector context might have been used in the past: 559 560```js 561// OLD WAY, NO LONGER SUPPORTED 562map.on('postcompose', function(event) { 563 event.vectorContext.setFillStrokeStyle(style.getFill(), style.getStroke()); 564 event.vectorContext.drawPointGeometry(geometry); 565}); 566``` 567 568Here is an example of how you could accomplish the same with the new methods: 569```js 570// NEW WAY, USE THIS INSTEAD OF THE CODE ABOVE 571map.on('postcompose', function(event) { 572 event.vectorContext.setStyle(style); 573 event.vectorContext.drawGeometry(geometry); 574}); 575``` 576 577A final change to the immediate rendering API is that `vectorContext.drawFeature()` calls are now "immediate" as well. The drawing now occurs synchronously. This means that any `zIndex` in a style passed to `drawFeature()` will be ignored. To achieve `zIndex` ordering, order your calls to `drawFeature()` instead. 578 579#### Removal of `ol.DEFAULT_TILE_CACHE_HIGH_WATER_MARK` 580 581The `ol.DEFAULT_TILE_CACHE_HIGH_WATER_MARK` define has been removed. The size of the cache can now be defined on every tile based `ol.source`: 582```js 583new ol.layer.Tile({ 584 source: new ol.source.OSM({ 585 cacheSize: 128 586 }) 587}) 588``` 589The default cache size is `2048`. 590 591### v3.14.0 592 593#### Internet Explorer 9 support 594 595As of this release, OpenLayers requires a `requestAnimationFrame`/`cancelAnimationFrame` polyfill for IE 9 support. See https://cdn.polyfill.io/v2/docs/features/#requestAnimationFrame. 596 597#### Layer pre-/postcompose event changes 598 599It is the responsibility of the application to undo any canvas transform changes at the end of a layer 'precompose' or 'postcompose' handler. Previously, it was ok to set a null transform. The API now guarantees a device pixel coordinate system on the canvas with its origin in the top left corner of the map. However, applications should not rely on the underlying canvas being the same size as the visible viewport. 600 601Old code: 602```js 603layer.on('precompose', function(e) { 604 // rely on canvas dimensions to move coordinate origin to center 605 e.context.translate(e.context.canvas.width / 2, e.context.canvas.height / 2); 606 e.context.scale(3, 3); 607 // draw an x in the center of the viewport 608 e.context.moveTo(-20, -20); 609 e.context.lineTo(20, 20); 610 e.context.moveTo(-20, 20); 611 e.context.lineTo(20, -20); 612 // rely on the canvas having a null transform 613 e.context.setTransform(1, 0, 0, 1, 0, 0); 614}); 615``` 616New code: 617```js 618layer.on('precompose', function(e) { 619 // use map size and pixel ratio to move coordinate origin to center 620 var size = map.getSize(); 621 var pixelRatio = e.frameState.pixelRatio; 622 e.context.translate(size[0] / 2 * pixelRatio, size[1] / 2 * pixelRatio); 623 e.context.scale(3, 3); 624 // draw an x in the center of the viewport 625 e.context.moveTo(-20, -20); 626 e.context.lineTo(20, 20); 627 e.context.moveTo(-20, 20); 628 e.context.lineTo(20, -20); 629 // undo all transforms 630 e.context.scale(1 / 3, 1 / 3); 631 e.context.translate(-size[0] / 2 * pixelRatio, -size[1] / 2 * pixelRatio); 632}); 633``` 634 635### v3.13.0 636 637#### `proj4js` integration 638 639Before this release, OpenLayers depended on the global proj4 namespace. When using a module loader like Browserify, you might not want to depend on the global `proj4` namespace. You can use the `ol.proj.setProj4` function to set the proj4 function object. For example in a browserify ES6 environment: 640 641```js 642import ol from 'openlayers'; 643import proj4 from 'proj4'; 644ol.proj.setProj4(proj4); 645``` 646 647#### `ol.source.TileJSON` changes 648 649The `ol.source.TileJSON` now uses `XMLHttpRequest` to load the TileJSON instead of JSONP with callback. 650When using server without proper CORS support, `jsonp: true` option can be passed to the constructor to get the same behavior as before: 651```js 652new ol.source.TileJSON({ 653 url: 'http://serverwithoutcors.com/tilejson.json', 654 jsonp: true 655}) 656``` 657Also for Mapbox v3, make sure you use urls ending with `.json` (which are able to handle both `XMLHttpRequest` and JSONP) instead of `.jsonp`. 658 659### v3.12.0 660 661#### `ol.Map#forEachFeatureAtPixel` changes 662 663The optional `layerFilter` function is now also called for unmanaged layers. To get the same behaviour as before, wrap your layer filter code in an if block like this: 664```js 665function layerFilter(layer) { 666 if (map.getLayers().getArray().indexOf(layer) !== -1) { 667 // existing layer filter code 668 } 669} 670``` 671 672### v3.11.0 673 674#### `ol.format.KML` changes 675 676KML icons are scaled 50% so that the rendering better matches Google Earth rendering. 677 678If a KML placemark has a name and is a point, an `ol.style.Text` is created with the name displayed to the right of the icon (if there is an icon). 679This can be controlled with the showPointNames option which defaults to true. 680 681To disable rendering of the point names for placemarks, use the option: 682new ol.format.KML({ showPointNames: false }); 683 684 685#### `ol.interaction.DragBox` and `ol.interaction.DragZoom` changes 686 687Styling is no longer done with `ol.Style`, but with pure CSS. The `style` constructor option is no longer required, and no longer available. Instead, there is a `className` option for the CSS selector. The default for `ol.interaction.DragBox` is `ol-dragbox`, and `ol.interaction.DragZoom` uses `ol-dragzoom`. If you previously had 688```js 689new ol.interaction.DragZoom({ 690 style: new ol.style.Style({ 691 stroke: new ol.style.Stroke({ 692 color: 'red', 693 width: 3 694 }), 695 fill: new ol.style.Fill({ 696 color: [255, 255, 255, 0.4] 697 }) 698 }) 699}); 700``` 701you'll now just need 702```js 703new ol.interaction.DragZoom(); 704``` 705but with additional css: 706```css 707.ol-dragzoom { 708 border-color: red; 709 border-width: 3px; 710 background-color: rgba(255,255,255,0.4); 711} 712``` 713 714#### Removal of `ol.source.TileVector` 715 716With the introduction of true vector tile support, `ol.source.TileVector` becomes obsolete. Change your code to use `ol.layer.VectorTile` and `ol.source.VectorTile` instead of `ol.layer.Vector` and `ol.source.TileVector`. 717 718#### `ol.Map#forEachFeatureAtPixel` changes for unmanaged layers 719 720`ol.Map#forEachFeatureAtPixel` will still be called for unmanaged layers, but the 2nd argument to the callback function will be `null` instead of a reference to the unmanaged layer. This brings back the behavior of the abandoned `ol.FeatureOverlay` that was replaced by unmanaged layers. 721 722If you are affected by this change, please change your unmanaged layer to a regular layer by using e.g. `ol.Map#addLayer` instead of `ol.layer.Layer#setMap`. 723 724### v3.10.0 725 726#### `ol.layer.Layer` changes 727 728The experimental `setHue`, `setContrast`, `setBrightness`, `setSaturation`, and the corresponding getter methods have been removed. These properties only worked with the WebGL renderer. If are interested in applying color transforms, look for the `postcompose` event in the API docs. In addition, the `ol.source.Raster` source provides a way to create new raster data based on arbitrary transforms run on any number of input sources. 729 730### v3.9.0 731 732#### `ol.style.Circle` changes 733 734The experimental `getAnchor`, `getOrigin`, and `getSize` methods have been removed. The anchor and origin of a circle symbolizer are not modifiable, so these properties should not need to be accessed. The radius and stroke width can be used to calculate the rendered size of a circle symbolizer if needed: 735 736```js 737// calculate rendered size of a circle symbolizer 738var width = 2 * circle.getRadius(); 739if (circle.getStroke()) { 740 width += circle.getStroke().getWidth() + 1; 741} 742``` 743 744### v3.8.0 745 746There should be nothing special required when upgrading from v3.7.0 to v3.8.0. 747 748### v3.7.0 749 750#### Removal of `ol.FeatureOverlay` 751 752Instead of an `ol.FeatureOverlay`, we now use an `ol.layer.Vector` with an 753`ol.source.Vector`. If you previously had: 754```js 755var featureOverlay = new ol.FeatureOverlay({ 756 map: map, 757 style: overlayStyle 758}); 759featureOverlay.addFeature(feature); 760featureOverlay.removeFeature(feature); 761var collection = featureOverlay.getFeatures(); 762``` 763you will have to change this to: 764```js 765var collection = new ol.Collection(); 766var featureOverlay = new ol.layer.Vector({ 767 map: map, 768 source: new ol.source.Vector({ 769 features: collection, 770 useSpatialIndex: false // optional, might improve performance 771 }), 772 style: overlayStyle, 773 updateWhileAnimating: true, // optional, for instant visual feedback 774 updateWhileInteracting: true // optional, for instant visual feedback 775}); 776featureOverlay.getSource().addFeature(feature); 777featureOverlay.getSource().removeFeature(feature); 778``` 779 780With the removal of `ol.FeatureOverlay`, `zIndex` symbolizer properties of overlays are no longer stacked per map, but per layer/overlay. If you previously had multiple feature overlays where you controlled the rendering order of features by using `zIndex` symbolizer properties, you can now achieve the same rendering order only if all overlay features are on the same layer. 781 782Note that `ol.FeatureOverlay#getFeatures()` returned an `{ol.Collection.<ol.Feature>}`, whereas `ol.source.Vector#getFeatures()` returns an `{Array.<ol.Feature>}`. 783 784#### `ol.TileCoord` changes 785 786Until now, the API exposed two different types of `ol.TileCoord` tile coordinates: internal ones that increase left to right and upward, and transformed ones that may increase downward, as defined by a transform function on the tile grid. With this change, the API now only exposes tile coordinates that increase left to right and upward. 787 788Previously, tile grids created by OpenLayers either had their origin at the top-left or at the bottom-left corner of the extent. To make it easier for application developers to transform tile coordinates to the common XYZ tiling scheme, all tile grids that OpenLayers creates internally have their origin now at the top-left corner of the extent. 789 790This change affects applications that configure a custom `tileUrlFunction` for an `ol.source.Tile`. Previously, the `tileUrlFunction` was called with rather unpredictable tile coordinates, depending on whether a tile coordinate transform took place before calling the `tileUrlFunction`. Now it is always called with OpenLayers tile coordinates. To transform these into the common XYZ tiling scheme, a custom `tileUrlFunction` has to change the `y` value (tile row) of the `ol.TileCoord`: 791```js 792function tileUrlFunction = function(tileCoord, pixelRatio, projection) { 793 var urlTemplate = '{z}/{x}/{y}'; 794 return urlTemplate 795 .replace('{z}', tileCoord[0].toString()) 796 .replace('{x}', tileCoord[1].toString()) 797 .replace('{y}', (-tileCoord[2] - 1).toString()); 798} 799``` 800 801The `ol.tilegrid.TileGrid#createTileCoordTransform()` function which could be used to get the tile grid's tile coordinate transform function has been removed. This function was confusing and should no longer be needed now that application developers get tile coordinates in a known layout. 802 803The code snippets below show how your application code needs to be changed: 804 805Old application code (with `ol.tilegrid.TileGrid#createTileCoordTransform()`): 806```js 807var transform = source.getTileGrid().createTileCoordTransform(); 808var tileUrlFunction = function(tileCoord, pixelRatio, projection) { 809 tileCoord = transform(tileCoord, projection); 810 return 'http://mytiles.com/' + 811 tileCoord[0] + '/' + tileCoord[1] + '/' + tileCoord[2] + '.png'; 812}; 813``` 814Old application code (with custom `y` transform): 815```js 816var tileUrlFunction = function(tileCoord, pixelRatio, projection) { 817 var z = tileCoord[0]; 818 var yFromBottom = tileCoord[2]; 819 var resolution = tileGrid.getResolution(z); 820 var tileHeight = ol.size.toSize(tileSize)[1]; 821 var matrixHeight = 822 Math.floor(ol.extent.getHeight(extent) / tileHeight / resolution); 823 return 'http://mytiles.com/' + 824 tileCoord[0] + '/' + tileCoord[1] + '/' + 825 (matrixHeight - yFromBottom - 1) + '.png'; 826 827}; 828``` 829New application code (simple -y - 1 transform): 830```js 831var tileUrlFunction = function(tileCoord, pixelRatio, projection) { 832 return 'http://mytiles.com/' + 833 tileCoord[0] + '/' + tileCoord[1] + '/' + (-tileCoord[2] - 1) + '.png'; 834}; 835``` 836 837#### Removal of `ol.tilegrid.Zoomify` 838 839The replacement of `ol.tilegrid.Zoomify` is a plain `ol.tilegrid.TileGrid`, configured with `extent`, `origin` and `resolutions`. If the `size` passed to the `ol.source.Zoomify` source is `[width, height]`, then the extent for the tile grid will be `[0, -height, width, 0]`, and the origin will be `[0, 0]`. 840 841#### Replace `ol.View.fitExtent()` and `ol.View.fitGeometry()` with `ol.View.fit()` 842* This combines two previously distinct functions into one more flexible call which takes either a geometry or an extent. 843* Rename all calls to `fitExtent` and `fitGeometry` to `fit`. 844 845#### Change to `ol.interaction.Modify` 846 847When single clicking a line or boundary within the `pixelTolerance`, a vertex is now created. 848 849### v3.6.0 850 851#### `ol.interaction.Draw` changes 852 853* The `minPointsPerRing` config option has been renamed to `minPoints`. It is now also available for linestring drawing, not only for polygons. 854* The `ol.DrawEvent` and `ol.DrawEventType` types were renamed to `ol.interaction.DrawEvent` and `ol.interaction.DrawEventType`. This has an impact on your code only if your code is compiled together with OpenLayers. 855 856#### `ol.tilegrid` changes 857 858* The `ol.tilegrid.XYZ` constructor has been replaced by a static `ol.tilegrid.createXYZ()` function. The `ol.tilegrid.createXYZ()` function takes the same arguments as the previous `ol.tilegrid.XYZ` constructor, but returns an `ol.tilegrid.TileGrid` instance. 859* The internal tile coordinate scheme for XYZ sources has been changed. Previously, the `y` of tile coordinates was transformed to the coordinates used by sources by calculating `-y-1`. Now, it is transformed by calculating `height-y-1`, where height is the number of rows of the tile grid at the zoom level of the tile coordinate. 860* The `widths` constructor option of `ol.tilegrid.TileGrid` and subclasses is no longer available, and it is no longer necessary to get proper wrapping at the 180° meridian. However, for `ol.tilegrid.WMTS`, there is a new option `sizes`, where each entry is an `ol.Size` with the `width` ('TileMatrixWidth' in WMTS capabilities) as first and the `height` ('TileMatrixHeight') as second entry of the array. For other tile grids, users can 861now specify an `extent` instead of `widths`. These settings are used to restrict the range of tiles that sources will request. 862* For `ol.source.TileWMS`, the default value of `warpX` used to be `undefined`, meaning that WMS requests with out-of-extent tile BBOXes would be sent. Now `wrapX` can only be `true` or `false`, and the new default is `true`. No application code changes should be required, but the resulting WMS requests for out-of-extent tiles will no longer use out-of-extent BBOXes, but ones that are shifted to real-world coordinates. 863 864### v3.5.0 865 866#### `ol.Object` and `bindTo` 867 868* The following experimental methods have been removed from `ol.Object`: `bindTo`, `unbind`, and `unbindAll`. If you want to get notification about `ol.Object` property changes, you can listen for the `'propertychange'` event (e.g. `object.on('propertychange', listener)`). Two-way binding can be set up at the application level using property change listeners. See [#3472](https://github.com/openlayers/openlayers/pull/3472) for details on the change. 869 870* The experimental `ol.dom.Input` component has been removed. If you need to synchronize the state of a dom Input element with an `ol.Object`, this can be accomplished using listeners for change events. For example, you might bind the state of a checkbox type input with a layer's visibility like this: 871 872 ```js 873 var layer = new ol.layer.Tile(); 874 var checkbox = document.querySelector('#checkbox'); 875 876 checkbox.addEventListener('change', function() { 877 var checked = this.checked; 878 if (checked !== layer.getVisible()) { 879 layer.setVisible(checked); 880 } 881 }); 882 883 layer.on('change:visible', function() { 884 var visible = this.getVisible(); 885 if (visible !== checkbox.checked) { 886 checkbox.checked = visible; 887 } 888 }); 889 ``` 890 891#### New Vector API 892 893* The following experimental vector classes have been removed: `ol.source.GeoJSON`, `ol.source.GML`, `ol.source.GPX`, `ol.source.IGC`, `ol.source.KML`, `ol.source.OSMXML`, and `ol.source.TopoJSON`. You now will use `ol.source.Vector` instead. 894 895 For example, if you used `ol.source.GeoJSON` as follows: 896 897 ```js 898 var source = new ol.source.GeoJSON({ 899 url: 'features.json', 900 projection: 'EPSG:3857' 901 }); 902 ``` 903 904 you will need to change your code to: 905 906 ```js 907 var source = new ol.source.Vector({ 908 url: 'features.json', 909 format: new ol.format.GeoJSON() 910 }); 911 ``` 912 913 See https://openlayers.org/en/master/examples/vector-layer.html for a real example. 914 915 Note that you no longer need to set a `projection` on the source! 916 917 Previously the vector data was loaded at source construction time, and, if the data projection and the source projection were not the same, the vector data was transformed to the source projection before being inserted (as features) into the source. 918 919 The vector data is now loaded at render time, when the view projection is known. And the vector data is transformed to the view projection if the data projection and the source projection are not the same. 920 921 If you still want to "eagerly" load the source you will use something like this: 922 923 ```js 924 var source = new ol.source.Vector(); 925 $.ajax('features.json').then(function(response) { 926 var geojsonFormat = new ol.format.GeoJSON(); 927 var features = geojsonFormat.readFeatures(response, 928 {featureProjection: 'EPSG:3857'}); 929 source.addFeatures(features); 930 }); 931 ``` 932 933 The above code uses jQuery to send an Ajax request, but you can obviously use any Ajax library. 934 935 See https://openlayers.org/en/master/examples/igc.html for a real example. 936 937* Note about KML 938 939 If you used `ol.source.KML`'s `extractStyles` or `defaultStyle` options, you will now have to set these options on `ol.format.KML` instead. For example, if you used: 940 941 ```js 942 var source = new ol.source.KML({ 943 url: 'features.kml', 944 extractStyles: false, 945 projection: 'EPSG:3857' 946 }); 947 ``` 948 949 you will now use: 950 951 ```js 952 var source = new ol.source.Vector({ 953 url: 'features.kml', 954 format: new ol.format.KML({ 955 extractStyles: false 956 }) 957 }); 958 ``` 959 960* The `ol.source.ServerVector` class has been removed. If you used it, for example as follows: 961 962 ```js 963 var source = new ol.source.ServerVector({ 964 format: new ol.format.GeoJSON(), 965 loader: function(extent, resolution, projection) { 966 var url = …; 967 $.ajax(url).then(function(response) { 968 source.addFeatures(source.readFeatures(response)); 969 }); 970 }, 971 strategy: ol.loadingstrategy.bbox, 972 projection: 'EPSG:3857' 973 }); 974 ``` 975 976 you will need to change your code to: 977 978 ```js 979 var source = new ol.source.Vector({ 980 loader: function(extent, resolution, projection) { 981 var url = …; 982 $.ajax(url).then(function(response) { 983 var format = new ol.format.GeoJSON(); 984 var features = format.readFeatures(response, 985 {featureProjection: projection}); 986 source.addFeatures(features); 987 }); 988 }, 989 strategy: ol.loadingstrategy.bbox 990 }); 991 ``` 992 993 See https://openlayers.org/en/master/examples/vector-osm.html for a real example. 994 995* The experimental `ol.loadingstrategy.createTile` function has been renamed to `ol.loadingstrategy.tile`. The signature of the function hasn't changed. See https://openlayers.org/en/master/examples/vector-osm.html for an example. 996 997#### Change to `ol.style.Icon` 998 999* When manually loading an image for `ol.style.Icon`, the image size should now be set 1000with the `imgSize` option and not with `size`. `size` is supposed to be used for the 1001size of a sub-rectangle in an image sprite. 1002 1003#### Support for non-square tiles 1004 1005The return value of `ol.tilegrid.TileGrid#getTileSize()` will now be an `ol.Size` array instead of a number if non-square tiles (i.e. an `ol.Size` array instead of a number as `tilsSize`) are used. To always get an `ol.Size`, the new `ol.size.toSize()` was added. 1006 1007#### Change to `ol.interaction.Draw` 1008 1009When finishing a draw, the `drawend` event is now dispatched before the feature is inserted to either the source or the collection. This change allows application code to finish setting up the feature. 1010 1011#### Misc. 1012 1013If you compile your application together with the library and use the `ol.feature.FeatureStyleFunction` type annotation (this should be extremely rare), the type is now named `ol.FeatureStyleFunction`. 1014 1015### v3.4.0 1016 1017There should be nothing special required when upgrading from v3.3.0 to v3.4.0. 1018 1019### v3.3.0 1020 1021* The `ol.events.condition.mouseMove` function was replaced by `ol.events.condition.pointerMove` (see [#3281](https://github.com/openlayers/openlayers/pull/3281)). For example, if you use `ol.events.condition.mouseMove` as the condition in a `Select` interaction then you now need to use `ol.events.condition.pointerMove`: 1022 1023 ```js 1024 var selectInteraction = new ol.interaction.Select({ 1025 condition: ol.events.condition.pointerMove 1026 // … 1027 }); 1028 ``` 1029