diff --git a/apidoc/template/tmpl/layout.tmpl b/apidoc/template/tmpl/layout.tmpl index 6fab32deef..dbecd6f857 100644 --- a/apidoc/template/tmpl/layout.tmpl +++ b/apidoc/template/tmpl/layout.tmpl @@ -21,7 +21,7 @@ diff --git a/doc/index.hbs b/doc/index.hbs new file mode 100644 index 0000000000..ee1051ae3d --- /dev/null +++ b/doc/index.hbs @@ -0,0 +1,12 @@ +--- +title: Documentation +layout: doc.hbs +--- + +# Documentation + +If you're eager to get your first OpenLayers 3 map on a page, dive into the [quick start](quickstart.html). + +For a more in-depth overview of OpenLayers 3 core concepts, check out the [tutorials](tutorials/). + +Find additional reference material in the [API docs](../apidoc). diff --git a/doc/quickstart.hbs b/doc/quickstart.hbs new file mode 100644 index 0000000000..dbc37808fe --- /dev/null +++ b/doc/quickstart.hbs @@ -0,0 +1,132 @@ +--- +title: Quick Start +layout: doc.hbs +--- + +# Quick Start + +## 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: + +```xml + + + + + + + OpenLayers 3 example + + +

My Map

+
+ + + +``` + +## Understanding what is going on + +To include a map a web page you will need 3 things: + + 1. Include OpenLayers + 2. `
` map container + 3. JavaScript to create a simple map + +### Include OpenLayers + +```xml + +``` + +The first part is to include the JavaScript library. For the purpose of this tutorial, here we simply point to the ol3js.org website to get the whole library. In a production environment, we would build a custom version of the library including only the module needed for our application. + + +### `
` to contain the map + +```xml +
+``` + +The map in the application is contained in a [`
` HTML element](http://en.wikipedia.org/wiki/Span_and_div). Through this `
` the map properties like width, height and border can be controlled through CSS. Here's the CSS element used to make the map 400 pixels high and as wide as the browser window. + +```xml + +``` + +### JavaScript to create a simple map + +```js + var map = new ol.Map({ + target: 'map', + layers: [ + new ol.layer.Tile({ + source: new ol.source.MapQuestOpenAerial() + }) + ], + view: new ol.View2D({ + center: ol.proj.transform([37.41, 8.82], 'EPSG:4326', 'EPSG:3857'), + zoom: 4 + }) + }); +``` + +With this JavaScript code, a map object is created with a MapQuest Open Aerial layer zoomed on the African East coast. Let's break this down: + +The following line creates an OpenLayers `Map` object. Just by itself, this does nothing since there's no layers or interaction attached to it. + +```js + var map = new ol.Map({ ... }); +``` + +To attach the map object to the `
`, the map object takes a `target` into arguments. The value is the `id` of the `
`: + +```js + target: 'map' +``` + +The `layers: [ ... ]` array is used to define the list of layers available in the map. The first and only layer right now is a tiled layer: + +```js + layers: [ + new ol.layer.Tile({ + source: new ol.source.MapQuestOpenAerial() + }) + ] +``` + +Layers in OpenLayers 3 are defined with a type (Image, Tile or Vector) which contains a source. The source is the protocol used to get the map tiles. You can consult the list of [available layer sources here](/en/{{ latest }}/apidoc/ol.source.html) + +The next part of the `Map` object is the `View`. The view allow to specify the center, resolution, and rotation of the map. Right now, only `View2D` is supported, but other views should be available at some point. The simplest way to define a view is to define a center point and a zoom level. Note that zoom level 0 is zoomed out. + +```js + view: new ol.View2D({ + center: ol.proj.transform([37.41, 8.82], 'EPSG:4326', 'EPSG:3857'), + zoom: 4 + }) +``` + +You will notice that the `center` specified is in lat/lon coordinates (EPSG:4326). Since the only layer we use is in Spherical Mercator projection (EPSG:3857), we can reproject them on the fly to be able to zoom the map on the right coordinates. diff --git a/doc/tutorials/concepts.hbs b/doc/tutorials/concepts.hbs new file mode 100644 index 0000000000..09110938c5 --- /dev/null +++ b/doc/tutorials/concepts.hbs @@ -0,0 +1,73 @@ +--- +title: Basic Concepts +layout: doc.hbs +--- + +# Basic Concepts + +## Map +The core component of OpenLayers 3 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()`. + +```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 - typically an `ol.View2D` for 2D maps. The reason for this abstraction is the idea of instantly switching e.g. between a 2D and a tilted 3D view, without the need to maintain two copies of the `layers`. + +```js + map.setView(new ol.View2D({ + center: [0, 0], + zoom: 2 + })); +``` + +An `ol.View2D` 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 3 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. + +```js + var osmSource = new ol.source.OSM(); +``` + +## Layer +A layer is a visual representation of data from a `source`. OpenLayers 3 has three basic types of layers: `ol.layer.Tile`, `ol.layer.Image` and `ol.layer.Vector`. + +`ol.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. + +`ol.layer.Vector` is for vector data that is rendered client-side. + +```js + var osmLayer = new ol.layer.Tile({source: osmSource}); + map.addLayer(osmLayer); +``` + +## Putting it all together + + +The above snippets can be conflated to a self contained map configuration with view and layers: + +```xml +
+ +``` diff --git a/doc/tutorials/index.hbs b/doc/tutorials/index.hbs new file mode 100644 index 0000000000..2ac1298a88 --- /dev/null +++ b/doc/tutorials/index.hbs @@ -0,0 +1,8 @@ +--- +title: Tutorials +layout: doc.hbs +--- + +# Tutorials + +We'll be putting together a more comprehensive set of tutorials here. For now, you can take a look at the [basic concepts](concepts.html) tutorial. Stay tuned for more! diff --git a/examples/accessible.html b/examples/accessible.html index 2f54c51911..94339ed9ac 100644 --- a/examples/accessible.html +++ b/examples/accessible.html @@ -20,7 +20,7 @@ diff --git a/examples/animation.html b/examples/animation.html index 60d6f937fd..f8f7d2c1ff 100644 --- a/examples/animation.html +++ b/examples/animation.html @@ -15,7 +15,7 @@ diff --git a/examples/bind-input.html b/examples/bind-input.html index c5015ddc7f..3418fbf246 100644 --- a/examples/bind-input.html +++ b/examples/bind-input.html @@ -15,7 +15,7 @@ diff --git a/examples/bing-maps.html b/examples/bing-maps.html index 0b11b7e66c..c038972c4c 100644 --- a/examples/bing-maps.html +++ b/examples/bing-maps.html @@ -15,7 +15,7 @@ diff --git a/examples/brightness-contrast.html b/examples/brightness-contrast.html index 07b42173a5..80dc70f757 100644 --- a/examples/brightness-contrast.html +++ b/examples/brightness-contrast.html @@ -23,7 +23,7 @@ diff --git a/examples/canvas-tiles.html b/examples/canvas-tiles.html index e896536fc8..51f97905f9 100644 --- a/examples/canvas-tiles.html +++ b/examples/canvas-tiles.html @@ -15,7 +15,7 @@ diff --git a/examples/custom-controls.html b/examples/custom-controls.html index 766941a871..9cf24d173b 100644 --- a/examples/custom-controls.html +++ b/examples/custom-controls.html @@ -51,7 +51,7 @@ diff --git a/examples/device-orientation.html b/examples/device-orientation.html index 0fb7ba701a..470b06839d 100644 --- a/examples/device-orientation.html +++ b/examples/device-orientation.html @@ -15,7 +15,7 @@ diff --git a/examples/drag-rotate-and-zoom.html b/examples/drag-rotate-and-zoom.html index e3c2df70d8..3111e8ef8f 100644 --- a/examples/drag-rotate-and-zoom.html +++ b/examples/drag-rotate-and-zoom.html @@ -15,7 +15,7 @@ diff --git a/examples/epsg-4326.html b/examples/epsg-4326.html index 9e55b944cb..91439320e5 100644 --- a/examples/epsg-4326.html +++ b/examples/epsg-4326.html @@ -15,7 +15,7 @@ diff --git a/examples/export-map.html b/examples/export-map.html index 334b02238f..14076fe011 100644 --- a/examples/export-map.html +++ b/examples/export-map.html @@ -15,7 +15,7 @@ diff --git a/examples/full-screen-drag-rotate-and-zoom.html b/examples/full-screen-drag-rotate-and-zoom.html index 84eb71902c..8ef61c96ba 100644 --- a/examples/full-screen-drag-rotate-and-zoom.html +++ b/examples/full-screen-drag-rotate-and-zoom.html @@ -26,7 +26,7 @@ diff --git a/examples/full-screen.html b/examples/full-screen.html index 89af0abe72..d641ce5938 100644 --- a/examples/full-screen.html +++ b/examples/full-screen.html @@ -26,7 +26,7 @@ diff --git a/examples/geolocation.html b/examples/geolocation.html index 34553bbe60..44e31c630b 100644 --- a/examples/geolocation.html +++ b/examples/geolocation.html @@ -24,7 +24,7 @@ diff --git a/examples/getfeatureinfo.html b/examples/getfeatureinfo.html index 1997d916b8..16446f0cfd 100644 --- a/examples/getfeatureinfo.html +++ b/examples/getfeatureinfo.html @@ -15,7 +15,7 @@ diff --git a/examples/gml.html b/examples/gml.html index beacda13e4..9f43183b3e 100644 --- a/examples/gml.html +++ b/examples/gml.html @@ -15,7 +15,7 @@ diff --git a/examples/gpx.html b/examples/gpx.html index cc3f23738d..f0997c44fb 100644 --- a/examples/gpx.html +++ b/examples/gpx.html @@ -15,7 +15,7 @@ diff --git a/examples/hue-saturation.html b/examples/hue-saturation.html index c1c1967025..9c90d64c9a 100644 --- a/examples/hue-saturation.html +++ b/examples/hue-saturation.html @@ -23,7 +23,7 @@ diff --git a/examples/icon.html b/examples/icon.html index de344d6861..0471245a5d 100644 --- a/examples/icon.html +++ b/examples/icon.html @@ -23,7 +23,7 @@ diff --git a/examples/index.html b/examples/index.html index 191dd2fa3f..41d41eb105 100644 --- a/examples/index.html +++ b/examples/index.html @@ -20,6 +20,9 @@ .example:hover { background-color: #ddd; } + .navbar-search.pull-left { + padding: 5px; + } ::-webkit-scrollbar { width: 8px; @@ -175,7 +178,7 @@