Created Use Cases (markdown)

Use-Cases.md

@@ -0,0 +1,81 @@
+# Vector Use Cases
+
+These use cases describe common scenarios for loading, rendering, and editing vector data.
+
+## Load data once from static file
+
+User has a static file (e.g. GeoJSON) hosted on the same origin as their application.  User expects data to be loaded and rendered over a raster tile based layer (e.g. WMS).  Data may be in a different coordinate reference system than map.
+
+**Alternative 1**
+
+```js
+var raster = new ol.layer.TileLayer({
+  source: new ol.source.TiledWMS({
+    url: 'http://demo.opengeo.org/geoserver/wms',
+    params: {'LAYERS': 'topp:states', 'TILED': true}
+  })
+});
+
+// assume features.json is a FeatureCollection in EPSG:4326
+var vector = new ol.layer.Vector({
+  source: new ol.source.Vector({
+    protocol: new ol.protocol.HTTP({
+      url: './data/features.json'
+    }),
+    parser: new ol.parser.GeoJSON()
+  })
+});
+
+var map = new ol.Map({
+  target: 'map',
+  layers: [raster, vector],
+  view: new ol.View2D({
+    projection: 'EPSG:1234',
+    center: ol.projection.transform(
+        new ol.Coordinate(139.7, 35.7), 'EPSG:4326', 'EPSG:1234'),
+    zoom: 9
+  })
+});
+```
+
+This alternative can be implemented if the layer knows the map projection.  The vector layer would be responsible for calling `source.protocol.read({success: callback})` where the callback would call `source.parser.parseFeatures(data, {projection: projection})` (`data` is supplied to the callback and `projection` comes from the map's view).  The layer would maintain a cache of features in the map view's projection, and these would be provided on demand to layer's the renderer.
+
+## Generate features in app and add to a layer
+
+User writes an application that generates features at run time.  These features are added to the layer for display and interaction (e.g. popup on selection).
+
+**Alternative 1**
+
+```js
+// a vector layer with no source means user will be manually adding features
+var vector = new ol.layer.Vector();
+
+var map = new ol.Map({
+  target: 'map',
+  layers: [vector]
+  view: new ol.View2D({
+    projection: 'EPSG:1234',
+    center: ol.projection.transform(
+        new ol.Coordinate(-111, 45), 'EPSG:4326', 'EPSG:1234'),
+    zoom: 3
+  })
+});
+
+var parser = new ol.parser.GeoJSON();
+
+vector.addFeatures(parser, {
+  type: 'FeatureCollection',
+  features: [{
+    type: 'Feature',
+    geometry: {
+      type: 'Point',
+      coordinates: [-111, 45]
+    },
+    properties: {
+      foo: 'bar'
+    }
+  }]
+});
+```
+
+In this alternative, the vector layer has no source set - meaning the user will be manually generating features.  This alternative can be implemented if the layer knows about the map projection.  In the `addFeatures` method, the layer would call `parser.readFeatures(data, {projection: projection})` where `data` is the first argument to `addFeatures` and `projection` is the map view's projection.