.. highlight:: javascript ==================== 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 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 `_). 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 `_ standard set by the `Open Geospatial Consortium. `_ 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); 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. 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 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. 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 `, 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++){ var x = -180 + Math.random() * 360; var y = -90 + Math.random() * 180; var numSides = 3 + Math.round(Math.random() * 6); vectorLayer.addFeature( new OpenLayers.Feature.Vector( OpenLayers.Geometry.Polygon.createRegularPolygon( new OpenLayers.Geometry.Point(x, y), numSides))); } 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`\ . 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 `_ 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 ``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. NavigationHistory Control ~~~~~~~~~~~~~~~~~~~~~~~~~ Take a look at the OpenLayers `NavigationHistory control example `_. 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. `_ More Controls ~~~~~~~~~~~~~ You can find more controls by `browsing the OpenLayers source code `_ or by reading `OpenLayers' Control documentation `_. 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. `_ 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 `_ * `Ext.util.Observable Class Documentation `_ * `Ext.util.Observable SlideShare `_