[Commits] r662 - sandbox/docsrc/tutorials

[commits at geoext.org]

Author: tcoulter
Date: 2009-05-08 20:54:03 +0200 (Fri, 08 May 2009)
New Revision: 662

Modified:
   sandbox/docsrc/tutorials/openlayers-primer.rst
Log:
Added the 'Control' section. One more to go.

Modified: sandbox/docsrc/tutorials/openlayers-primer.rst
===================================================================
--- sandbox/docsrc/tutorials/openlayers-primer.rst	2009-05-08 13:45:34 UTC (rev 661)
+++ sandbox/docsrc/tutorials/openlayers-primer.rst	2009-05-08 18:54:03 UTC (rev 662)
@@ -43,7 +43,7 @@
        );
        map.addLayer(layer);
     
-This tells OpenLayers that you'd like to create a new WMS layer referenced by the 'layer' variable, and that you'd like to add that layer
+This tells OpenLayers that you'd like to create a new WMS layer referenced by the ``layer`` variable, and that you'd like to add that layer
 to the map. In this case, we're adding the `Blue Marble data set provided by NASA <http://earthobservatory.nasa.gov/Features/BlueMarble/>`_
        
 The first parameter ("Blue Marble") represents the name of the layer. This can be anything, and is only used to reference the layer on screen.
@@ -52,10 +52,10 @@
 sigma.openplans.org.
 
 The third parameter lets you override the parameters of every request passed to the WMS server. Since many servers host different 
-data sets, we need to specify which set we'd like: We do this by creating a new object and setting the 'layers' key to the identifier 
+data sets, we need to specify which set we'd like: We do this by creating a new object and setting the ``layers`` key to the identifier 
 of our Blue Marble data set.
 
-Note that 'layers' isn't the only WMS parameter we can override. You can find out more in the
+Note that ``layers`` isn't the only WMS parameter we can override. You can find out more in the
 `OpenLayers Class Documentation <http://dev.openlayers.org/apidocs/>`_, by selecting 'Layer' and then 'WMS' in the navigation.
 
 And that's it! Now let's move onto WFS.
@@ -84,8 +84,8 @@
        );
        map.addLayer(layer);
        
-Like the WMS layer, the paramaters contain a layer name ("United States"), the url of the data provider and options for the WFS request.
-In this case, we're requesting the 'topp:states' layer so it can be rendered in the browser by OpenLayers.
+Like the WMS layer, the parameters contain a layer name ("United States"), the url of the data provider and options for the WFS request.
+In this case, we're requesting the ``'topp:states'`` layer so it can be rendered in the browser by OpenLayers.
 
 This layers extends the `Vector Layer <http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Layer/Vector.js>`_.
 
@@ -96,14 +96,91 @@
 `Browse the OpenLayers source code <http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Layer>`_ for more information. 
 
        
-
-
 Controls
 ========
 
-all about controls
+Although OpenLayers is great at managing layers, it also provides a way to interact with those layers, primarily through the use of controls.
 
+Controls are primary user interface elements and/or API hooks that control and manage interaction with an OpenLayers map. For instance, panning
+and navigating a map is handled by the ``Navigation`` control. If you want a zoom bar in addition to zoom buttons, you'd add a ``PanZoomBar``
+control. If you then want to see where you've navigated, you'd use the ``NavigationHistory`` control.
 
+Each control provides different and unique functionality. For this primer, we'll focus only on the ``NavigationHistory`` control.
+
+
+NavigationHistory Control
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Take a look at the OpenLayers `NavigationHistory control example <http://openlayers.org/dev/examples/navigation-history.html>`_. 
+If you view the source, you'll come across code like this:
+
+    .. code-block::
+       html
+       
+       var map, nav, panel;
+
+       //...
+            
+       map = new OpenLayers.Map('map');
+
+       nav = new OpenLayers.Control.NavigationHistory();
+       map.addControl(nav);
+       
+The above code is fairly straightforward. First create a map, then a ``NavigationHistory`` control, and then finally add that control to the map.
+If you were to then look at your map in a web browser, you would only see the layers that you had added -- no special user interface elements
+for exploring the navigation history.
+
+This is because without more intervention, the NavigationHistory control only provides an API allowing you to scroll through
+the history using a programmable interface.
+
+But the ``NavigationHistory`` control also provides a user interface. Let's continue on through the example:
+
+    .. code-block::
+       html
+       
+       panel = new OpenLayers.Control.Panel(
+           {div: document.getElementById("panel")}
+       );
+       panel.addControls([nav.next, nav.previous]);
+       map.addControl(panel);
+       
+To expose this interface, we first create a ``Panel`` control, and then add the ``next`` and ``previous`` buttons to the panel giving the user 
+something to click on. We finally add the panel to the map.
+
+Now try the example again in your browser. *Beautiful ain't it?*
+
+.. note:: In OpenLayers 3.0, user interface controls will be separated from controls that provide an API. This will bring large
+   changes to the OpenLayers Control API, as well as the NavigationHistory control.
+       
+Initialization w/ Controls
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the above examples, we only added controls to the map using the ``map.addControl()`` method. Often, controls are added when the map
+is initialized bypassing the ``map.addControl()`` method. This is done simply by using the ``controls`` key and passing an array 
+of controls, as seen below.
+
+    .. code-block::
+       html
+       
+       var map = new OpenLayers.Map({
+            controls: [
+                new OpenLayers.Control.Navigation(),
+                new OpenLayers.Control.Measure()
+            ]
+       });
+       
+.. note:: If you use the ``controls`` key, **you will not be given the default controls**  when initializing the map.
+   You will have to add those controls yourself instead. `Find out more. <http://docs.openlayers.org/library/controls.html>`_
+
+More Controls
+~~~~~~~~~~~~~
+
+You can find more controls by 
+`browsing the OpenLayers source code <http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Control>`_, or reading
+`OpenLayers' Control documentation <http://docs.openlayers.org/library/controls.html>`_.
+
+
+
 Events
 ======