| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
|---|
| 2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | |
|---|
| 4 | <html xmlns="http://www.w3.org/1999/xhtml"> |
|---|
| 5 | <head> |
|---|
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|---|
| 7 | |
|---|
| 8 | <title>Primer: OpenLayers — GeoExt v1.0</title> |
|---|
| 9 | <link rel="stylesheet" href="../_static/geoext.css" type="text/css" /> |
|---|
| 10 | <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> |
|---|
| 11 | <script type="text/javascript"> |
|---|
| 12 | var DOCUMENTATION_OPTIONS = { |
|---|
| 13 | URL_ROOT: '../', |
|---|
| 14 | VERSION: '1.0', |
|---|
| 15 | COLLAPSE_MODINDEX: false, |
|---|
| 16 | FILE_SUFFIX: '.html', |
|---|
| 17 | HAS_SOURCE: true |
|---|
| 18 | }; |
|---|
| 19 | </script> |
|---|
| 20 | <script type="text/javascript" src="../_static/jquery.js"></script> |
|---|
| 21 | <script type="text/javascript" src="../_static/doctools.js"></script> |
|---|
| 22 | <link rel="shortcut icon" href="../_static/favicon.ico"/> |
|---|
| 23 | <link rel="top" title="GeoExt v1.0" href="../index.html" /> |
|---|
| 24 | <link rel="up" title="Core Concepts" href="index.html" /> |
|---|
| 25 | <link rel="next" title="Examples" href="../examples.html" /> |
|---|
| 26 | <link rel="prev" title="Primer: Ext" href="ext-primer.html" /> |
|---|
| 27 | |
|---|
| 28 | |
|---|
| 29 | |
|---|
| 30 | |
|---|
| 31 | |
|---|
| 32 | |
|---|
| 33 | </head> |
|---|
| 34 | <body> |
|---|
| 35 | <div class="header"> |
|---|
| 36 | <div class="wrap"> |
|---|
| 37 | <h1 id="logo"><a href="../index.html">GeoExt</a></h1> |
|---|
| 38 | <ul id="top-nav"> |
|---|
| 39 | <li class="first"><a href="../docs.html">Documentation</a></li> |
|---|
| 40 | <li><a href="../examples.html">Examples</a></li> |
|---|
| 41 | <li><a href="../downloads.html">Download</a></li> |
|---|
| 42 | <li><a href="http://trac.geoext.org/">Development</a></li> |
|---|
| 43 | </ul> |
|---|
| 44 | <div id="searchbox"> |
|---|
| 45 | <form class="search" action="../search.html" method="get"> |
|---|
| 46 | <input id="searchbox-query" type="text" name="q" size="25" value="Search …" tabindex="3" onblur="if(this.value=='') this.value='Search …';" onfocus="if(this.value=='Search …') this.value='';" /> |
|---|
| 47 | <input id="searchbox-submit" type="image" value="Search" src="../_static/img/search_icon_green.png" /> |
|---|
| 48 | <input type="hidden" name="check_keywords" value="yes" /> |
|---|
| 49 | <input type="hidden" name="area" value="default" /> |
|---|
| 50 | </form> |
|---|
| 51 | </div> |
|---|
| 52 | </div> |
|---|
| 53 | </div> |
|---|
| 54 | |
|---|
| 55 | <div class="related"> |
|---|
| 56 | <h3>Navigation</h3> |
|---|
| 57 | <ul> |
|---|
| 58 | <li><a href="../index.html">GeoExt</a> »</li> |
|---|
| 59 | <li><a href="index.html" accesskey="U">Core Concepts</a> »</li> |
|---|
| 60 | <li><a href="#">Primer: OpenLayers</a></li> |
|---|
| 61 | </ul> |
|---|
| 62 | </div> |
|---|
| 63 | |
|---|
| 64 | <div class="sphinxsidebar"> |
|---|
| 65 | <div class="sphinxsidebarwrapper"> |
|---|
| 66 | <h3><a href="../index.html">Table Of Contents</a></h3> |
|---|
| 67 | <ul> |
|---|
| 68 | <li><a class="reference external" href="#">Primer: OpenLayers</a><ul> |
|---|
| 69 | <li><a class="reference external" href="#layers">Layers</a><ul> |
|---|
| 70 | <li><a class="reference external" href="#the-wms-layer">The WMS Layer</a></li> |
|---|
| 71 | <li><a class="reference external" href="#the-vector-layer">The Vector Layer</a></li> |
|---|
| 72 | <li><a class="reference external" href="#other-layers">Other Layers</a></li> |
|---|
| 73 | </ul> |
|---|
| 74 | </li> |
|---|
| 75 | <li><a class="reference external" href="#controls">Controls</a><ul> |
|---|
| 76 | <li><a class="reference external" href="#navigationhistory-control">NavigationHistory Control</a></li> |
|---|
| 77 | <li><a class="reference external" href="#initialization-w-controls">Initialization w/ Controls</a></li> |
|---|
| 78 | <li><a class="reference external" href="#more-controls">More Controls</a></li> |
|---|
| 79 | </ul> |
|---|
| 80 | </li> |
|---|
| 81 | <li><a class="reference external" href="#events">Events</a><ul> |
|---|
| 82 | <li><a class="reference external" href="#geoext-events">GeoExt Events</a></li> |
|---|
| 83 | <li><a class="reference external" href="#openlayers-events">OpenLayers Events</a></li> |
|---|
| 84 | <li><a class="reference external" href="#more-information">More Information</a></li> |
|---|
| 85 | </ul> |
|---|
| 86 | </li> |
|---|
| 87 | </ul> |
|---|
| 88 | </li> |
|---|
| 89 | </ul> |
|---|
| 90 | |
|---|
| 91 | <h4>Previous topic</h4> |
|---|
| 92 | <p class="topless"><a href="ext-primer.html" |
|---|
| 93 | title="previous chapter">Primer: Ext</a></p> |
|---|
| 94 | <h4>Next topic</h4> |
|---|
| 95 | <p class="topless"><a href="../examples.html" |
|---|
| 96 | title="next chapter">Examples</a></p> |
|---|
| 97 | </div> |
|---|
| 98 | </div> |
|---|
| 99 | |
|---|
| 100 | |
|---|
| 101 | <div class="document"> |
|---|
| 102 | <div class="documentwrapper"> |
|---|
| 103 | <div class="bodywrapper"> |
|---|
| 104 | <div class="body"> |
|---|
| 105 | |
|---|
| 106 | <div class="section" id="primer-openlayers"> |
|---|
| 107 | <h1>Primer: OpenLayers<a class="headerlink" href="#primer-openlayers" title="Permalink to this headline">¶</a></h1> |
|---|
| 108 | <p>The OpenLayers mapping library is the key component of GeoExt, performing the |
|---|
| 109 | core map-related functions of every GeoExt-based application. To get up to speed |
|---|
| 110 | with GeoExt, let’s discover some OpenLayers basics.</p> |
|---|
| 111 | <div class="section" id="layers"> |
|---|
| 112 | <h2>Layers<a class="headerlink" href="#layers" title="Permalink to this headline">¶</a></h2> |
|---|
| 113 | <p>As its name suggests, OpenLayers manages a list of layers that together form a |
|---|
| 114 | web-based mapping client. Each layer represents a different set of data. For |
|---|
| 115 | instance, one layer might be responsible for displaying the boundary of a |
|---|
| 116 | country. Another layer responsible for that country’s roads.</p> |
|---|
| 117 | <p>OpenLayers contains many types of layers (you can see them all at the |
|---|
| 118 | <a class="reference external" href="http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Layer">OpenLayers website</a>). |
|---|
| 119 | For this primer, we’ll focus on two different layer types: <tt class="docutils literal"><span class="pre">WMS</span></tt> and |
|---|
| 120 | <tt class="docutils literal"><span class="pre">Vector</span></tt>.</p> |
|---|
| 121 | <div class="section" id="the-wms-layer"> |
|---|
| 122 | <h3>The WMS Layer<a class="headerlink" href="#the-wms-layer" title="Permalink to this headline">¶</a></h3> |
|---|
| 123 | <p>This is the canonical layer type found in almost all GeoExt applications, where |
|---|
| 124 | one or more images are used to display map-related information to the user. This |
|---|
| 125 | type is named ‘WMS’ because it implements the <a class="reference external" href="http://www.opengeospatial.org/standards/wms">Web Map Service</a> standard set by the <a class="reference external" href="http://www.opengeospatial.org/">Open |
|---|
| 126 | Geospatial Consortium.</a></p> |
|---|
| 127 | <p>If you followed the <a class="reference external" href="../tutorials/quickstart.html"><em>GeoExt QuickStart</em></a> guide, you will have already |
|---|
| 128 | encountered a <tt class="docutils literal"><span class="pre">MapPanel</span></tt> and created your very own WMS layer. Let’s dissect |
|---|
| 129 | what you did:</p> |
|---|
| 130 | <blockquote> |
|---|
| 131 | <div class="highlight-javascript"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1 |
|---|
| 132 | 2 |
|---|
| 133 | 3 |
|---|
| 134 | 4 |
|---|
| 135 | 5 |
|---|
| 136 | 6</pre></div></td><td class="code"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">layer</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Layer</span><span class="p">.</span><span class="nx">WMS</span><span class="p">(</span> |
|---|
| 137 | <span class="s2">"Global Imagery"</span><span class="p">,</span> |
|---|
| 138 | <span class="s2">"http://maps.opengeo.org/geowebcache/service/wms"</span><span class="p">,</span> |
|---|
| 139 | <span class="p">{</span><span class="nx">layers</span><span class="o">:</span> <span class="s2">"bluemarble"</span><span class="p">}</span> |
|---|
| 140 | <span class="p">);</span> |
|---|
| 141 | <span class="nx">map</span><span class="p">.</span><span class="nx">addLayer</span><span class="p">(</span><span class="nx">layer</span><span class="p">);</span> |
|---|
| 142 | </pre></div> |
|---|
| 143 | </td></tr></table></div> |
|---|
| 144 | </blockquote> |
|---|
| 145 | <p>This tells OpenLayers that you’d like to create a new WMS layer referenced by |
|---|
| 146 | the <tt class="docutils literal"><span class="pre">layer</span></tt> variable, and that you’d like to add that layer to the map. In |
|---|
| 147 | this case, we’re adding the <a class="reference external" href="http://earthobservatory.nasa.gov/Features/BlueMarble/">Blue Marble data set</a> provided by NASA.</p> |
|---|
| 148 | <p>In <strong>line 2</strong> we provide “Global Imagery” as the name of the layer. This can be |
|---|
| 149 | anything, and is only used to reference the layer on screen.</p> |
|---|
| 150 | <p>In <strong>line 3</strong> we provide the location of the WMS server tasked with providing |
|---|
| 151 | the images. Here, we use a GeoWebCache instance located at |
|---|
| 152 | <tt class="docutils literal"><span class="pre">maps.opengeo.org</span></tt>.</p> |
|---|
| 153 | <p>In <strong>line 4</strong> we provide extra parameters for the WMS server. Since many servers |
|---|
| 154 | host different data sets, we need to specify which set we’d like. We do this by |
|---|
| 155 | creating a new object and setting the <tt class="docutils literal"><span class="pre">layers</span></tt> property to <tt class="docutils literal"><span class="pre">"bluemarble"</span></tt>, |
|---|
| 156 | the identifier for the Blue Marble data set.</p> |
|---|
| 157 | <p>Note that <tt class="docutils literal"><span class="pre">layers</span></tt> isn’t the only WMS parameter we can provide. You can find |
|---|
| 158 | out more in the <a class="reference external" href="http://dev.openlayers.org/apidocs">OpenLayers API Documentation</a>, by selecting ‘Layer’ and then |
|---|
| 159 | ‘WMS’ in the navigation.</p> |
|---|
| 160 | <p>And that’s it! Now let’s move on to the vector layer.</p> |
|---|
| 161 | </div> |
|---|
| 162 | <div class="section" id="the-vector-layer"> |
|---|
| 163 | <h3>The Vector Layer<a class="headerlink" href="#the-vector-layer" title="Permalink to this headline">¶</a></h3> |
|---|
| 164 | <p>The WMS Layer, and many of the layer types provided by OpenLayers, use raster |
|---|
| 165 | files (images like JPG, GIF, and PNG) to display maps. However, OpenLayers can |
|---|
| 166 | also render map features directly in the browser, simply by adding an |
|---|
| 167 | <tt class="docutils literal"><span class="pre">OpenLayers.Layer.Vector</span></tt> to the map. This is useful when displaying data from |
|---|
| 168 | an OGC <cite>Web Feature Service <http://www.opengeospatial.org/standards/wfs></cite>, a |
|---|
| 169 | KML document, or even sketched in by the user. Here’s an example that generates |
|---|
| 170 | some random data and displays it in a vector layer:</p> |
|---|
| 171 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">vectorLayer</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Layer</span><span class="p">.</span><span class="nx">Vector</span><span class="p">();</span> |
|---|
| 172 | <span class="k">for</span> <span class="p">(</span><span class="kd">var</span> <span class="nx">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="nx">i</span> <span class="o"><</span> <span class="mi">10</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span><span class="p">){</span> |
|---|
| 173 | <span class="kd">var</span> <span class="nx">x</span> <span class="o">=</span> <span class="o">-</span><span class="mi">180</span> <span class="o">+</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">random</span><span class="p">()</span> <span class="o">*</span> <span class="mi">360</span><span class="p">;</span> |
|---|
| 174 | <span class="kd">var</span> <span class="nx">y</span> <span class="o">=</span> <span class="o">-</span><span class="mi">90</span> <span class="o">+</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">random</span><span class="p">()</span> <span class="o">*</span> <span class="mi">180</span><span class="p">;</span> |
|---|
| 175 | <span class="kd">var</span> <span class="nx">numSides</span> <span class="o">=</span> <span class="mi">3</span> <span class="o">+</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">round</span><span class="p">(</span><span class="nb">Math</span><span class="p">.</span><span class="nx">random</span><span class="p">()</span> <span class="o">*</span> <span class="mi">6</span><span class="p">);</span> |
|---|
| 176 | <span class="nx">vectorLayer</span><span class="p">.</span><span class="nx">addFeature</span><span class="p">(</span> |
|---|
| 177 | <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Feature</span><span class="p">.</span><span class="nx">Vector</span><span class="p">(</span> |
|---|
| 178 | <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Geometry</span><span class="p">.</span><span class="nx">Polygon</span><span class="p">.</span><span class="nx">createRegularPolygon</span><span class="p">(</span> |
|---|
| 179 | <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Geometry</span><span class="p">.</span><span class="nx">Point</span><span class="p">(</span><span class="nx">x</span><span class="p">,</span> <span class="nx">y</span><span class="p">),</span> |
|---|
| 180 | <span class="nx">numSides</span><span class="p">)));</span> |
|---|
| 181 | <span class="p">}</span> |
|---|
| 182 | |
|---|
| 183 | <span class="kd">var</span> <span class="nx">map</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Map</span><span class="p">();</span> |
|---|
| 184 | <span class="nx">map</span><span class="p">.</span><span class="nx">addLayer</span><span class="p">(</span><span class="nx">vectorLayer</span><span class="p">);</span> |
|---|
| 185 | </pre></div> |
|---|
| 186 | </div> |
|---|
| 187 | <p>While OpenLayers provides customized vector layers for loading data from |
|---|
| 188 | existing sources, the GeoExt team recommends that you use the generic vector |
|---|
| 189 | layer and populate it using <a title="GeoExt.data.FeatureStore" class="reference external" href="../lib/GeoExt/data/FeatureStore.html#GeoExt.data.FeatureStore"><tt class="xref docutils literal"><span class="pre">GeoExt.data.FeatureStore</span></tt></a>. For more |
|---|
| 190 | information on doing this, see <a class="reference external" href="../tutorials/remote-features-tutorial.html"><em>Vector Data Tutorial</em></a>.</p> |
|---|
| 191 | </div> |
|---|
| 192 | <div class="section" id="other-layers"> |
|---|
| 193 | <h3>Other Layers<a class="headerlink" href="#other-layers" title="Permalink to this headline">¶</a></h3> |
|---|
| 194 | <p>WMS and Vector are not the only layer types in OpenLayers. There are plenty more |
|---|
| 195 | available, including Google Maps, Virtual Earth, and many more. Browse the |
|---|
| 196 | <a class="reference external" href="http://dev.openlayers.org/apidocs">OpenLayers API documentation</a> for more |
|---|
| 197 | information.</p> |
|---|
| 198 | </div> |
|---|
| 199 | </div> |
|---|
| 200 | <div class="section" id="controls"> |
|---|
| 201 | <h2>Controls<a class="headerlink" href="#controls" title="Permalink to this headline">¶</a></h2> |
|---|
| 202 | <p>Although OpenLayers is great at managing layers, it also provides a way to |
|---|
| 203 | interact with those layers, primarily through the use of controls.</p> |
|---|
| 204 | <p>Controls are primary user interface elements and/or API hooks that control and |
|---|
| 205 | manage interaction with an OpenLayers map. For instance, panning and navigating |
|---|
| 206 | a map is handled by the <tt class="docutils literal"><span class="pre">OpenLayers.Control.Navigation</span></tt> control. If you want a |
|---|
| 207 | zoom bar in addition to zoom buttons, you’d add a <tt class="docutils literal"><span class="pre">PanZoomBar</span></tt> control. If you |
|---|
| 208 | then want to see where you’ve navigated, you’d use the <tt class="docutils literal"><span class="pre">NavigationHistory</span></tt> |
|---|
| 209 | control.</p> |
|---|
| 210 | <p>Each control provides different and unique functionality. For this primer, we’ll |
|---|
| 211 | focus only on the <tt class="docutils literal"><span class="pre">NavigationHistory</span></tt> control.</p> |
|---|
| 212 | <div class="section" id="navigationhistory-control"> |
|---|
| 213 | <h3>NavigationHistory Control<a class="headerlink" href="#navigationhistory-control" title="Permalink to this headline">¶</a></h3> |
|---|
| 214 | <p>Take a look at the OpenLayers <a class="reference external" href="http://openlayers.org/dev/examples/navigation-history.html">NavigationHistory control example</a>. If you view the |
|---|
| 215 | source, you’ll come across code like this:</p> |
|---|
| 216 | <blockquote> |
|---|
| 217 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">map</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Map</span><span class="p">(</span><span class="s1">'map'</span><span class="p">);</span> |
|---|
| 218 | <span class="kd">var</span> <span class="nx">nav</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">NavigationHistory</span><span class="p">();</span> |
|---|
| 219 | <span class="nx">map</span><span class="p">.</span><span class="nx">addControl</span><span class="p">(</span><span class="nx">nav</span><span class="p">);</span> |
|---|
| 220 | </pre></div> |
|---|
| 221 | </div> |
|---|
| 222 | </blockquote> |
|---|
| 223 | <p>The above code is fairly straightforward. First create a map, then a |
|---|
| 224 | <tt class="docutils literal"><span class="pre">NavigationHistory</span></tt> control, and then finally add that control to the map. If |
|---|
| 225 | you were to then look at your map in a web browser, you would only see the |
|---|
| 226 | layers that you had added – no special user interface elements for exploring |
|---|
| 227 | the navigation history.</p> |
|---|
| 228 | <p>This is because without more intervention, the NavigationHistory control only |
|---|
| 229 | provides an API allowing you to scroll through the history using a programmable |
|---|
| 230 | interface.</p> |
|---|
| 231 | <p>But the <tt class="docutils literal"><span class="pre">NavigationHistory</span></tt> control also provides a user interface. Let’s |
|---|
| 232 | continue on through the example:</p> |
|---|
| 233 | <blockquote> |
|---|
| 234 | <div class="highlight-javascript"><div class="highlight"><pre><span class="nx">panel</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">Panel</span><span class="p">({</span> |
|---|
| 235 | <span class="nx">div</span><span class="o">:</span> <span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s2">"panel"</span><span class="p">)</span> |
|---|
| 236 | <span class="p">});</span> |
|---|
| 237 | <span class="nx">panel</span><span class="p">.</span><span class="nx">addControls</span><span class="p">([</span><span class="nx">nav</span><span class="p">.</span><span class="nx">next</span><span class="p">,</span> <span class="nx">nav</span><span class="p">.</span><span class="nx">previous</span><span class="p">]);</span> |
|---|
| 238 | <span class="nx">map</span><span class="p">.</span><span class="nx">addControl</span><span class="p">(</span><span class="nx">panel</span><span class="p">);</span> |
|---|
| 239 | </pre></div> |
|---|
| 240 | </div> |
|---|
| 241 | </blockquote> |
|---|
| 242 | <p>To expose this interface, we first create a <tt class="docutils literal"><span class="pre">Panel</span></tt> control, and then add the |
|---|
| 243 | <tt class="docutils literal"><span class="pre">next</span></tt> and <tt class="docutils literal"><span class="pre">previous</span></tt> buttons to the panel giving the user something to |
|---|
| 244 | click on. We finally add the panel to the map.</p> |
|---|
| 245 | <p>Now try the example again in your browser. <em>Beautiful ain’t it?</em></p> |
|---|
| 246 | </div> |
|---|
| 247 | <div class="section" id="initialization-w-controls"> |
|---|
| 248 | <h3>Initialization w/ Controls<a class="headerlink" href="#initialization-w-controls" title="Permalink to this headline">¶</a></h3> |
|---|
| 249 | <p>In the above examples, we only added controls to the map using the |
|---|
| 250 | <tt class="docutils literal"><span class="pre">map.addControl()</span></tt> method. Often, controls are added when the map is |
|---|
| 251 | initialized bypassing the <tt class="docutils literal"><span class="pre">map.addControl()</span></tt> method. This is done simply by |
|---|
| 252 | using the <tt class="docutils literal"><span class="pre">controls</span></tt> key and passing an array of controls, as seen below.</p> |
|---|
| 253 | <blockquote> |
|---|
| 254 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">map</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Map</span><span class="p">({</span> |
|---|
| 255 | <span class="nx">controls</span><span class="o">:</span> <span class="p">[</span> |
|---|
| 256 | <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">Navigation</span><span class="p">(),</span> |
|---|
| 257 | <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">Measure</span><span class="p">()</span> |
|---|
| 258 | <span class="p">]</span> |
|---|
| 259 | <span class="p">});</span> |
|---|
| 260 | </pre></div> |
|---|
| 261 | </div> |
|---|
| 262 | </blockquote> |
|---|
| 263 | <div class="admonition note"> |
|---|
| 264 | <p class="first admonition-title">Note</p> |
|---|
| 265 | <p class="last">If you use the <tt class="docutils literal"><span class="pre">controls</span></tt> key, <strong>you will not be given the default |
|---|
| 266 | controls</strong> when initializing the map. You will have to add those controls |
|---|
| 267 | yourself instead. <a class="reference external" href="http://docs.openlayers.org/library/controls.html">Find out more.</a></p> |
|---|
| 268 | </div> |
|---|
| 269 | </div> |
|---|
| 270 | <div class="section" id="more-controls"> |
|---|
| 271 | <h3>More Controls<a class="headerlink" href="#more-controls" title="Permalink to this headline">¶</a></h3> |
|---|
| 272 | <p>You can find more controls by |
|---|
| 273 | <a class="reference external" href="http://trac.openlayers.org/browser/trunk/openlayers/lib/OpenLayers/Control">browsing the OpenLayers source code</a> |
|---|
| 274 | or by reading <a class="reference external" href="http://docs.openlayers.org/library/controls.html">OpenLayers’ Control documentation</a>.</p> |
|---|
| 275 | </div> |
|---|
| 276 | </div> |
|---|
| 277 | <div class="section" id="events"> |
|---|
| 278 | <h2>Events<a class="headerlink" href="#events" title="Permalink to this headline">¶</a></h2> |
|---|
| 279 | <p>Events are the main mechanism for notifying multiple objects that something has |
|---|
| 280 | happened. For instance, the <tt class="docutils literal"><span class="pre">NavigationHistory</span></tt> control listens to the map’s |
|---|
| 281 | <tt class="docutils literal"><span class="pre">zoomend</span></tt> event to save the user’s zoom history for a later date; similarly, |
|---|
| 282 | other objects may listen to the same event without interfering or knowing about |
|---|
| 283 | the <tt class="docutils literal"><span class="pre">NavigationHistory</span></tt> control. This makes events very powerful, allowing |
|---|
| 284 | objects to perform their desired function while decreasing coupling within |
|---|
| 285 | OpenLayers and Ext applications.</p> |
|---|
| 286 | <p>Both GeoExt and OpenLayers make extensive use of events. However, the OpenLayers |
|---|
| 287 | events are slightly different from those in GeoExt, though they provide the same |
|---|
| 288 | functionality. Let’s explore those differences.</p> |
|---|
| 289 | <div class="section" id="geoext-events"> |
|---|
| 290 | <h3>GeoExt Events<a class="headerlink" href="#geoext-events" title="Permalink to this headline">¶</a></h3> |
|---|
| 291 | <p>GeoExt uses the event library that comes standard with Ext. GeoExt events are |
|---|
| 292 | synonymous with Ext events.</p> |
|---|
| 293 | <p>Ext events can be used in any Ext or GeoExt components that extend the |
|---|
| 294 | <tt class="docutils literal"><span class="pre">Ext.util.Observable</span></tt> class. <a class="reference external" href="http://www.slideshare.net/sdhjl2000/ext-j-s-observable">More here.</a></p> |
|---|
| 295 | <p>To throw an event in any component that extends <tt class="docutils literal"><span class="pre">Ext.util.Observable</span></tt>, you |
|---|
| 296 | must first tell the component that the event may be thrown. For instance, in a |
|---|
| 297 | custom <tt class="docutils literal"><span class="pre">Ext.Panel</span></tt> class, this is done using the <tt class="docutils literal"><span class="pre">addEvents()</span></tt> method below.</p> |
|---|
| 298 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyPanel</span> <span class="o">=</span> <span class="nx">Ext</span><span class="p">.</span><span class="nx">extend</span><span class="p">(</span><span class="nx">Ext</span><span class="p">.</span><span class="nx">Panel</span><span class="p">,</span> <span class="p">{</span> |
|---|
| 299 | <span class="nx">initComponent</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> |
|---|
| 300 | <span class="c1">// ...</span> |
|---|
| 301 | <span class="k">this</span><span class="p">.</span><span class="nx">addEvents</span><span class="p">(</span><span class="s2">"event1"</span> <span class="cm">/*, "event2", ... etc.*/</span> <span class="p">);</span> |
|---|
| 302 | |
|---|
| 303 | <span class="nx">MyPanel</span><span class="p">.</span><span class="nx">superclass</span><span class="p">.</span><span class="nx">initComponent</span><span class="p">.</span><span class="nx">call</span><span class="p">(</span><span class="k">this</span><span class="p">);</span> |
|---|
| 304 | <span class="p">}</span> |
|---|
| 305 | <span class="p">});</span> |
|---|
| 306 | </pre></div> |
|---|
| 307 | </div> |
|---|
| 308 | <p>Finally triggering the event is easy:</p> |
|---|
| 309 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyPanel</span> <span class="o">=</span> <span class="nx">Ext</span><span class="p">.</span><span class="nx">extend</span><span class="p">(</span><span class="nx">Ext</span><span class="p">.</span><span class="nx">Panel</span><span class="p">,</span> <span class="p">{</span> |
|---|
| 310 | |
|---|
| 311 | <span class="c1">// ...</span> |
|---|
| 312 | |
|---|
| 313 | <span class="nx">myFunction</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> |
|---|
| 314 | <span class="kd">var</span> <span class="nx">arg1</span> <span class="o">=</span> <span class="s2">"somevalue"</span><span class="p">;</span> |
|---|
| 315 | <span class="k">this</span><span class="p">.</span><span class="nx">fireEvent</span><span class="p">(</span><span class="s2">"event1"</span><span class="p">,</span> <span class="nx">arg1</span> <span class="cm">/*, arg2, ... etc. */</span><span class="p">);</span> |
|---|
| 316 | <span class="p">}</span> |
|---|
| 317 | <span class="p">});</span> |
|---|
| 318 | </pre></div> |
|---|
| 319 | </div> |
|---|
| 320 | <p>Great! Now in order for the event to be useful, we have to listen to it. Below |
|---|
| 321 | is an example of adding two listeners to an instance of <tt class="docutils literal"><span class="pre">MyPanel</span></tt> using the |
|---|
| 322 | <tt class="docutils literal"><span class="pre">on()</span></tt> function, and then finally triggering the event by calling |
|---|
| 323 | <tt class="docutils literal"><span class="pre">myFunction()</span></tt>.</p> |
|---|
| 324 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">panel</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">MyPanel</span><span class="p">(</span><span class="cm">/* ... */</span><span class="p">);</span> |
|---|
| 325 | |
|---|
| 326 | <span class="c1">// First listener.</span> |
|---|
| 327 | <span class="nx">panel</span><span class="p">.</span><span class="nx">on</span><span class="p">(</span><span class="s2">"event1"</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">arg1</span><span class="p">)</span> <span class="p">{</span> |
|---|
| 328 | <span class="nx">alert</span><span class="p">(</span><span class="s2">"First listener responded. Got "</span> <span class="o">+</span> <span class="nx">arg1</span> <span class="o">+</span> <span class="s2">"!"</span><span class="p">);</span> |
|---|
| 329 | <span class="p">});</span> |
|---|
| 330 | |
|---|
| 331 | <span class="c1">// Second listener.</span> |
|---|
| 332 | <span class="nx">panel</span><span class="p">.</span><span class="nx">on</span><span class="p">(</span><span class="s2">"event1"</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">arg1</span><span class="p">)</span> <span class="p">{</span> |
|---|
| 333 | <span class="nx">alert</span><span class="p">(</span><span class="s2">"Second listener responded. Got "</span> <span class="o">+</span> <span class="nx">arg1</span> <span class="o">+</span> <span class="s2">"!"</span><span class="p">);</span> |
|---|
| 334 | <span class="p">});</span> |
|---|
| 335 | |
|---|
| 336 | <span class="nx">panel</span><span class="p">.</span><span class="nx">myFunction</span><span class="p">();</span> |
|---|
| 337 | </pre></div> |
|---|
| 338 | </div> |
|---|
| 339 | <div class="admonition note"> |
|---|
| 340 | <p class="first admonition-title">Note</p> |
|---|
| 341 | <p class="last">The <tt class="docutils literal"><span class="pre">on()</span></tt> function takes an optional third parameter that specifies |
|---|
| 342 | the scope of the listening function. If given, the <tt class="docutils literal"><span class="pre">this</span></tt> identifier |
|---|
| 343 | within the listening function will refer to the object passed.</p> |
|---|
| 344 | </div> |
|---|
| 345 | <p>And that’s it! Now let’s see how to do the same thing in OpenLayers.</p> |
|---|
| 346 | </div> |
|---|
| 347 | <div class="section" id="openlayers-events"> |
|---|
| 348 | <h3>OpenLayers Events<a class="headerlink" href="#openlayers-events" title="Permalink to this headline">¶</a></h3> |
|---|
| 349 | <p>OpenLayers provides similar functionality as the <tt class="docutils literal"><span class="pre">Ext.util.Observable</span></tt> class, |
|---|
| 350 | but it does so using the <tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt> class. Unlike |
|---|
| 351 | <tt class="docutils literal"><span class="pre">Ext.util.Observable</span></tt>, OpenLayers classes do not extend <tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt>.</p> |
|---|
| 352 | <p>Instead, it is customary for OpenLayers classes to create an attribute called |
|---|
| 353 | <tt class="docutils literal"><span class="pre">events</span></tt> that is an instance of <tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt>, as per the code below.</p> |
|---|
| 354 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyControl</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Class</span><span class="p">(</span><span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">,</span> <span class="p">{</span> |
|---|
| 355 | |
|---|
| 356 | <span class="nx">events</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span> |
|---|
| 357 | |
|---|
| 358 | <span class="nx">initialize</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> |
|---|
| 359 | <span class="k">this</span><span class="p">.</span><span class="nx">events</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Events</span><span class="p">(</span> |
|---|
| 360 | <span class="k">this</span><span class="p">,</span> |
|---|
| 361 | <span class="kc">null</span><span class="p">,</span> |
|---|
| 362 | <span class="p">[</span><span class="s2">"event1"</span> <span class="cm">/*, "event2", ... etc. */</span><span class="p">]</span> |
|---|
| 363 | <span class="kc">false</span> |
|---|
| 364 | <span class="p">);</span> |
|---|
| 365 | |
|---|
| 366 | <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">.</span><span class="nx">prototype</span><span class="p">.</span><span class="nx">initialize</span><span class="p">.</span><span class="nx">call</span><span class="p">(</span><span class="k">this</span><span class="p">);</span> |
|---|
| 367 | <span class="p">}</span> |
|---|
| 368 | <span class="p">});</span> |
|---|
| 369 | </pre></div> |
|---|
| 370 | </div> |
|---|
| 371 | <p>The first parameter to the <tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt> constructor is the object that |
|---|
| 372 | will ‘own’ these events – in other words, the caller that triggers the event. |
|---|
| 373 | In situations like the example above, it is usually <tt class="docutils literal"><span class="pre">this</span></tt>.</p> |
|---|
| 374 | <p>The second parameter specifies a <tt class="docutils literal"><span class="pre">div</span></tt> that will listen to events thrown by |
|---|
| 375 | the browser. Here, this functionality is ignored; see the note below.</p> |
|---|
| 376 | <p>The third parameter is an array specifying the events that this |
|---|
| 377 | <tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt> object can throw. This is analogous to |
|---|
| 378 | <tt class="docutils literal"><span class="pre">Ext.util.Observable</span></tt>‘s <tt class="docutils literal"><span class="pre">addEvents()</span></tt> method, and can accept any number of |
|---|
| 379 | events.</p> |
|---|
| 380 | <p>The fourth parameter is the <tt class="docutils literal"><span class="pre">fallthrough</span></tt>, a boolean that is related to the |
|---|
| 381 | second parameter above. For our purposes, we’ll leave it as <tt class="docutils literal"><span class="pre">false</span></tt>.</p> |
|---|
| 382 | <div class="admonition note"> |
|---|
| 383 | <p class="first admonition-title">Note</p> |
|---|
| 384 | <p class="last">The <tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt> class handles both browser events like when |
|---|
| 385 | the window resizes, as well as handling developer-created events like |
|---|
| 386 | <tt class="docutils literal"><span class="pre">event1</span></tt> above. This makes initializing an <tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt> object |
|---|
| 387 | fairly mucky, though using it like we did above is nearly the same. See more |
|---|
| 388 | below.</p> |
|---|
| 389 | </div> |
|---|
| 390 | <p>Triggering an event is just as easy as Ext’s <tt class="docutils literal"><span class="pre">fireEvent()</span></tt>, except here we use |
|---|
| 391 | <tt class="docutils literal"><span class="pre">triggerEvent()</span></tt>:</p> |
|---|
| 392 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyControl</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Class</span><span class="p">(</span><span class="nx">OpenLayers</span><span class="p">.</span><span class="nx">Control</span><span class="p">,</span> <span class="p">{</span> |
|---|
| 393 | |
|---|
| 394 | <span class="c1">// ...</span> |
|---|
| 395 | |
|---|
| 396 | <span class="nx">myFunction</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> |
|---|
| 397 | <span class="kd">var</span> <span class="nx">evt</span> <span class="o">=</span> <span class="p">{</span> |
|---|
| 398 | <span class="nx">arg1</span><span class="o">:</span> <span class="s2">"somevalue"</span> <span class="cm">/*, arg2: ..., ... etc.*/</span> |
|---|
| 399 | <span class="p">}</span> |
|---|
| 400 | <span class="k">this</span><span class="p">.</span><span class="nx">events</span><span class="p">.</span><span class="nx">triggerEvent</span><span class="p">(</span><span class="s2">"event1"</span><span class="p">,</span> <span class="nx">evt</span><span class="p">);</span> |
|---|
| 401 | <span class="p">}</span> |
|---|
| 402 | <span class="p">});</span> |
|---|
| 403 | </pre></div> |
|---|
| 404 | </div> |
|---|
| 405 | <div class="admonition note"> |
|---|
| 406 | <p class="first admonition-title">Note</p> |
|---|
| 407 | <p class="last"><tt class="docutils literal"><span class="pre">OpenLayers.Events</span></tt> passes data to listeners using a single object |
|---|
| 408 | with properties – otherwise called ‘the event object’ – instead of passing |
|---|
| 409 | function arguments like Ext. All listener functions, then, should only |
|---|
| 410 | expect one named argument. See example below.</p> |
|---|
| 411 | </div> |
|---|
| 412 | <p>Finally, let’s add two listeners and call <tt class="docutils literal"><span class="pre">myFunction()</span></tt>:</p> |
|---|
| 413 | <div class="highlight-javascript"><div class="highlight"><pre><span class="kd">var</span> <span class="nx">control</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">MyControl</span><span class="p">(</span><span class="cm">/* ... */</span><span class="p">);</span> |
|---|
| 414 | |
|---|
| 415 | <span class="c1">// First listener.</span> |
|---|
| 416 | <span class="nx">control</span><span class="p">.</span><span class="nx">events</span><span class="p">.</span><span class="nx">register</span><span class="p">(</span><span class="s2">"event1"</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">evt</span><span class="p">)</span> <span class="p">{</span> |
|---|
| 417 | <span class="nx">alert</span><span class="p">(</span><span class="s2">"First listener responded. Got "</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">arg1</span> <span class="o">+</span> <span class="s2">"!"</span><span class="p">);</span> |
|---|
| 418 | <span class="p">});</span> |
|---|
| 419 | |
|---|
| 420 | <span class="c1">// Second listener.</span> |
|---|
| 421 | <span class="nx">control</span><span class="p">.</span><span class="nx">events</span><span class="p">.</span><span class="nx">register</span><span class="p">(</span><span class="s2">"event1"</span><span class="p">,</span> <span class="kc">null</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">evt</span><span class="p">)</span> <span class="p">{</span> |
|---|
| 422 | <span class="nx">alert</span><span class="p">(</span><span class="s2">"Second listener responded. Got "</span> <span class="o">+</span> <span class="nx">evt</span><span class="p">.</span><span class="nx">arg1</span> <span class="o">+</span> <span class="s2">"!"</span><span class="p">);</span> |
|---|
| 423 | <span class="p">});</span> |
|---|
| 424 | |
|---|
| 425 | <span class="nx">control</span><span class="p">.</span><span class="nx">myFunction</span><span class="p">();</span> |
|---|
| 426 | </pre></div> |
|---|
| 427 | </div> |
|---|
| 428 | <div class="admonition note"> |
|---|
| 429 | <p class="first admonition-title">Note</p> |
|---|
| 430 | <p class="last">Like Ext’s <tt class="docutils literal"><span class="pre">on()</span></tt> function, OpenLayer’s <tt class="docutils literal"><span class="pre">register()</span></tt> function also |
|---|
| 431 | takes an optional <tt class="docutils literal"><span class="pre">scope</span></tt> value in order to specify the scope of the |
|---|
| 432 | listening function, but it expects this value as the second parameter passed |
|---|
| 433 | to the function. We don’t have a scope for our listeners in this example, |
|---|
| 434 | hence the <tt class="docutils literal"><span class="pre">null</span></tt> parameters.</p> |
|---|
| 435 | </div> |
|---|
| 436 | <p>And that’s it! Events in GeoExt should now be old hat. Fire away!</p> |
|---|
| 437 | </div> |
|---|
| 438 | <div class="section" id="more-information"> |
|---|
| 439 | <h3>More Information<a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h3> |
|---|
| 440 | <p>More information about both event types can be found at the links below:</p> |
|---|
| 441 | <ul class="simple"> |
|---|
| 442 | <li><a class="reference external" href="http://dev.openlayers.org/docs/files/OpenLayers/Events-js.html">OpenLayers Events Class Documentation</a></li> |
|---|
| 443 | <li><a class="reference external" href="http://dev.sencha.com/deploy/dev/docs/?class=Ext.util.Observable">Ext.util.Observable Class Documentation</a></li> |
|---|
| 444 | <li><a class="reference external" href="http://www.slideshare.net/sdhjl2000/ext-j-s-observable">Ext.util.Observable SlideShare</a></li> |
|---|
| 445 | </ul> |
|---|
| 446 | </div> |
|---|
| 447 | </div> |
|---|
| 448 | </div> |
|---|
| 449 | |
|---|
| 450 | |
|---|
| 451 | </div> |
|---|
| 452 | </div> |
|---|
| 453 | </div> |
|---|
| 454 | <div class="clearer"></div> |
|---|
| 455 | </div> |
|---|
| 456 | <div class="related"> |
|---|
| 457 | <h3>Navigation</h3> |
|---|
| 458 | <ul> |
|---|
| 459 | <li class="right" style="margin-right: 10px"> |
|---|
| 460 | <a href="../genindex.html" title="General Index" |
|---|
| 461 | accesskey="I">index</a></li> |
|---|
| 462 | <li class="right" > |
|---|
| 463 | <a href="../modindex.html" title="Global Module Index" |
|---|
| 464 | accesskey="M">modules</a> |</li> |
|---|
| 465 | <li class="right" > |
|---|
| 466 | <a href="../examples.html" title="Examples" |
|---|
| 467 | accesskey="N">next</a> |</li> |
|---|
| 468 | <li class="right" > |
|---|
| 469 | <a href="ext-primer.html" title="Primer: Ext" |
|---|
| 470 | accesskey="P">previous</a> |</li> |
|---|
| 471 | <li><a href="../index.html">GeoExt</a> »</li> |
|---|
| 472 | <li><a href="index.html" >Core Concepts</a> »</li> |
|---|
| 473 | <li><a href="#">Primer: OpenLayers</a></li> |
|---|
| 474 | </ul> |
|---|
| 475 | </div> |
|---|
| 476 | |
|---|
| 477 | <div class="footer"> |
|---|
| 478 | © Copyright 2009-2010, GeoExt Community. |
|---|
| 479 | </div> |
|---|
| 480 | </body> |
|---|
| 481 | </html> |
|---|
