[Commits] r690 - in sandbox/docsrc: . primers tutorials
commits at geoext.org
commits at geoext.org
Tue May 12 21:52:13 CEST 2009
Author: dwins
Date: 2009-05-12 21:52:13 +0200 (Tue, 12 May 2009)
New Revision: 690
Added:
sandbox/docsrc/primers/
sandbox/docsrc/primers/ext-primer.rst
sandbox/docsrc/primers/openlayers-primer.rst
Removed:
sandbox/docsrc/tutorials/ext-primer.rst
sandbox/docsrc/tutorials/openlayers-primer.rst
Log:
Reorganize primer materials
Copied: sandbox/docsrc/primers/ext-primer.rst (from rev 689, sandbox/docsrc/tutorials/ext-primer.rst)
===================================================================
--- sandbox/docsrc/primers/ext-primer.rst (rev 0)
+++ sandbox/docsrc/primers/ext-primer.rst 2009-05-12 19:52:13 UTC (rev 690)
@@ -0,0 +1,105 @@
+.. _ext-primer:
+
+=============
+ Primer: Ext
+=============
+
+GeoExt extends `Ext JS <http://extjs.com/>`_, a rich library of web UI
+widgets and helper classes. Using GeoExt requires a working knowledge
+of Ext's idioms. This tutorial provides a quick overview of core Ext concepts.
+
+.. _ext-getting-started:
+
+Getting Started
+===============
+
+To start using Ext, you will first have to `download
+<http://www.extjs.com/products/extjs/download.php>`_ it.
+For more complete instructions about how configure a web page to use
+Ext, you can check the GeoExt :doc:`quickstart` tutorial.
+
+When you download Ext, you also get their excellent `Examples <http://www.extjs.com/deploy/dev/examples/>'_ and 'API
+Documentation <http://www.extjs.com/deploy/dev/docs/>`_, which you can also look at on-line for education and reference.
+
+In order to get Ext running on a page you will need to have something
+like the following in the ``<head>`` of an HTML page in a directory
+that is published by your web server.
+
+ .. code-block::
+ xml
+
+ <script src="ext-2.2/adapter/ext/ext-base.js" type="text/javascript"></script>
+ <script src="ext-2.2/ext-all.js" type="text/javascript"></script>
+ <link rel="stylesheet" type="text/css" href="ext-2.2/resources/ext-all.css"></link>
+
+This will load the code and styles for Ext. Change the paths
+according to where you have put the Ext files.
+
+When writing Ext code, most of what you will be doing is instantiating
+classes with constructors that takes a single object--its
+configuration object--as an argument. This snippet demonstrates this
+coding pattern:
+
+ .. code-block::
+ html
+
+ Ext.onReady(function(){
+ var myPanel = new Ext.Panel({
+ title: 'Hello World!',
+ html: '<i>Hello World!</i> Please enjoy this primer on Ext!'
+ collapsible: true,
+ width:500,
+ renderTo: 'panelDiv',
+ });
+ };
+
+This code uses Ext's ``onReady`` method to trigger the method when the
+document's body is ready. (This is cleaner than using body's
+``onready`` event, and with ``Ext.onReady`` several functions can be
+queued for execution before the page loads.)
+
+When the page is ready, the ``Ext.Panel`` constructor is called with a
+single configuration object as argument. The Panel's structure should
+be familiar from your desktop experience. It has a ``title`` which
+runs across the top, and some content which in this case is ``html``
+provided in the configuration.
+
+Many configuration options (best explored in the Ext examples and API
+documention) are available. Here, they are represented by the
+``collapsible`` property, which allows the user to collapse the panel
+much like you can minimize your browser's window, and the ``width`` of
+the panel specified in pixels.
+
+Lastly, this code assumes that somewhere in the DOM of the page is a
+``div`` with the id ``panelDiv``. When the Panel is constructed, it
+will be automatically rendered in this div because of the ``renderTo``
+option. (This option can be left out and panels rendered manually, if desired.)
+
+.. _ext-basic-layout:
+
+Basic Layout
+============
+
+Ext makes it easy to separate out your UI into logical blocks. It
+
+.. _ext-trees:
+
+Trees, Nodes, and Childnodes
+============================
+
+[tba]
+
+.. _ext-grid-store:
+
+Grid and Store
+==============
+
+[working with records from a reader]
+
+
+.. _ext-events:
+
+Events
+======
+
+[from a geoxt perspective]
Property changes on: sandbox/docsrc/primers/ext-primer.rst
___________________________________________________________________
Name: svn:mergeinfo
+
Copied: sandbox/docsrc/primers/openlayers-primer.rst (from rev 689, sandbox/docsrc/tutorials/openlayers-primer.rst)
===================================================================
--- sandbox/docsrc/primers/openlayers-primer.rst (rev 0)
+++ sandbox/docsrc/primers/openlayers-primer.rst 2009-05-12 19:52:13 UTC (rev 690)
@@ -0,0 +1,353 @@
+====================
+ 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.
+
+Layers
+======
+
+As its name suggests, OpenLayers manages a list of layers that together form a web-based
+mapping client. Each layer represents a different piece 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 WFS.
+
+WMS
+~~~
+
+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:`quickstart` guide in GeoExt under the heading 'Using GeoExt', you will have already encountered a MapPanel and created
+your very own WMS layer. Let's dissect what you did.
+
+new OpenLayers.Layer.WMS()
+--------------------------
+
+After creating an OpenLayers Map (but before creating a GeoExt MapPanel), you encountered the following code:
+
+ .. code-block::
+ html
+
+ var layer = new OpenLayers.Layer.WMS(
+ "Blue Marble",
+ "http://sigma.openplans.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 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.
+
+The second parameter represents the location of the WMS server tasked with providing the images. We're using a Geoserver instance located at
+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
+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
+`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.
+
+
+WFS
+~~~
+
+WFS, like WMS, implements a standard set by the Open Geospatial Consortium, this time the
+`Web Feature Service <http://www.opengeospatial.org/standards/wfs>`_. Unlike WMS, however, the WFS layer is used to show
+points, lines and polygons instead of displaying images. In many cases, this layer is
+used to perform client-side rendering instead of having features rendered by the server.
+
+new OpenLayers.Layer.WFS()
+--------------------------
+
+Creating a WFS layer is very similar to creating a WMS layer.
+
+ .. code-block::
+ html
+
+ var layer = new OpenLayers.Layer.WFS(
+ "United States",
+ "http://sigma.openplans.org/geoserver/wfs",
+ { typename: 'topp:states' }
+ );
+ map.addLayer(layer);
+
+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>`_.
+
+Other Layers
+------------
+
+WMS and WFS are not the only layers out there: There are plenty more available.
+`Browse the OpenLayers source code <http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Layer>`_ 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.
+
+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?*
+
+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 by reading
+`OpenLayers' Control documentation <http://docs.openlayers.org/library/controls.html>`_.
+
+
+
+Events
+======
+
+Events are the main mechanism for notifying multiple objects that something has happened. For instance, the ``NavigationHistory``
+control listens to the map's ``zoomend`` event to save the user's zoom history for a later date; similarly, other objects may
+listen to the same event without interfering or knowing about the ``NavigationHistory`` control. This makes events very powerful,
+allowing objects to perform their desired function while decreasing coupling within OpenLayers and Ext applications.
+
+Both GeoExt and OpenLayers make extensive use of events. However, the OpenLayers events are slightly different from those in
+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.
+
+Ext events can be used in any Ext or GeoExt components that extend the ``Ext.util.Observable`` class.
+`More here. <http://www.slideshare.net/sdhjl2000/ext-j-s-observable>`_
+
+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
+
+ 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
+
+ var MyPanel = Ext.Extend(Ext.Panel, {
+
+ // ...
+
+ myFunction: function() {
+ 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
+
+ var panel = new MyPanel(/* ... */);
+
+ // First listener.
+ panel.on("event1", function(arg1) {
+ alert("First listener responded. Got " + arg1 + "!");
+ });
+
+ // Second listener.
+ panel.on("event1", function(arg1) {
+ alert("Second listener responded. Got " + arg1 + "!");
+ });
+
+ 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.
+
+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``.
+
+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
+
+ var MyControl = new OpenLayers.Class(OpenLayers.Control, {
+
+ events: null,
+
+ initialize: function() {
+ this.events = new OpenLayers.Events(
+ this,
+ null,
+ ["event1" /*, "event2", ... etc. */]
+ false
+ );
+
+ 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``.
+
+The second parameter specifies a ``div`` that will listen to events thrown by the browser. Here, this functionality is ignored; see the note
+below.
+
+The third parameter is an array specifying the events that this ``OpenLayers.Events`` object can throw. This is analogous to
+``Ext.util.Observable``'s ``addEvents()`` method, and can accept any number of events.
+
+The fourth parameter is the ``fallthrough``, a boolean that is related to the second parameter above. For our purposes, we'll leave
+it as ``false``.
+
+.. note:: The ``OpenLayers.Events`` class handles both browser events like when the window resizes, as well
+ as handling developer-created events like ``event1`` above. This makes initializing an ``OpenLayers.Events`` object fairly mucky,
+ though using it like we did above is nearly the same. See more below.
+
+Triggering an event is just as easy as Ext's ``fireEvent()``, except here we use ``triggerEvent()``:
+
+ .. code-block::
+ html
+
+ var MyControl = new OpenLayers.Class(OpenLayers.Control, {
+
+ // ...
+
+ myFunction: function() {
+ var evt = {
+ arg1: "somevalue" /*, arg2: ..., ... etc.*/
+ }
+ 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
+ one named argument. See example below.
+
+Finally, let's add two listeners and call ``myFunction()``:
+
+ .. code-block::
+ html
+
+ 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) {
+ alert("Second listener responded. Got " + evt.arg1 + "!");
+ });
+
+ 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.
+ We don't have a scope for our listeners in this example, hence the ``null`` parameters.
+
+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:
+
+* `OpenLayers Events Class Documentation <http://dev.openlayers.org/docs/files/OpenLayers/Events-js.html>`_
+* `Ext.util.Observable Class Documentation <http://extjs.com/deploy/ext/docs/output/Ext.util.Observable.html>`_
+* `Ext.util.Observable SlideShare <http://www.slideshare.net/sdhjl2000/ext-j-s-observable>`_
Property changes on: sandbox/docsrc/primers/openlayers-primer.rst
___________________________________________________________________
Name: svn:mergeinfo
+
Deleted: sandbox/docsrc/tutorials/ext-primer.rst
===================================================================
--- sandbox/docsrc/tutorials/ext-primer.rst 2009-05-12 19:49:11 UTC (rev 689)
+++ sandbox/docsrc/tutorials/ext-primer.rst 2009-05-12 19:52:13 UTC (rev 690)
@@ -1,105 +0,0 @@
-.. _ext-primer:
-
-=============
- Primer: Ext
-=============
-
-GeoExt extends `Ext JS <http://extjs.com/>`_, a rich library of web UI
-widgets and helper classes. Using GeoExt requires a working knowledge
-of Ext's idioms. This tutorial provides a quick overview of core Ext concepts.
-
-.. _ext-getting-started:
-
-Getting Started
-===============
-
-To start using Ext, you will first have to `download
-<http://www.extjs.com/products/extjs/download.php>`_ it.
-For more complete instructions about how configure a web page to use
-Ext, you can check the GeoExt :doc:`quickstart` tutorial.
-
-When you download Ext, you also get their excellent `Examples <http://www.extjs.com/deploy/dev/examples/>'_ and 'API
-Documentation <http://www.extjs.com/deploy/dev/docs/>`_, which you can also look at on-line for education and reference.
-
-In order to get Ext running on a page you will need to have something
-like the following in the ``<head>`` of an HTML page in a directory
-that is published by your web server.
-
- .. code-block::
- xml
-
- <script src="ext-2.2/adapter/ext/ext-base.js" type="text/javascript"></script>
- <script src="ext-2.2/ext-all.js" type="text/javascript"></script>
- <link rel="stylesheet" type="text/css" href="ext-2.2/resources/ext-all.css"></link>
-
-This will load the code and styles for Ext. Change the paths
-according to where you have put the Ext files.
-
-When writing Ext code, most of what you will be doing is instantiating
-classes with constructors that takes a single object--its
-configuration object--as an argument. This snippet demonstrates this
-coding pattern:
-
- .. code-block::
- html
-
- Ext.onReady(function(){
- var myPanel = new Ext.Panel({
- title: 'Hello World!',
- html: '<i>Hello World!</i> Please enjoy this primer on Ext!'
- collapsible: true,
- width:500,
- renderTo: 'panelDiv',
- });
- };
-
-This code uses Ext's ``onReady`` method to trigger the method when the
-document's body is ready. (This is cleaner than using body's
-``onready`` event, and with ``Ext.onReady`` several functions can be
-queued for execution before the page loads.)
-
-When the page is ready, the ``Ext.Panel`` constructor is called with a
-single configuration object as argument. The Panel's structure should
-be familiar from your desktop experience. It has a ``title`` which
-runs across the top, and some content which in this case is ``html``
-provided in the configuration.
-
-Many configuration options (best explored in the Ext examples and API
-documention) are available. Here, they are represented by the
-``collapsible`` property, which allows the user to collapse the panel
-much like you can minimize your browser's window, and the ``width`` of
-the panel specified in pixels.
-
-Lastly, this code assumes that somewhere in the DOM of the page is a
-``div`` with the id ``panelDiv``. When the Panel is constructed, it
-will be automatically rendered in this div because of the ``renderTo``
-option. (This option can be left out and panels rendered manually, if desired.)
-
-.. _ext-basic-layout:
-
-Basic Layout
-============
-
-Ext makes it easy to separate out your UI into logical blocks. It
-
-.. _ext-trees:
-
-Trees, Nodes, and Childnodes
-============================
-
-[tba]
-
-.. _ext-grid-store:
-
-Grid and Store
-==============
-
-[working with records from a reader]
-
-
-.. _ext-events:
-
-Events
-======
-
-[from a geoxt perspective]
Deleted: sandbox/docsrc/tutorials/openlayers-primer.rst
===================================================================
--- sandbox/docsrc/tutorials/openlayers-primer.rst 2009-05-12 19:49:11 UTC (rev 689)
+++ sandbox/docsrc/tutorials/openlayers-primer.rst 2009-05-12 19:52:13 UTC (rev 690)
@@ -1,353 +0,0 @@
-====================
- 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.
-
-Layers
-======
-
-As its name suggests, OpenLayers manages a list of layers that together form a web-based
-mapping client. Each layer represents a different piece 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 WFS.
-
-WMS
-~~~
-
-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:`quickstart` guide in GeoExt under the heading 'Using GeoExt', you will have already encountered a MapPanel and created
-your very own WMS layer. Let's dissect what you did.
-
-new OpenLayers.Layer.WMS()
---------------------------
-
-After creating an OpenLayers Map (but before creating a GeoExt MapPanel), you encountered the following code:
-
- .. code-block::
- html
-
- var layer = new OpenLayers.Layer.WMS(
- "Blue Marble",
- "http://sigma.openplans.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 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.
-
-The second parameter represents the location of the WMS server tasked with providing the images. We're using a Geoserver instance located at
-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
-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
-`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.
-
-
-WFS
-~~~
-
-WFS, like WMS, implements a standard set by the Open Geospatial Consortium, this time the
-`Web Feature Service <http://www.opengeospatial.org/standards/wfs>`_. Unlike WMS, however, the WFS layer is used to show
-points, lines and polygons instead of displaying images. In many cases, this layer is
-used to perform client-side rendering instead of having features rendered by the server.
-
-new OpenLayers.Layer.WFS()
---------------------------
-
-Creating a WFS layer is very similar to creating a WMS layer.
-
- .. code-block::
- html
-
- var layer = new OpenLayers.Layer.WFS(
- "United States",
- "http://sigma.openplans.org/geoserver/wfs",
- { typename: 'topp:states' }
- );
- map.addLayer(layer);
-
-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>`_.
-
-Other Layers
-------------
-
-WMS and WFS are not the only layers out there: There are plenty more available.
-`Browse the OpenLayers source code <http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Layer>`_ 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.
-
-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?*
-
-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 by reading
-`OpenLayers' Control documentation <http://docs.openlayers.org/library/controls.html>`_.
-
-
-
-Events
-======
-
-Events are the main mechanism for notifying multiple objects that something has happened. For instance, the ``NavigationHistory``
-control listens to the map's ``zoomend`` event to save the user's zoom history for a later date; similarly, other objects may
-listen to the same event without interfering or knowing about the ``NavigationHistory`` control. This makes events very powerful,
-allowing objects to perform their desired function while decreasing coupling within OpenLayers and Ext applications.
-
-Both GeoExt and OpenLayers make extensive use of events. However, the OpenLayers events are slightly different from those in
-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.
-
-Ext events can be used in any Ext or GeoExt components that extend the ``Ext.util.Observable`` class.
-`More here. <http://www.slideshare.net/sdhjl2000/ext-j-s-observable>`_
-
-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
-
- 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
-
- var MyPanel = Ext.Extend(Ext.Panel, {
-
- // ...
-
- myFunction: function() {
- 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
-
- var panel = new MyPanel(/* ... */);
-
- // First listener.
- panel.on("event1", function(arg1) {
- alert("First listener responded. Got " + arg1 + "!");
- });
-
- // Second listener.
- panel.on("event1", function(arg1) {
- alert("Second listener responded. Got " + arg1 + "!");
- });
-
- 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.
-
-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``.
-
-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
-
- var MyControl = new OpenLayers.Class(OpenLayers.Control, {
-
- events: null,
-
- initialize: function() {
- this.events = new OpenLayers.Events(
- this,
- null,
- ["event1" /*, "event2", ... etc. */]
- false
- );
-
- 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``.
-
-The second parameter specifies a ``div`` that will listen to events thrown by the browser. Here, this functionality is ignored; see the note
-below.
-
-The third parameter is an array specifying the events that this ``OpenLayers.Events`` object can throw. This is analogous to
-``Ext.util.Observable``'s ``addEvents()`` method, and can accept any number of events.
-
-The fourth parameter is the ``fallthrough``, a boolean that is related to the second parameter above. For our purposes, we'll leave
-it as ``false``.
-
-.. note:: The ``OpenLayers.Events`` class handles both browser events like when the window resizes, as well
- as handling developer-created events like ``event1`` above. This makes initializing an ``OpenLayers.Events`` object fairly mucky,
- though using it like we did above is nearly the same. See more below.
-
-Triggering an event is just as easy as Ext's ``fireEvent()``, except here we use ``triggerEvent()``:
-
- .. code-block::
- html
-
- var MyControl = new OpenLayers.Class(OpenLayers.Control, {
-
- // ...
-
- myFunction: function() {
- var evt = {
- arg1: "somevalue" /*, arg2: ..., ... etc.*/
- }
- 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
- one named argument. See example below.
-
-Finally, let's add two listeners and call ``myFunction()``:
-
- .. code-block::
- html
-
- 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) {
- alert("Second listener responded. Got " + evt.arg1 + "!");
- });
-
- 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.
- We don't have a scope for our listeners in this example, hence the ``null`` parameters.
-
-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:
-
-* `OpenLayers Events Class Documentation <http://dev.openlayers.org/docs/files/OpenLayers/Events-js.html>`_
-* `Ext.util.Observable Class Documentation <http://extjs.com/deploy/ext/docs/output/Ext.util.Observable.html>`_
-* `Ext.util.Observable SlideShare <http://www.slideshare.net/sdhjl2000/ext-j-s-observable>`_
More information about the Commits
mailing list