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. |
---|