[Commits] r1126 - in core/trunk/docsrc: primers tutorials
commits at geoext.org
commits at geoext.org
Mon Jun 22 22:48:37 CEST 2009
Author: tschaub
Date: 2009-06-22 22:48:37 +0200 (Mon, 22 Jun 2009)
New Revision: 1126
Modified:
core/trunk/docsrc/primers/ext-primer.rst
core/trunk/docsrc/primers/openlayers-primer.rst
core/trunk/docsrc/tutorials/control-button-tutorial.rst
core/trunk/docsrc/tutorials/layertree-tutorial.rst
core/trunk/docsrc/tutorials/mappanel-tutorial.rst
core/trunk/docsrc/tutorials/quickstart.rst
core/trunk/docsrc/tutorials/remote-features-tutorial.rst
Log:
Doc tidy.
Modified: core/trunk/docsrc/primers/ext-primer.rst
===================================================================
--- core/trunk/docsrc/primers/ext-primer.rst 2009-06-22 20:40:44 UTC (rev 1125)
+++ core/trunk/docsrc/primers/ext-primer.rst 2009-06-22 20:48:37 UTC (rev 1126)
@@ -27,11 +27,11 @@
like the following in the ``<head>`` of an HTML page in a directory
that is published by your web server.
- .. code-block:: html
+.. code-block:: html
- <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/css/ext-all.css"></link>
+ <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/css/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.
@@ -41,24 +41,24 @@
configuration object--as an argument. This snippet demonstrates this
coding pattern:
- .. code-block:: javascript
+.. code-block:: javascript
- 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:300,
- renderTo: 'panelDiv'
- });
- });
+ 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:300,
+ renderTo: 'panelDiv'
+ });
+ });
There are a few things to note about this example:
* 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.)
+ 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
@@ -75,7 +75,8 @@
* 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.)
+ option. (This option can be left out and panels rendered manually, if
+ desired.)
.. _ext-basic-layout:
@@ -87,28 +88,28 @@
``Ext.Panel`` built above is the most common kind of container. You
can nest panels using the ``items`` property. For example:
- .. code-block:: javascript
+.. code-block:: javascript
- Ext.onReady(function(){
- var myPanel = new Ext.Panel({
- title: 'Top level',
- layout: 'border',
- items: [{
- xtype:'panel',
- title:'Sub1',
- html:'Contents of sub panel 1',
- region: 'east'
- },{
- xtype:'panel',
- title: 'Sub2',
- html:'Contents of sub panel 2',
- region: 'center'
- }],
- width:300,
- height:200,
- renderTo:'panelDiv'
- });
- });
+ Ext.onReady(function(){
+ var myPanel = new Ext.Panel({
+ title: 'Top level',
+ layout: 'border',
+ items: [{
+ xtype:'panel',
+ title:'Sub1',
+ html:'Contents of sub panel 1',
+ region: 'east'
+ },{
+ xtype:'panel',
+ title: 'Sub2',
+ html:'Contents of sub panel 2',
+ region: 'center'
+ }],
+ width:300,
+ height:200,
+ renderTo:'panelDiv'
+ });
+ });
This code introduces some new concepts:
Modified: core/trunk/docsrc/primers/openlayers-primer.rst
===================================================================
--- core/trunk/docsrc/primers/openlayers-primer.rst 2009-06-22 20:40:44 UTC (rev 1125)
+++ core/trunk/docsrc/primers/openlayers-primer.rst 2009-06-22 20:48:37 UTC (rev 1126)
@@ -158,17 +158,19 @@
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.
+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.
+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:: javascript
@@ -179,173 +181,197 @@
]
});
-.. 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>`_
+.. 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>`_.
+`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.
+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.
+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.
+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>`_
+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.
+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:: javascript
-
- var MyPanel = Ext.Extend(Ext.Panel, {
- initComponent: function() {
- // ...
- this.addEvents("event1" /*, "event2", ... etc.*/ );
-
- MyPanel.superclass.initComponent.call(this);
- }
- });
+.. code-block:: javascript
+
+ 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:: javascript
-
- var MyPanel = Ext.Extend(Ext.Panel, {
-
- // ...
-
- myFunction: function() {
- var arg1 = "somevalue";
- this.fireEvent("event1", arg1 /*, arg2, ... etc. */);
- }
- });
+.. code-block:: javascript
+
+ 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()``.
+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:: javascript
-
- 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 + "!");
- });
+.. code-block:: javascript
+
+ var panel = new MyPanel(/* ... */);
- panel.myFunction();
+ // 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.
+.. 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``.
+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.
+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:: javascript
-
- var MyControl = new OpenLayers.Class(OpenLayers.Control, {
-
- events: null,
+.. code-block:: javascript
+
+ var MyControl = new OpenLayers.Class(OpenLayers.Control, {
+
+ events: null,
+
+ initialize: function() {
+ this.events = new OpenLayers.Events(
+ this,
+ null,
+ ["event1" /*, "event2", ... etc. */]
+ false
+ );
- initialize: function() {
- this.events = new OpenLayers.Events(
- this,
- null,
- ["event1" /*, "event2", ... etc. */]
- false
- );
-
- OpenLayers.Control.prototype.initialize.call(this);
- }
- });
+ 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 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 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 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``.
+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.
+.. 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()``:
+Triggering an event is just as easy as Ext's ``fireEvent()``, except here we use
+``triggerEvent()``:
- .. code-block:: javascript
-
- var MyControl = new OpenLayers.Class(OpenLayers.Control, {
+.. code-block:: javascript
+
+ var MyControl = new OpenLayers.Class(OpenLayers.Control, {
- // ...
-
- myFunction: function() {
- var evt = {
- arg1: "somevalue" /*, arg2: ..., ... etc.*/
- }
- this.events.triggerEvent("event1", evt);
+ // ...
+
+ 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.
+.. note:: ``OpenLayers.Events`` passes data to listeners using a single object
+ with properties -- 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:: javascript
-
- 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 + "!");
- });
+.. code-block:: javascript
+
+ 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();
+ 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.
+.. 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!
Modified: core/trunk/docsrc/tutorials/control-button-tutorial.rst
===================================================================
--- core/trunk/docsrc/tutorials/control-button-tutorial.rst 2009-06-22 20:40:44 UTC (rev 1125)
+++ core/trunk/docsrc/tutorials/control-button-tutorial.rst 2009-06-22 20:48:37 UTC (rev 1126)
@@ -4,21 +4,38 @@
Map Tool Tutorial
============================
-Okay, so now you know how to :doc:`add a map to a web page <mappanel-tutorial>` and load some data into it. Your users can drag and zoom to their hearts' content. You even followed the :doc:`layertree-tutorial` so they could switch between different datasets. (You did follow that tutorial, right?) But now you want to do more than just view some pretty pictures. You want to let your users analyze data, or get more info about particular features on your map, or just draw things. Basically, you want to give them some **tools**\ .
+Okay, so now you know how to :doc:`add a map to a web page <mappanel-tutorial>`
+and load some data into it. Your users can drag and zoom to their hearts'
+content. You even followed the :doc:`layertree-tutorial` so they could switch
+between different datasets. (You did follow that tutorial, right?) But now you
+want to do more than just view some pretty pictures. You want to let your users
+analyze data, or get more info about particular features on your map, or just
+draw things. Basically, you want to give them some **tools**\ .
-.. note:: This tutorial makes heavy use of the OpenLayers mapping library. If you're not familiar with it, you might want to take a look at the :doc:`/primers/openlayers-primer` before moving forward.
+.. note:: This tutorial makes heavy use of the OpenLayers mapping library. If
+ you're not familiar with it, you might want to take a look at the
+ :doc:`/primers/openlayers-primer` before moving forward.
OpenLayers Controls
===================
-In `OpenLayers <http://openlayers.org/>`_\ , these tools for interacting with a map are called ``Controls``\ . For the purposes of this tutorial, we'll just stick to the ``Measure`` control, a handy little tool that lets you draw a line on the map and tells you its length in real-world units.
+In `OpenLayers <http://openlayers.org/>`_\ , these tools for interacting with a
+map are called ``Controls``\ . For the purposes of this tutorial, we'll just
+stick to the ``Measure`` control, a handy little tool that lets you draw a line
+on the map and tells you its length in real-world units.
.. seealso:: The OpenLayer API documentation for a comprehensive listing of standard controls.
ExtJS Buttons
=============
-While OpenLayers ``Control``\ s provide a number of excellent ways of interacting with maps, they have only limited support for actually manipulating the controls; ie, choosing which tool to use and providing user feedback about which tool is active. ExtJS provides a richer array of options for managing tools. Here is the idiomatic way to create an ``Ext.Button`` which activates and deactivates an OpenLayers ``Control``\ , and stays depressed while the control is active::
+While OpenLayers ``Control``\ s provide a number of excellent ways of
+interacting with maps, they have only limited support for actually manipulating
+the controls; ie, choosing which tool to use and providing user feedback about
+which tool is active. ExtJS provides a richer array of options for managing
+tools. Here is the idiomatic way to create an ``Ext.Button`` which activates and
+deactivates an OpenLayers ``Control``\ , and stays depressed while the control
+is active::
var control = new OpenLayers.Control.Measure(OpenLayers.Handler.Path, {
eventListeners: {
@@ -41,7 +58,9 @@
}
});
-The ``Button`` can be added to an ExtJS toolbar or to a panel, in whatever layout we choose. For example, you could add the button to a ``MapPanel``\ 's top toolbar::
+The ``Button`` can be added to an ExtJS toolbar or to a panel, in whatever
+layout we choose. For example, you could add the button to a ``MapPanel``\ 's
+top toolbar::
mapPanel.getTopToolbar().addButton(button);
@@ -49,7 +68,15 @@
There Can Be Only One
=====================
-In general, when you have multiple tools associated with a map, you want to avoid having more than one tool active at the same time. It would be somewhat confusing if the user starts deleting data while he or she is trying to find the distance from one end of town to the other! Fortunately, ExtJS makes it very simple to ensure that only one toggle button from a group is toggled at a time, through the ``toggleGroup`` property of the ``Button`` object. This is a string identifying a group of buttons, only one of which can be pressed at a time. Let's extend our example from before, this time adding the option to measure area instead of length::
+In general, when you have multiple tools associated with a map, you want to
+avoid having more than one tool active at the same time. It would be somewhat
+confusing if the user starts deleting data while he or she is trying to find the
+distance from one end of town to the other! Fortunately, ExtJS makes it very
+simple to ensure that only one toggle button from a group is toggled at a time,
+through the ``toggleGroup`` property of the ``Button`` object. This is a string
+identifying a group of buttons, only one of which can be pressed at a time.
+Let's extend our example from before, this time adding the option to measure
+area instead of length::
var length = new OpenLayers.Control.Measure(OpenLayers.Handler.Path, {
eventListeners: {
@@ -98,4 +125,5 @@
}
});
-All right, you've got all you need to add and activate tools to help users get the most out of your maps.
+All right, you've got all you need to add and activate tools to help users get
+the most out of your maps.
Modified: core/trunk/docsrc/tutorials/layertree-tutorial.rst
===================================================================
--- core/trunk/docsrc/tutorials/layertree-tutorial.rst 2009-06-22 20:40:44 UTC (rev 1125)
+++ core/trunk/docsrc/tutorials/layertree-tutorial.rst 2009-06-22 20:48:37 UTC (rev 1126)
@@ -2,14 +2,28 @@
Layer Tree Tutorial
============================
-Often when presenting users with an interactive map, it is useful to allow them to control the visible layers. In this tutorial, we examine the use of :class:`GeoExt.tree.LayerContainer` with the stock ``Ext.tree.TreePanel`` class to accommodate toggling visibility of layers and rearranging their drawing order.
+Often when presenting users with an interactive map, it is useful to allow them
+to control the visible layers. In this tutorial, we examine the use of
+:class:`GeoExt.tree.LayerContainer` with the stock ``Ext.tree.TreePanel`` class
+to accommodate toggling visibility of layers and rearranging their drawing
+order.
-.. note:: Before starting this tutorial, you should have a working :class:`GeoExt.MapPanel` in your page. The :doc:`mappanel-tutorial` will help you set one up if you don't already have one.
+.. note:: Before starting this tutorial, you should have a working
+ :class:`GeoExt.MapPanel` in your page. The :doc:`mappanel-tutorial` will
+ help you set one up if you don't already have one.
Start With a Map
================
-Let's assume you already have a :class:`GeoExt.MapPanel` on your page with some layers. In the :doc:`mappanel-tutorial`\ , we discussed how you can use the ``layers`` property of the ``MapPanel`` to add, remove, and modify the layers of the map as well as monitor the layer list for changes. This is more than sufficient to display a 'live' list of layers in an ``Ext.grid.GridPanel``\ . The :class:`GeoExt.tree.LayerContainer` is another component that can listen to changes to the map's layer list. However, rather than an independent panel, the ``LayerContainer`` is a node that must be contained in an ``Ext.tree.TreePanel`` to be displayed. Here's an example rendering a layer tree to a ``div``:
+Let's assume you already have a :class:`GeoExt.MapPanel` on your page with some
+layers. In the :doc:`mappanel-tutorial`\ , we discussed how you can use the
+``layers`` property of the ``MapPanel`` to add, remove, and modify the layers of
+the map as well as monitor the layer list for changes. This is more than
+sufficient to display a 'live' list of layers in an ``Ext.grid.GridPanel``\ .
+The :class:`GeoExt.tree.LayerContainer` is another component that can listen to
+changes to the map's layer list. However, rather than an independent panel, the
+``LayerContainer`` is a node that must be contained in an ``Ext.tree.TreePanel``
+to be displayed. Here's an example rendering a layer tree to a ``div``:
.. code-block:: javascript
@@ -30,10 +44,23 @@
root: layerList
});
-``LayerContainer``\ s automatically add checkboxes that can be used to toggle the visibility of layers. You can also enable drag-n-drop layer reordering by simply setting the ``enableDD`` property of the ``TreePanel``.
+``LayerContainer``\ s automatically add checkboxes that can be used to toggle
+the visibility of layers. You can also enable drag-n-drop layer reordering by
+simply setting the ``enableDD`` property of the ``TreePanel``.
Filtering
=========
-Currently, the ``LayerContainer`` automatically pulls in all layers from the store and displays those with the ``displayInLayerSwitcher`` property set to true. In the future (but before the robots take over) you will be able to filter out some layers by providing a filter function. By adding multiple named and filtered ``LayerContainer``\ s to a ``TreePanel`` you will be able to provide logical organization to your layer trees. In the meantime, you can directly instantiate :class:`GeoExt.LayerNode` to create tree nodes that can be added anywhere in a tree. Keep in mind, however, that this approach does not allow for automatic drag-n-drop support.
+Currently, the ``LayerContainer`` automatically pulls in all layers from the
+store and displays those with the ``displayInLayerSwitcher`` property set to
+true. In the future (but before the robots take over) you will be able to filter
+out some layers by providing a filter function. By adding multiple named and
+filtered ``LayerContainer``\ s to a ``TreePanel`` you will be able to provide
+logical organization to your layer trees. In the meantime, you can directly
+instantiate :class:`GeoExt.LayerNode` to create tree nodes that can be added
+anywhere in a tree. Keep in mind, however, that this approach does not allow for
+automatic drag-n-drop support.
-.. seealso:: The ExtJS TreePanel `documentation <http://extjs.com/deploy/dev/docs/?class=Ext.tree.TreePanel>`_ and `examples <http://extjs.com/deploy/dev/examples/samples.html#sample-4>`_ for more information about customizing tree panels.
+.. seealso:: The ExtJS TreePanel `documentation
+ <http://extjs.com/deploy/dev/docs/?class=Ext.tree.TreePanel>`_ and `examples
+ <http://extjs.com/deploy/dev/examples/samples.html#sample-4>`_ for more
+ information about customizing tree panels.
Modified: core/trunk/docsrc/tutorials/mappanel-tutorial.rst
===================================================================
--- core/trunk/docsrc/tutorials/mappanel-tutorial.rst 2009-06-22 20:40:44 UTC (rev 1125)
+++ core/trunk/docsrc/tutorials/mappanel-tutorial.rst 2009-06-22 20:48:37 UTC (rev 1126)
@@ -4,56 +4,78 @@
``MapPanel`` Tutorial
============================
-The :class:`GeoExt.MapPanel` is the heart of most GeoExt applications, displaying rendered data. Leveraging the OpenLayers JavaScript mapping library, it can display rendered tiles from OWS services, perform client-side rendering in the browser, and use tiles from popular mapping services such as Google Maps or Virtual Earth. In this tutorial, we explore ways that developers can customize the MapPanel.
+The :class:`GeoExt.MapPanel` is the heart of most GeoExt applications,
+displaying rendered data. Leveraging the OpenLayers JavaScript mapping library,
+it can display rendered tiles from OWS services, perform client-side rendering
+in the browser, and use tiles from popular mapping services such as Google Maps
+or Virtual Earth. In this tutorial, we explore ways that developers can
+customize the MapPanel.
-.. note:: It is recommended that you follow the :doc:`quickstart` tutorial before moving on to this one. It really is quick; we'll wait for you.
+.. note:: It is recommended that you follow the :doc:`quickstart` tutorial
+before moving on to this one. It really is quick; we'll wait for you.
A Basic MapPanel
================
-Taking a look at the example code from the quickstart tutorial, we can see a very basic map configuration::
+Taking a look at the example code from the quickstart tutorial, we can see a
+very basic map configuration::
- var map = new OpenLayers.Map();
- var layer = new OpenLayers.Layer.WMS(
- "Blue Marble",
- "http://sigma.openplans.org/geoserver/wms?",
- {layers: "bluemarble"}
- );
- map.addLayer(layer);
-
- var mapPanel = new GeoExt.MapPanel({
- renderTo: 'gxmap',
- height: 400,
- width: 600,
- map: map,
- title: 'A Simple GeoExt Map'
- });
+ var map = new OpenLayers.Map();
+ var layer = new OpenLayers.Layer.WMS(
+ "Blue Marble",
+ "http://sigma.openplans.org/geoserver/wms?",
+ {layers: "bluemarble"}
+ );
+ map.addLayer(layer);
+
+ var mapPanel = new GeoExt.MapPanel({
+ renderTo: 'gxmap',
+ height: 400,
+ width: 600,
+ map: map,
+ title: 'A Simple GeoExt Map'
+ });
Looking at this code we can see a few things going on:
-In **line 1** we instantiate an :class:`OpenLayers.Map`. This isn't required by the MapPanel (it will create a Map for you if none is provided) but we want to customize our map a bit.
+In **line 1** we instantiate an :class:`OpenLayers.Map`. This isn't required by
+the MapPanel (it will create a Map for you if none is provided) but we want to
+customize our map a bit.
-In **lines 2-6** we create a new :class:`OpenLayers.Layer`. This particular layer is a WMS layer, which uses tiles from the Blue Marble layer at http://sigma.openplans.org/.
+In **lines 2-6** we create a new :class:`OpenLayers.Layer`. This particular
+layer is a WMS layer, which uses tiles from the Blue Marble layer at
+http://sigma.openplans.org/.
In **line 7** we add our new layer to the map.
In **lines 9-15** we create a new map panel with several options:
- renderTo
- This works the same as ``renderTo`` in a normal :class:`Ext.Panel`; it can be an id string, DOM node, or :class:`Ext.Element` telling the MapPanel where on the page it should insert itself.
+ ``renderTo``
+ This works the same as ``renderTo`` in a normal :class:`Ext.Panel`; it
+ can be an id string, DOM node, or :class:`Ext.Element` telling the
+ MapPanel where on the page it should insert itself.
- height, width
+ ``height``, ``width``
These tell the map panel how much large it should draw itself.
- map
- This is an :class:`OpenLayers.Map` which will be used as the actual map inside the panel.
+ ``map``
+ This is an :class:`OpenLayers.Map` which will be used as the actual map
+ inside the panel.
- title
- This is the normal ``title`` property for ExtJS components. It will be rendered nicely across the top of the panel.
+ ``title``
+ This is the normal ``title`` property for ExtJS components. It will be
+ rendered nicely across the top of the panel.
Working with the MapPanel
=========================
-While using ``OpenLayers.Map.addLayer()`` to add layers is a convenient way to customize the map, a hand-coded, static list of map layers is not always what we want. In order to make manipulating the layer list more accessible to ExtJS widgets, the MapPanel exposes a `layers` property which is an :class:`Ext.data.Store` that will automatically be updated when layers are added, removed, changed, or reordered, with all of the Ext events that go with it. We can use this to, for example, populate an :class:`Ext.grid.GridPanel` with a live list of layers in the map::
+While using ``OpenLayers.Map.addLayer()`` to add layers is a convenient way to
+customize the map, a hand-coded, static list of map layers is not always what we
+want. In order to make manipulating the layer list more accessible to ExtJS
+widgets, the MapPanel exposes a `layers` property which is an
+:class:`Ext.data.Store` that will automatically be updated when layers are
+added, removed, changed, or reordered, with all of the Ext events that go with
+it. We can use this to, for example, populate an :class:`Ext.grid.GridPanel`
+with a live list of layers in the map::
new Ext.grid.GridPanel({
renderTo: 'layerlist',
@@ -63,13 +85,19 @@
columns: [{name: 'name', heading: 'Name'}]
});
-.. highlight:: html
+In the HTML, you'll need to add a ``div`` for the grid panel to render itself in:
-In the HTML, you'll need to add a ``div`` for the grid panel to render itself in::
+.. code-block:: html
<div id='layerlist'></div>
-More information on the :class:`Ext.grid.GridPanel` is available from the `ExtJS API documentation <http://extjs.com/deploy/dev/docs/?class=Ext.grid.GridPanel>`_.
+More information on the :class:`Ext.grid.GridPanel` is available from the `ExtJS
+API documentation
+<http://extjs.com/deploy/dev/docs/?class=Ext.grid.GridPanel>`_.
-.. note:: This code is only meant as an example to demonstrate the map panel's integration with Ext. An :class:`Ext.tree.TreePanel` with :class:`GeoExt.tree.LayerNode`\ s is a a much nicer way to display the layers in a map, with optional support for hiding/showing layers and reordering. The TreePanel approach is discussed in the :doc:`layertree-tutorial`.
+.. note:: This code is only meant as an example to demonstrate the map panel's
+integration with Ext. An :class:`Ext.tree.TreePanel` with
+:class:`GeoExt.tree.LayerNode`\ s is a a much nicer way to display the layers in
+a map, with optional support for hiding/showing layers and reordering. The
+TreePanel approach is discussed in the :doc:`layertree-tutorial`.
Modified: core/trunk/docsrc/tutorials/quickstart.rst
===================================================================
--- core/trunk/docsrc/tutorials/quickstart.rst 2009-06-22 20:40:44 UTC (rev 1125)
+++ core/trunk/docsrc/tutorials/quickstart.rst 2009-06-22 20:48:37 UTC (rev 1126)
@@ -15,23 +15,26 @@
reasons, ExtJS cannot be included in the GeoExt download, so preparing
GeoExt for use on your own web pages is a multi-step process:
-#. Download GeoExt from the :doc:`downloads page </downloads>`. For the purposes of this
- quickstart, the development version will be fine.
+#. Download GeoExt from the :doc:`downloads page </downloads>`. For the purposes
+ of this quickstart, the development version will be fine.
#. Download OpenLayers 2.8 or later from http://openlayers.org/.
#. Download ExtJS 2.2 from `the ExtJS website <http://extjs.com/products/extjs/download.php>`_.
-#. Place both unpacked libraries in a directory that is published by your web server. For this tutorial, I will assume that this is the root of your web server, so that GeoExt.js is at http://localhost/GeoExt/lib/GeoExt.js and ext-all.js is at http://localhost/ext-2.2/ext-all.js
+#. Place both unpacked libraries in a directory that is published by your web
+ server. For this tutorial, I will assume that this is the root of your web
+ server, so that GeoExt.js is at http://localhost/GeoExt/lib/GeoExt.js and
+ ext-all.js is at http://localhost/ext-2.2/ext-all.js
#. Now you're ready to use GeoExt in your application!
.. note:: For production environments, the GeoExt team recommends that
- you use compressed and minified builds of GeoExt and ExtJS to
- optimize the download size of your page. A generic minified build
- containing all of GeoExt is available from the
- :doc:`downloads page </downloads>`, but advanced users can build their
- own.
+ you use compressed and minified builds of GeoExt and ExtJS to
+ optimize the download size of your page. A generic minified build
+ containing all of GeoExt is available from the
+ :doc:`downloads page </downloads>`, but advanced users can build their
+ own.
@@ -43,87 +46,85 @@
#. Include the ExtJS libraries in your web page.
- .. code-block::
- xml
+ .. code-block:: html
+
+ <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>
+ <script src="OpenLayers/OpenLayers.js" type="text/javascript"></script>
+ <script src="GeoExt/lib/GeoExt.js" type="text/javascript"></script>
+ <link rel="stylesheet" type="text/css" href="GeoExt/resources/geoext-all-debug.css"></link>
- <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>
- <script src="OpenLayers/OpenLayers.js" type="text/javascript"></script>
- <script src="GeoExt/lib/GeoExt.js" type="text/javascript"></script>
- <link rel="stylesheet" type="text/css" href="GeoExt/resources/geoext-all-debug.css"></link>
-
#. Create a ``<div>`` element in your web page with its ``id``
- attribute set to ``gxmap``. We will use the ``id`` to attach a
- GeoExt component to the ``div``.
+ attribute set to ``gxmap``. We will use the ``id`` to attach a
+ GeoExt component to the ``div``.
#. Attach a ``MapPanel`` object to the ``div`` with some JavaScript code:
- .. code-block::
- html
+ .. code-block:: html
+
+ <script type="text/javascript">
+ Ext.onReady(function() {
+ var map = new OpenLayers.Map();
+ var layer = new OpenLayers.Layer.WMS(
+ "Blue Marble",
+ "http://sigma.openplans.org/geoserver/wms?",
+ {layers: "bluemarble"}
+ );
+ map.addLayer(layer);
+
+ new GeoExt.MapPanel({
+ renderTo: 'gxmap',
+ height: 400,
+ width: 600,
+ map: map,
+ title: 'A Simple GeoExt Map'
+ });
+ });
+ </script>
- <script type="text/javascript">
- Ext.onReady(function() {
- var map = new OpenLayers.Map();
- var layer = new OpenLayers.Layer.WMS(
- "Blue Marble",
- "http://sigma.openplans.org/geoserver/wms?",
- {layers: "bluemarble"}
- );
- map.addLayer(layer);
-
- new GeoExt.MapPanel({
- renderTo: 'gxmap',
- height: 400,
- width: 600,
- map: map,
- title: 'A Simple GeoExt Map'
- });
- });
- </script>
-
The entire source of your page should look something like:
- .. code-block::
- html
+.. code-block:: html
- <html>
- <head>
+ <html>
+ <head>
- <title> A Basic GeoExt Page </title>
- <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>
- <script src="OpenLayers/OpenLayers.js" type="text/javascript"></script>
- <script src="GeoExt/lib/GeoExt.js" type="text/javascript"></script>
- <link rel="stylesheet" type="text/css" href="GeoExt/resources/geoext-all-debug.css"></link>
+ <title> A Basic GeoExt Page </title>
+ <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>
+ <script src="OpenLayers/OpenLayers.js" type="text/javascript"></script>
+ <script src="GeoExt/lib/GeoExt.js" type="text/javascript"></script>
+ <link rel="stylesheet" type="text/css" href="GeoExt/resources/geoext-all-debug.css"></link>
- <script type="text/javascript">
- Ext.onReady(function() {
- var map = new OpenLayers.Map();
- var layer = new OpenLayers.Layer.WMS(
- "Blue Marble",
- "http://sigma.openplans.org/geoserver/wms?",
- {layers: "bluemarble"}
- );
- map.addLayer(layer);
+ <script type="text/javascript">
+ Ext.onReady(function() {
+ var map = new OpenLayers.Map();
+ var layer = new OpenLayers.Layer.WMS(
+ "Blue Marble",
+ "http://sigma.openplans.org/geoserver/wms?",
+ {layers: "bluemarble"}
+ );
+ map.addLayer(layer);
- new GeoExt.MapPanel({
- renderTo: 'gxmap',
- height: 400,
- width: 600,
- map: map,
- title: 'A Simple GeoExt Map'
- });
- });
- </script>
- </head>
- <body>
- <div id="gxmap"></div>
- </body>
- </html>
+ new GeoExt.MapPanel({
+ renderTo: 'gxmap',
+ height: 400,
+ width: 600,
+ map: map,
+ title: 'A Simple GeoExt Map'
+ });
+ });
+ </script>
+ </head>
+ <body>
+ <div id="gxmap"></div>
+ </body>
+ </html>
-And that's it! You now have all of GeoExt, ready to bring your geospatial data to life. Go forth and prosper!
+And that's it! You now have all of GeoExt, ready to bring your geospatial data
+to life. Go forth and prosper!
Going Further
=============
@@ -133,7 +134,7 @@
learn more take a look at :doc:`index`, :doc:`/examples/index` and
:doc:`/lib/index`.
-We also recommend reading :doc:`../primers/ext-primer` and :doc:`../primers/openlayers-primer` to
-become acquainted with the libraries that form the foundation of
-GeoExt.
+We also recommend reading :doc:`../primers/ext-primer` and
+:doc:`../primers/openlayers-primer` to become acquainted with the libraries that
+form the foundation of GeoExt.
Modified: core/trunk/docsrc/tutorials/remote-features-tutorial.rst
===================================================================
--- core/trunk/docsrc/tutorials/remote-features-tutorial.rst 2009-06-22 20:40:44 UTC (rev 1125)
+++ core/trunk/docsrc/tutorials/remote-features-tutorial.rst 2009-06-22 20:48:37 UTC (rev 1126)
@@ -5,14 +5,27 @@
Vector Data Tutorial
====================
-Base layers such as OpenStreetMap and Google Maps are generally distributed in pre-rendered tiles using file formats such as PNG or JPG. While these are great for **displaying** maps, they are not very useful for getting at the data behind a map. They don't allow you to provide functionality such as informational popups, selection and highlighting of individual features, and editing of data. For these, you need to use **vector data**, provided through file formats such as KML, GeoJSON, or GML which provide information about each feature on the map, rather than just the pixels to put on the screen.
+Base layers such as OpenStreetMap and Google Maps are generally distributed in
+pre-rendered tiles using file formats such as PNG or JPG. While these are great
+for **displaying** maps, they are not very useful for getting at the data behind
+a map. They don't allow you to provide functionality such as informational
+popups, selection and highlighting of individual features, and editing of data.
+For these, you need to use **vector data**, provided through file formats such
+as KML, GeoJSON, or GML which provide information about each feature on the map,
+rather than just the pixels to put on the screen.
-.. note:: Modern web browsers impose a single-site restriction on JavaScript code to protect users from cross-site scripting attacks. This means that if your GeoExt application is hosted on a different host or port from your vector data, you will need to configure a proxy service.
+.. note:: Web browsers impose a same origin policy on JavaScript code to protect
+ users from cross-site scripting attacks. This means that if your GeoExt
+ application is hosted on a different host or port from your vector data, you
+ will need to configure a proxy service.
Reading KML
===========
-As an introduction to using vector data in GeoExt, let's create a simple map that displays data from a KML. Copy :download:`this sample KML file <sundials.kml>` to the same directory with your GeoExt and Ext libraries. Then we can load it with some JavaScript::
+As an introduction to using vector data in GeoExt, let's create a simple map
+that displays data from a KML. Copy :download:`this sample KML file
+<sundials.kml>` to the same directory with your GeoExt and Ext libraries. Then
+we can load it with some JavaScript::
var map = new Openlayers.Map();
var bluemarble = new OpenLayers.Layer.WMS("Blue Marble",
@@ -46,25 +59,46 @@
width: 600
});
-Here, we set up a map with two layers. ``bluemarble`` is a WMS layer, which you should have seen before in other tutorials. ``sundials`` is a vector layer, which handles client-side rendering of vector data.
+Here, we set up a map with two layers. ``bluemarble`` is a WMS layer, which you
+should have seen before in other tutorials. ``sundials`` is a vector layer,
+which handles client-side rendering of vector data.
-In **line 10** we initialize a :class:`GeoExt.data.FeatureStore`\ . This class functions as a normal ``Ext.data.Store`` to interoperate with ExtJS classes, as well as providing the ability to **bind** to an ``OpenLayers.Layer.Vector`` in order to display features on a map. In this example, we set up the store completely through constructor parameters:
+In **line 10** we initialize a :class:`GeoExt.data.FeatureStore`\ . This class
+functions as a normal ``Ext.data.Store`` to interoperate with ExtJS classes, as
+well as providing the ability to **bind** to an ``OpenLayers.Layer.Vector`` in
+order to display features on a map. In this example, we set up the store
+completely through constructor parameters:
``layer: sundials``
- tells the store to render features using the ``sundials`` layer. This is equivalent to calling ``store.bind(sundials)`` after initializing the store.
+ tells the store to render features using the ``sundials`` layer. This is
+ equivalent to calling ``store.bind(sundials)`` after initializing the
+ store.
``proxy: new GeoExt.data.ProtocolProxy(``
- tells the store to use a ``ProtocolProxy`` for fetching features. ``ProtocolProxy`` wraps OpenLayers Protocol objects. Here we use an ``OpenLayers.Protocol.HTTP`` to fetch data over the web. The ``HTTP`` protocol works with a variety of ``OpenLayers.Format`` types; here we use ``KML`` to match our dataset. You can see all the available ``Protocol``\ s and ``Format``\ s in the `OpenLayers API documentation <http://openlayers.org>`_.
+ tells the store to use a ``ProtocolProxy`` for fetching features.
+ ``ProtocolProxy`` wraps OpenLayers Protocol objects. Here we use an
+ ``OpenLayers.Protocol.HTTP`` to fetch data over the web. The ``HTTP``
+ protocol works with a variety of ``OpenLayers.Format`` types; here we
+ use ``KML`` to match our dataset. You can see all the available
+ ``Protocol``\ s and ``Format``\ s in the `OpenLayers API documentation
+ <http://openlayers.org>`_.
``fields: [...]``
- tells the store which extra properties (aside from just the geometry) to look for. Here, we know that KML includes a ``title`` and a ``description`` for each point, and that both are string values.
+ tells the store which extra properties (aside from just the geometry) to
+ look for. Here, we know that KML includes a ``title`` and a
+ ``description`` for each point, and that both are string values.
``autoLoad: true``
- tells the store to go ahead and fetch the feature data as soon as the constructor finishes. This is equivalent to calling ``store.load()`` after the store is initialized.
+ tells the store to go ahead and fetch the feature data as soon as the
+ constructor finishes. This is equivalent to calling ``store.load()``
+ after the store is initialized.
-Now we have a map with a background and some data hosted on our server. It looks like any other map; we can pan and zoom normally to navigate around.
+Now we have a map with a background and some data hosted on our server. It looks
+like any other map; we can pan and zoom normally to navigate around.
-However, since GeoExt has access to the data *behind* the map, we now have some options that weren't available to us before. For example, we can add a control that allows us to view the features in a tabular format::
+However, since GeoExt has access to the data *behind* the map, we now have some
+options that weren't available to us before. For example, we can add a control
+that allows us to view the features in a tabular format::
new Ext.grid.GridPanel({
title: 'Sundials',
More information about the Commits
mailing list