[Commits] r924 - core/trunk/docsrc/primers
commits at geoext.org
commits at geoext.org
Sat May 30 00:05:28 CEST 2009
Author: tschaub
Date: 2009-05-30 00:05:28 +0200 (Sat, 30 May 2009)
New Revision: 924
Modified:
core/trunk/docsrc/primers/openlayers-primer.rst
Log:
Tidying up the OL primer.
Modified: core/trunk/docsrc/primers/openlayers-primer.rst
===================================================================
--- core/trunk/docsrc/primers/openlayers-primer.rst 2009-05-29 21:57:36 UTC (rev 923)
+++ core/trunk/docsrc/primers/openlayers-primer.rst 2009-05-29 22:05:28 UTC (rev 924)
@@ -4,50 +4,80 @@
Primer: OpenLayers
====================
-The OpenLayers mapping library is the key component of GeoExt, performing the core map-related functions of every GeoExt-based application. To get up to speed with GeoExt, let's discover some OpenLayers basics.
+The OpenLayers mapping library is the key component of GeoExt, performing the
+core map-related functions of every GeoExt-based application. To get up to speed
+with GeoExt, let's discover some OpenLayers basics.
Layers
======
-As its name suggests, OpenLayers manages a list of layers that together form a web-based mapping client. Each layer represents a different set of data. For instance, one layer might be responsible for displaying the boundary of a country. Another layer responsible for that country's roads.
+As its name suggests, OpenLayers manages a list of layers that together form a
+web-based mapping client. Each layer represents a different set of data. For
+instance, one layer might be responsible for displaying the boundary of a
+country. Another layer responsible for that country's roads.
-OpenLayers contains many types of layers (you can see them all at the `OpenLayers website <http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Layer>`_). For this primer, we'll focus on two different layer types: ``WMS`` and ``Vector``.
+OpenLayers contains many types of layers (you can see them all at the
+`OpenLayers website
+<http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Layer>`_).
+For this primer, we'll focus on two different layer types: ``WMS`` and
+``Vector``.
The WMS Layer
-~~~~~~~~~~~~~
+-------------
-This is the canonical layer type found in almost all GeoExt applications, where one or more images are used to display map-related information to the user. This type is named 'WMS' because it implements the `Web Map Service <http://www.opengeospatial.org/standards/wms>`_ standard set by the `Open Geospatial Consortium. <http://www.opengeospatial.org/>`_
+This is the canonical layer type found in almost all GeoExt applications, where
+one or more images are used to display map-related information to the user. This
+type is named 'WMS' because it implements the `Web Map Service
+<http://www.opengeospatial.org/standards/wms>`_ standard set by the `Open
+Geospatial Consortium. <http://www.opengeospatial.org/>`_
-If you followed the :doc:`/tutorials/quickstart` guide, you will have already encountered a ``MapPanel`` and created your very own WMS layer. Let's dissect what you did:
+If you followed the :doc:`/tutorials/quickstart` guide, you will have already
+encountered a ``MapPanel`` and created your very own WMS layer. Let's dissect
+what you did:
- .. code-block::
- javascript
- :linenos:
-
- var layer = new OpenLayers.Layer.WMS(
- "Blue Marble",
- "http://sigma.openplans.org/geoserver/wms?",
- {layers: "bluemarble"}
- );
- map.addLayer(layer);
+ .. code-block:: javascript
+ :linenos:
-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 <http://earthobservatory.nasa.gov/Features/BlueMarble/>`_ provided by NASA.
+ var layer = new OpenLayers.Layer.WMS(
+ "Global Imagery",
+ "http://demo.opengeo.org/geoserver/wms",
+ {layers: "bluemarble"}
+ );
+ 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 to the map. In
+this case, we're adding the `Blue Marble data set
+<http://earthobservatory.nasa.gov/Features/BlueMarble/>`_ provided by NASA.
-In **line 2** we provide "Blue Marble" as the name of the layer. This can be anything, and is only used to reference the layer on screen.
+In **line 2** we provide "Blue Marble" as the name of the layer. This can be
+anything, and is only used to reference the layer on screen.
-In **line 3** we provide the location of the WMS server tasked with providing the images. Here, we use a GeoServer instance located at ``sigma.openplans.org``\ .
+In **line 3** we provide the location of the WMS server tasked with providing
+the images. Here, we use a GeoServer instance located at
+``sigma.openplans.org``\ .
-In **line 4** we provide extra parameters for 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`` property to ``"bluemarble"``\ , the identifier for the Blue Marble data set.
+In **line 4** we provide extra parameters for 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`` property to ``"bluemarble"``\ ,
+the identifier for the Blue Marble data set.
-Note that ``layers`` isn't the only WMS parameter we can provide. You can find out more in the `OpenLayers API Documentation`_, by selecting 'Layer' and then 'WMS' in the navigation.
+Note that ``layers`` isn't the only WMS parameter we can provide. You can find
+out more in the `OpenLayers API Documentation`_, by selecting 'Layer' and then
+'WMS' in the navigation.
And that's it! Now let's move on to the vector layer.
The Vector Layer
-~~~~~~~~~~~~~~~~
+----------------
-The WMS Layer, and many of the layer types provided by OpenLayers, use raster files (images like JPG, GIF, and PNG) to display maps. However, OpenLayers can also render map features directly in the browser, simply by adding an ``OpenLayers.Layer.Vector`` to the map. This is useful when displaying data from an OGC `Web Feature Service <http://www.opengeospatial.org/standards/wfs>`, a KML document, or even sketched in by the user. Here's an example that generates some random data and displays it in a vector layer::
+The WMS Layer, and many of the layer types provided by OpenLayers, use raster
+files (images like JPG, GIF, and PNG) to display maps. However, OpenLayers can
+also render map features directly in the browser, simply by adding an
+``OpenLayers.Layer.Vector`` to the map. This is useful when displaying data from
+an OGC `Web Feature Service <http://www.opengeospatial.org/standards/wfs>`, a
+KML document, or even sketched in by the user. Here's an example that generates
+some random data and displays it in a vector layer::
var vectorLayer = new OpenLayers.Layer.Vector();
for (var i = 0; i < 10; i++){
@@ -64,59 +94,69 @@
var map = new OpenLayers.Map();
map.addLayer(vectorLayer);
-While OpenLayers provides customized vector layers for loading data from existing sources, the GeoExt team recommends that you use the generic vector layer and populate it using :class:`GeoExt.data.FeatureStore`\ . For more information on doing this, see :doc:`/tutorials/remote-features-tutorial`\ .
+While OpenLayers provides customized vector layers for loading data from
+existing sources, the GeoExt team recommends that you use the generic vector
+layer and populate it using :class:`GeoExt.data.FeatureStore`\ . For more
+information on doing this, see :doc:`/tutorials/remote-features-tutorial`\ .
Other Layers
------------
-WMS and Vector are not the only layer types in OpenLayers. There are plenty more available, including Google Maps, Virtual Earth, and many more. Browse the `OpenLayers API documentation <http://dev.openlayers.org/apidocs>`_ for more information.
+WMS and Vector are not the only layer types in OpenLayers. There are plenty more
+available, including Google Maps, Virtual Earth, and many more. Browse the
+`OpenLayers API documentation <http://dev.openlayers.org/apidocs>`_ for more
+information.
Controls
========
-Although OpenLayers is great at managing layers, it also provides a way to interact with those layers, primarily through the use of 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 ``OpenLayers.Control.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.
+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 ``OpenLayers.Control.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.
+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:
+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
+ .. code-block:: javascript
- var map, nav, panel;
-
- //...
-
- map = new OpenLayers.Map('map');
-
- nav = new OpenLayers.Control.NavigationHistory();
- map.addControl(nav);
+ var map = new OpenLayers.Map('map');
+ var 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.
+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.
+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:
+But the ``NavigationHistory`` control also provides a user interface. Let's
+continue on through the example:
- .. code-block::
- html
+ .. code-block:: javascript
- panel = new OpenLayers.Control.Panel(
- {div: document.getElementById("panel")}
- );
- panel.addControls([nav.next, nav.previous]);
- map.addControl(panel);
+ 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.
@@ -124,27 +164,26 @@
Now try the example again in your browser. *Beautiful ain't it?*
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
+ .. code-block:: javascript
- var map = new OpenLayers.Map({
+ 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 by reading
@@ -164,7 +203,7 @@
GeoExt, though they provide the same functionality. Let's explore those differences.
GeoExt Events
-~~~~~~~~~~~~~
+-------------
GeoExt uses the event library that comes standard with Ext. GeoExt events are synonymous with Ext events.
@@ -174,53 +213,49 @@
To throw an event in any component that extends ``Ext.util.Observable``, you must first tell the component that the event may be thrown.
For instance, in a custom ``Ext.Panel`` class, this is done using the ``addEvents()`` method below.
- .. code-block::
- html
+ .. code-block:: javascript
- var MyPanel = Ext.Extend(Ext.Panel, {
+ var MyPanel = Ext.Extend(Ext.Panel, {
initComponent: function() {
// ...
this.addEvents("event1" /*, "event2", ... etc.*/ );
MyPanel.superclass.initComponent.call(this);
}
- });
+ });
Finally triggering the event is easy:
- .. code-block::
- html
+ .. code-block:: javascript
- var MyPanel = Ext.Extend(Ext.Panel, {
-
+ var MyPanel = Ext.Extend(Ext.Panel, {
+
// ...
-
+
myFunction: function() {
- var arg1 = "somevalue"
-
+ var arg1 = "somevalue";
this.fireEvent("event1", arg1 /*, arg2, ... etc. */);
}
- });
+ });
Great! Now in order for the event to be useful, we have to listen to it. Below is an example of adding two listeners to an instance
of ``MyPanel`` using the ``on()`` function, and then finally triggering the event by calling ``myFunction()``.
- .. code-block::
- html
+ .. code-block:: javascript
- var panel = new MyPanel(/* ... */);
-
- // First listener.
- panel.on("event1", function(arg1) {
+ var panel = new MyPanel(/* ... */);
+
+ // First listener.
+ panel.on("event1", function(arg1) {
alert("First listener responded. Got " + arg1 + "!");
- });
-
- // Second listener.
- panel.on("event1", function(arg1) {
+ });
+
+ // Second listener.
+ panel.on("event1", function(arg1) {
alert("Second listener responded. Got " + arg1 + "!");
- });
-
- panel.myFunction();
+ });
+
+ panel.myFunction();
.. note:: The ``on()`` function takes an optional third parameter that specifies the scope of the listening function. If given, the ``this``
identifier within the listening function will refer to the object passed.
@@ -228,7 +263,7 @@
And that's it! Now let's see how to do the same thing in OpenLayers.
OpenLayers Events
-~~~~~~~~~~~~~~~~~
+-----------------
OpenLayers provides similar functionality as the ``Ext.util.Observable`` class, but it does so using the ``OpenLayers.Events`` class.
Unlike ``Ext.util.Observable``, OpenLayers classes do not extend ``OpenLayers.Events``.
@@ -236,11 +271,10 @@
Instead, it is customary for OpenLayers classes to create an attribute called ``events`` that is an instance of ``OpenLayers.Events``,
as per the code below.
- .. code-block::
- html
+ .. code-block:: javascript
- var MyControl = new OpenLayers.Class(OpenLayers.Control, {
-
+ var MyControl = new OpenLayers.Class(OpenLayers.Control, {
+
events: null,
initialize: function() {
@@ -253,7 +287,7 @@
OpenLayers.Control.prototype.initialize.call(this);
}
- });
+ });
The first parameter to the ``OpenLayers.Events`` constructor is the object that will 'own' these events -- in other words, the caller
that triggers the event. In situations like the example above, it is usually ``this``.
@@ -273,10 +307,9 @@
Triggering an event is just as easy as Ext's ``fireEvent()``, except here we use ``triggerEvent()``:
- .. code-block::
- html
+ .. code-block:: javascript
- var MyControl = new OpenLayers.Class(OpenLayers.Control, {
+ var MyControl = new OpenLayers.Class(OpenLayers.Control, {
// ...
@@ -286,7 +319,7 @@
}
this.events.triggerEvent("event1", evt);
}
- });
+ });
.. note:: ``OpenLayers.Events`` passes data to listeners using a single object with parameters -- otherwise called
'the event object' -- instead of passing function arguments like Ext. All listener functions, then, should only expect
@@ -294,22 +327,21 @@
Finally, let's add two listeners and call ``myFunction()``:
- .. code-block::
- html
+ .. code-block:: javascript
- var control = new MyControl(/* ... */);
-
- // First listener.
- control.events.register("event1", null, function(evt) {
+ var control = new MyControl(/* ... */);
+
+ // First listener.
+ control.events.register("event1", null, function(evt) {
alert("First listener responded. Got " + evt.arg1 + "!");
- });
+ });
- // Second listener.
- control.events.register("event1", null, function(evt) {
+ // Second listener.
+ control.events.register("event1", null, function(evt) {
alert("Second listener responded. Got " + evt.arg1 + "!");
- });
+ });
- control.myFunction();
+ control.myFunction();
.. note:: Like Ext's ``on()`` function, OpenLayer's ``register()`` function also takes an optional ``scope`` value in order to specify
the scope of the listening function, but it expects this value as the second parameter passed to the function.
@@ -318,7 +350,7 @@
And that's it! Events in GeoExt should now be old hat. Fire away!
More Information
-~~~~~~~~~~~~~~~~
+----------------
More information about both event types can be found at the links below:
More information about the Commits
mailing list