[76] | 1 | .. highlight:: javascript |
---|
| 2 | |
---|
| 3 | ============================ |
---|
| 4 | Map Tool Tutorial |
---|
| 5 | ============================ |
---|
| 6 | |
---|
| 7 | Okay, so now you know how to :doc:`add a map to a web page <mappanel-tutorial>` |
---|
| 8 | and load some data into it. Your users can drag and zoom to their hearts' |
---|
| 9 | content. You even followed the :doc:`layertree-tutorial` so they could switch |
---|
| 10 | between different datasets. (You did follow that tutorial, right?) But now you |
---|
| 11 | want to do more than just view some pretty pictures. You want to let your users |
---|
| 12 | analyze data, or get more info about particular features on your map, or just |
---|
| 13 | draw things. Basically, you want to give them some **tools**\ . |
---|
| 14 | |
---|
| 15 | .. note:: This tutorial makes heavy use of the OpenLayers mapping library. If |
---|
| 16 | you're not familiar with it, you might want to take a look at the |
---|
| 17 | :doc:`/primers/openlayers-primer` before moving forward. |
---|
| 18 | |
---|
| 19 | OpenLayers Controls |
---|
| 20 | =================== |
---|
| 21 | |
---|
| 22 | In `OpenLayers <http://openlayers.org/>`_\ , these tools for interacting with a |
---|
| 23 | map are called ``Controls``\ . For the purposes of this tutorial, we'll just |
---|
| 24 | stick to the ``Measure`` control, a handy little tool that lets you draw a line |
---|
| 25 | on the map and tells you its length in real-world units. |
---|
| 26 | |
---|
| 27 | .. seealso:: The OpenLayer API documentation for a comprehensive listing of standard controls. |
---|
| 28 | |
---|
| 29 | ExtJS Buttons |
---|
| 30 | ============= |
---|
| 31 | |
---|
| 32 | While OpenLayers ``Control``\ s provide a number of excellent ways of |
---|
| 33 | interacting with maps, they have only limited support for actually manipulating |
---|
| 34 | the controls; ie, choosing which tool to use and providing user feedback about |
---|
| 35 | which tool is active. ExtJS provides a richer array of options for managing |
---|
| 36 | tools. Here is the idiomatic way to create an ``Ext.Button`` which activates and |
---|
| 37 | deactivates an OpenLayers ``Control``\ , and stays depressed while the control |
---|
| 38 | is active:: |
---|
| 39 | |
---|
| 40 | var control = new OpenLayers.Control.Measure(OpenLayers.Handler.Path, { |
---|
| 41 | eventListeners: { |
---|
| 42 | measure: function(evt) { |
---|
| 43 | alert("The measurement was " + evt.measure + evt.units); |
---|
| 44 | } |
---|
| 45 | } |
---|
| 46 | }); |
---|
| 47 | |
---|
| 48 | mapPanel.map.addControl(control); |
---|
| 49 | var button = new Ext.Button({ |
---|
| 50 | text: 'Measure Things', |
---|
| 51 | enableToggle: true, |
---|
| 52 | handler: function(toggled){ |
---|
| 53 | if (toggled) { |
---|
| 54 | control.activate(); |
---|
| 55 | } else { |
---|
| 56 | control.deactivate(); |
---|
| 57 | } |
---|
| 58 | } |
---|
| 59 | }); |
---|
| 60 | |
---|
| 61 | The ``Button`` can be added to an ExtJS toolbar or to a panel, in whatever |
---|
| 62 | layout we choose. For example, you could add the button to a ``MapPanel``\ 's |
---|
| 63 | top toolbar:: |
---|
| 64 | |
---|
| 65 | mapPanel.getTopToolbar().addButton(button); |
---|
| 66 | |
---|
| 67 | |
---|
| 68 | There Can Be Only One |
---|
| 69 | ===================== |
---|
| 70 | |
---|
| 71 | In general, when you have multiple tools associated with a map, you want to |
---|
| 72 | avoid having more than one tool active at the same time. It would be somewhat |
---|
| 73 | confusing if the user starts deleting data while he or she is trying to find the |
---|
| 74 | distance from one end of town to the other! Fortunately, ExtJS makes it very |
---|
| 75 | simple to ensure that only one toggle button from a group is toggled at a time, |
---|
| 76 | through the ``toggleGroup`` property of the ``Button`` object. This is a string |
---|
| 77 | identifying a group of buttons, only one of which can be pressed at a time. |
---|
| 78 | Let's extend our example from before, this time adding the option to measure |
---|
| 79 | area instead of length:: |
---|
| 80 | |
---|
| 81 | var length = new OpenLayers.Control.Measure(OpenLayers.Handler.Path, { |
---|
| 82 | eventListeners: { |
---|
| 83 | measure: function(evt) { |
---|
| 84 | alert("The length was " + evt.measure + evt.units); |
---|
| 85 | } |
---|
| 86 | } |
---|
| 87 | }); |
---|
| 88 | |
---|
| 89 | var area = new OpenLayers.Control.Measure(OpenLayers.Handler.Polygon, { |
---|
| 90 | eventListeners: { |
---|
| 91 | measure: function(evt) { |
---|
| 92 | alert("The area was " + evt.measure + evt.units); |
---|
| 93 | } |
---|
| 94 | } |
---|
| 95 | }); |
---|
| 96 | |
---|
| 97 | mapPanel.map.addControl(length); |
---|
| 98 | mapPanel.map.addControl(area); |
---|
| 99 | |
---|
| 100 | var toggleGroup = "measure controls"; |
---|
| 101 | |
---|
| 102 | var lengthButton = new Ext.Button({ |
---|
| 103 | text: 'Measure Length', |
---|
| 104 | enableToggle: true, |
---|
| 105 | toggleGroup: toggleGroup, |
---|
| 106 | handler: function(toggled){ |
---|
| 107 | if (toggled) { |
---|
| 108 | length.activate(); |
---|
| 109 | } else { |
---|
| 110 | length.deactivate(); |
---|
| 111 | } |
---|
| 112 | } |
---|
| 113 | }); |
---|
| 114 | |
---|
| 115 | var area = new Ext.Button({ |
---|
| 116 | text: 'Measure Area', |
---|
| 117 | enableToggle: true, |
---|
| 118 | toggleGroup: toggleGroup, |
---|
| 119 | handler: function(toggled){ |
---|
| 120 | if (toggled) { |
---|
| 121 | area.activate(); |
---|
| 122 | } else { |
---|
| 123 | area.deactivate(); |
---|
| 124 | } |
---|
| 125 | } |
---|
| 126 | }); |
---|
| 127 | |
---|
| 128 | All right, you've got all you need to add and activate tools to help users get |
---|
| 129 | the most out of your maps. |
---|