diff --git a/doc/quickstart.hbs b/doc/quickstart.hbs index e8544b61cf..bb0d450c55 100644 --- a/doc/quickstart.hbs +++ b/doc/quickstart.hbs @@ -5,6 +5,8 @@ layout: doc.hbs # Quick Start +This primer shows you how to put a simple map on a web page. + ## Put a map on a page Below you'll find a complete working example. Create a new file, copy in the contents below, and open in a browser: @@ -54,6 +56,8 @@ To include a map a web page you will need 3 things: ### Include OpenLayers +**Caveat:** In production, it is not recommended to include dependencies as script tag. Instead, we recommend bundling the application together with its dependencies, as explained in the [Building an OpenLayers Application](./tutorials/bundle.html) tutorial. + ```xml ``` diff --git a/doc/tutorials/background.md b/doc/tutorials/background.md new file mode 100644 index 0000000000..5566fb27a4 --- /dev/null +++ b/doc/tutorials/background.md @@ -0,0 +1,49 @@ +--- +title: Introduction +layout: doc.hbs +--- + +# Introduction + +## Objectives + +OpenLayers is a modular, high-performance, feature-packed library for displaying and interacting with maps and geospatial data. + +The library comes with built-in support for a wide range of commercial and free image and vector tile sources, and the most popular open and proprietary vector data formats. With OpenLayers's map projection support, data can be in any projection. + +## Public API + +OpenLayers is available as [`ol` npm package](https://npmjs.com/package/ol), which provides all modules of the officially supported [API](../../apidoc). + +## Renderers and Browser Support + +By default, OpenLayers uses a performance optimized Canvas renderer. An experimental WebGL renderer (without text rendering support) is also avaialble. + +OpenLayers runs on all modern browsers that support [HTML5](https://html.spec.whatwg.org/multipage/) and [ECMAScript 5](http://www.ecma-international.org/ecma-262/5.1/). This includes Chrome, Firefox, Safari and Edge. For older browsers and platforms like Internet Explorer (down to version 9) and Android 4.x, [polyfills](http://polyfill.io), the application bundle needs to be transpiled (e.g. using [Babel](https://babeljs.io)) and bundled with polyfills for `requestAnimationFrame`, `Element.prototype.classList` and `URL`. + +The library is intended for use on both desktop/laptop and mobile devices, and supports pointer and touch interactions. + +## Module and Naming Conventions + +OpenLayers modules with CamelCase names provide classes as default exports, and may contain additional constants or functions as named exports: + +```js +import Map from 'ol/Map'; +import View from 'ol/View'; +``` + +Class hierarchies grouped by their parent are provided in a subfolder of the package, e.g. `layer/`. + +For convenience, these are also available as named exports, e.g. + +```js +import {Map, View} from `ol`; +import {Tile, Vector} from `ol/layer`; +``` + +In addition to these re-exported classes, modules with lowercase names also provide constants or functions as named exports: + +```js +import {inherits} from `ol`; +import {fromLonLat} from `ol/proj`; +``` diff --git a/doc/tutorials/browserify.md b/doc/tutorials/browserify.md deleted file mode 100644 index a405178004..0000000000 --- a/doc/tutorials/browserify.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Basic project setup using NPM and Browserify -layout: doc.hbs ---- - -# Introduction - -When going beyond modifying existing examples you might be looking for a way to setup your own code with dependency management together with external dependencies like OpenLayers. - -This tutorial serves as a suggested project setup using NPM and Browserify for the most basic needs. There are several other options, and in particular you might be interested in a more modern one (ES2015) [using Webpack with OpenLayers](https://gist.github.com/tschaub/79025aef325cd2837364400a105405b8). - -## Initial steps - -Create a new empty directory for your project and navigate to it by running `mkdir new-project && cd new-project`. Initialize your project using `npm init` and answer the questions asked. - -Add OpenLayers as dependency to your application with `npm install --save ol`. - -At this point you can ask NPM to add required development dependencies by running -``` -npm install --save-dev cssify browserify cssify http-server uglify-js watchify -npm install --save-dev babelify babel-plugin-transform-es2015-modules-commonjs -``` -We will be using `cssify` to include the css definitions required by OpenLayers in our bundle. `watchify`, `http-server` and `uglify-js` are used to monitor for changes and to build into a minified bundle. `babelify` and `babel-plugin-transform-es2015-modules-commonjs` are used to make the `ol` package, which was created using ES2015 modules, work with CommonJS. - -## Application code and index.html - -Place your application code in `index.js`. Here is a simple starting point: - -```js -require('ol/ol.css'); -var ol_Map = require('ol/map').default; -var ol_layer_Tile = require('ol/layer/tile').default; -var ol_source_OSM = require('ol/source/osm').default; -var ol_View = require('ol/view').default; - -var map = new ol_Map({ - target: 'map', - layers: [ - new ol_layer_Tile({ - source: new ol_source_OSM() - }) - ], - view: new ol_View({ - center: [0, 0], - zoom: 0 - }) -}); -``` - -You will also need an `ìndex.html` file that will use your bundle. Here is a simple example: - -```html - - - - - Using Browserify with OpenLayers - - - -
- - - -``` - -## Creating a bundle - -With simple scripts you can introduce the commands `npm run build` and `npm start` to manually build your bundle and watch for changes, respectively. Add the following to the script section in `package.json`: - -```json -"scripts": { - "start": "watchify index.js -g cssify --outfile bundle.js & http-server", - "build": "browserify -g cssify index.js | uglifyjs --compress --output bundle.js" -} -``` -Now to test your application open http://localhost:8080/ in your browser. `watchify` will update `bundle.js` whenever you change something. You simply need to reload the page in your browser to see the changes. -``` -$ npm start -``` - -Note that `bundle.js` will contain your application code and all dependencies used in your application. From OpenLayers, it only contains the required components. diff --git a/doc/tutorials/bundle.md b/doc/tutorials/bundle.md new file mode 100644 index 0000000000..7009d27203 --- /dev/null +++ b/doc/tutorials/bundle.md @@ -0,0 +1,93 @@ +--- +title: Basic project setup using NPM and Parcel +layout: doc.hbs +--- + +# Introduction + +Modern JavaScript works best when using and authoring modules. The recommended way of using OpenLayers is installing the [`ol`](https://npmjs.com/package/ol) package. This tutorial walks you through setting up a simple dev environment, which requires [node](https://nodejs.org) for everything to work. + +In this tutorial, we will be using [Parcel](https://parceljs.org) to bundle our application. There are several other options, some of which are linked from the [README](https://npmjs.com/package/ol). + +## Initial steps + +Create a new empty directory for your project and navigate to it by running `mkdir new-project && cd new-project`. Initialize your project using `npm init` and answer the questions asked. + +Add OpenLayers as dependency to your application with + + npm install ol + +At this point you can ask NPM to add required development dependencies by running + + npm install --save-dev parcel-bundler + +## Application code and index.html + +Place your application code in `index.js`. Here is a simple starting point: + +```js +import 'ol/ol.css'; +import {Map, View} from 'ol'; +import TileLayer from 'ol/layer/Tile'; +import OSM from 'ol/source/OSM'; + +const map = new Map({ + target: 'map', + layers: [ + new TileLayer({ + source: new OSM() + }) + ], + view: new View({ + center: [0, 0], + zoom: 0 + }) +}); +``` + +You will also need an `ìndex.html` file that will use your bundle. Here is a simple example: + +```html + + + + + Using Parcel with OpenLayers + + + +
+ + + +``` + +## Creating a bundle + +With simple scripts you can introduce the commands `npm run build` and `npm start` to manually build your bundle and watch for changes, respectively. Add the following to the script section in `package.json`: + +```json +"scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "parcel index.html", + "build": "parcel build --public-url . index.html" +} +``` +That's it. Now to run your application, enter + + npm start + +in your console. To test your application, open http://localhost:1234/ in your browser. Whenever you change something, the page will reload automatically to show the result of your changes. + +Note that a single JavaScript file with all your application code and all dependencies used in your application has been created. From the OpenLayers package, it only contains the required components. + +To create a production bundle of your application, simply type + + npm run build + +and copy the `dist/` folder to your production server. diff --git a/doc/tutorials/concepts.hbs b/doc/tutorials/concepts.hbs index 914352661f..edbb4ec1ef 100644 --- a/doc/tutorials/concepts.hbs +++ b/doc/tutorials/concepts.hbs @@ -6,48 +6,58 @@ layout: doc.hbs # Basic Concepts ## Map -The core component of OpenLayers is the map (`ol.Map`). It is rendered to a `target` container (e.g. a `div` element on the web page that contains the map). All map properties can either be configured at construction time, or by using setter methods, e.g. `setTarget()`. +The core component of OpenLayers is the map (`Map`). It is rendered to a `target` container (e.g. a `div` element on the web page that contains the map). All map properties can either be configured at construction time, or by using setter methods, e.g. `setTarget()`. ```xml
``` ## View -`ol.Map` is not responsible for things like center, zoom level and projection of the map. Instead, these are properties of an `ol.View` instance. +`Map` is not responsible for things like center, zoom level and projection of the map. Instead, these are properties of a `View` instance. ```js - map.setView(new ol.View({ + import View from 'ol/View'; + + map.setView(new View({ center: [0, 0], zoom: 2 })); ``` -An `ol.View` also has a `projection`. The projection determines the coordinate system of the `center` and the units for map resolution calculations. If not specified (like in the above snippet), the default projection is Spherical Mercator (EPSG:3857), with meters as map units. +A `View` also has a `projection`. The projection determines the coordinate system of the `center` and the units for map resolution calculations. If not specified (like in the above snippet), the default projection is Spherical Mercator (EPSG:3857), with meters as map units. The `zoom` option is a convenient way to specify the map resolution. The available zoom levels are determined by `maxZoom` (default: 28), `zoomFactor` (default: 2) and `maxResolution` (default is calculated in such a way that the projection's validity extent fits in a 256x256 pixel tile). Starting at zoom level 0 with a resolution of `maxResolution` units per pixel, subsequent zoom levels are calculated by dividing the previous zoom level's resolution by `zoomFactor`, until zoom level `maxZoom` is reached. ## Source -To get remote data for a layer, OpenLayers uses `ol.source.Source` subclasses. These are available for free and commercial map tile services like OpenStreetMap or Bing, for OGC sources like WMS or WMTS, and for vector data in formats like GeoJSON or KML. +To get remote data for a layer, OpenLayers uses `source/Source` subclasses. These are available for free and commercial map tile services like OpenStreetMap or Bing, for OGC sources like WMS or WMTS, and for vector data in formats like GeoJSON or KML. ```js - var osmSource = new ol.source.OSM(); + import OSM from 'ol/source/OSM'; + + var osmSource = OSM(); ``` ## Layer -A layer is a visual representation of data from a `source`. OpenLayers has three basic types of layers: `ol.layer.Tile`, `ol.layer.Image` and `ol.layer.Vector`. +A layer is a visual representation of data from a `source`. OpenLayers has four basic types of layers: `layer/Tile`, `layer/Image`, `layer/Vector` and `layer/VectorTile`. -`ol.layer.Tile` is for layer sources that provide pre-rendered, tiled images in grids that are organized by zoom levels for specific resolutions. +`layer/Tile` is for layer sources that provide pre-rendered, tiled images in grids that are organized by zoom levels for specific resolutions. -`ol.layer.Image` is for server rendered images that are available for arbitrary extents and resolutions. +`layer/Image` is for server rendered images that are available for arbitrary extents and resolutions. -`ol.layer.Vector` is for vector data that is rendered client-side. +`layer/Vector` is for vector data that is rendered client-side. + +`layer/VectorTile` is for tiled vector data that is rendered client-side. ```js - var osmLayer = new ol.layer.Tile({source: osmSource}); + import TileLayer from 'ol/layer/Tile'; + + var osmLayer = new TileLayer({source: osmSource}); map.addLayer(osmLayer); ``` @@ -59,11 +69,16 @@ The above snippets can be conflated to a self contained map configuration with v ```xml
-``` +```js +import proj4 from 'proj4'; +import {get as getProjection, register} from 'ol/proj'; -``` javascript proj4.defs('EPSG:27700', '+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 ' + '+x_0=400000 +y_0=-100000 +ellps=airy ' + '+towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 ' + '+units=m +no_defs'); -var proj27700 = ol.proj.get('EPSG:27700'); +register(proj4); +var proj27700 = getProjection('EPSG:27700'); proj27700.setExtent([0, 0, 700000, 1300000]); ``` ### Change of the view projection -To switch the projection used to display the map you have to set a new `ol.View` with selected projection on the `ol.Map`: +To switch the projection used to display the map you have to set a new `ol/View` with selected projection on the `ol/Map`: ``` javascript -map.setView(new ol.View({ +map.setView(new View({ projection: 'EPSG:27700', center: [400000, 650000], zoom: 4 @@ -69,16 +76,16 @@ map.setView(new ol.View({ ## TileGrid and Extents When reprojection is needed, new tiles (in the target projection) are under the hood created from the original source tiles. -The TileGrid of the reprojected tiles is by default internally constructed using `ol.tilegrid.getForProjection(projection)`. +The TileGrid of the reprojected tiles is by default internally constructed using `ol/tilegrid~getForProjection(projection)`. The projection should have extent defined (see above) for this to work properly. -Alternatively, a custom target TileGrid can be constructed manually and set on the source instance using `ol.source.TileImage#setTileGridForProjection(projection, tilegrid)`. +Alternatively, a custom target TileGrid can be constructed manually and set on the source instance using `ol/source/TileImage~setTileGridForProjection(projection, tilegrid)`. This TileGrid will then be used when reprojecting to the specified projection instead of creating the default one. In certain cases, this can be used to optimize performance (by tweaking tile sizes) or visual quality (by specifying resolutions). # How it works -The reprojection process is based on triangles -- the target raster is divided into a limited number of triangles with vertices transformed using `ol.proj` capabilities ([proj4js](http://proj4js.org/) is usually utilized to define custom transformations). +The reprojection process is based on triangles -- the target raster is divided into a limited number of triangles with vertices transformed using `ol/proj` capabilities ([proj4js](http://proj4js.org/) is usually utilized to define custom transformations). The reprojection of pixels inside the triangle is approximated with an affine transformation (with rendering hardware-accelerated by the canvas 2d context): How it works @@ -122,7 +129,7 @@ Setting such a limit is demonstrated in the [reprojection demo example](https:// ### Resolution calculation When determining source tiles to load, the ideal source resolution needs to be calculated. -The `ol.reproj.calculateSourceResolution(sourceProj, targetProj, targetCenter, targetResolution)` function calculates the ideal value in order to achieve pixel mapping as close as possible to 1:1 during reprojection, which is then used to select proper zoom level from the source. +The `ol/reproj~calculateSourceResolution(sourceProj, targetProj, targetCenter, targetResolution)` function calculates the ideal value in order to achieve pixel mapping as close as possible to 1:1 during reprojection, which is then used to select proper zoom level from the source. It is, however, generally not practical to use the same source zoom level for the whole target zoom level -- different projections can have significantly different resolutions in different parts of the world (e.g. polar regions in EPSG:3857 vs EPSG:4326) and enforcing a single resolution for the whole zoom level would result in some tiles being scaled up/down, possibly requiring a huge number of source tiles to be loaded. Therefore, the resolution mapping is calculated separately for each reprojected tile (in the middle of the tile extent). diff --git a/src/ol/package.json b/src/ol/package.json index 2ccdaa47b2..b93f471c77 100644 --- a/src/ol/package.json +++ b/src/ol/package.json @@ -10,4 +10,4 @@ "pixelworks": "1.1.0", "rbush": "2.0.2" } -} \ No newline at end of file +}