added README to gps module
[project/getlocations.git] / README.txt
1 for Drupal 7
2 Getlocations will provide a Google maps API version 3 enabled map on which to
3 display markers of locations found in location-enabled content-types.
4
5 INSTALL
6 Before installing getlocations please ensure that you have the libraries module installed
7
8 You can fetch markers from dropbox:
9 As tarballs:
10 http://dl.dropbox.com/u/41489105/Drupal/getlocations/getlocations-markers.tar.gz (required)
11 http://dl.dropbox.com/u/41489105/Drupal/getlocations/getlocations-markers-extra.tar.gz
12
13 As zipfles:
14 http://dl.dropbox.com/u/41489105/Drupal/getlocations/getlocations-markers.zip (required)
15 http://dl.dropbox.com/u/41489105/Drupal/getlocations/getlocations-markers-extra.zip
16
17 Download the file(s) and place them into your libraries folder so you have
18 a path something like this:
19 sites/all/libraries/getlocations/markers
20
21 The 'extra' files contain numbered and letter markers.
22 You can optionally add these if you need them.
23
24 CONFIGURE
25 You should configure Getlocations by visiting admin/config/services/getlocations.
26
27 USAGE
28 Getlocations maps can be displayed per node, eg "/getlocations/node/xxx"
29 will display all the locations associated with that node.
30
31 They can also be displayed per content-type, so if your content-type
32 has a machine name 'venue' you can show them all with
33 "/getlocations/type/venue".
34
35 With the above path you can add another two parameters which must be a
36 location key/value pair, so "/getlocations/type/venue/city/london" will
37 give you all the locations in London. The keys might typically be
38
39 lid
40 name
41 street
42 additional
43 city
44 province
45 postal_code
46 country
47 latitude
48 longitude
49 province_name
50 country_name
51
52 If you need more complex things use Views.
53
54 TODO
55 add location-enabled user ids once location handles users properly
56
57 You can display a list of location ids with something like
58 "getlocations/lids/1,2,3,4"
59 and a list of nodes with
60 "getlocations/nids/1,2,3,4"
61
62 There are some Views, disabled by default.
63 The getlocations View will provide a block that will appear when a location
64 enabled node is being shown. The block contains a link to a map.
65
66
67 Automatic Panning
68 This setting has 4 possibilities:
69 "None" is No panning.
70 This uses the default zoom and map center.
71
72 "Pan" keeps the markers in the Viewport.
73 This will try to fit the markers in by panning to them but uses
74 the default zoom.
75
76 "Pan and zoom" fits the markers to the Viewport.
77 This zooms in as far as it can and will fit all the markers onto the map.
78 This setting should only be used if you have less than 30 - 50 markers.
79
80 "Set Center" places the markers in the middle of the map.
81 This is similar to "Pan" but uses averaging to define the map center.
82
83
84 Which of these settings is best for your usecase depends on how many markers
85 you have and their 'spread', eg are they all in one region or spread out all
86 over the world.
87
88 Showing more than 30 -50 markers could lead to browser crash, remember that
89 it is the client browser not the server that is doing the work so you need to
90 test on slow machines and basic handheld devices to determine the best
91 settings for your site.
92
93 If you have many markers you can use MarkerClusterer to control your markers.
94 There is also a Markermanager but it is not as reliable.
95
96 If you have the Colorbox module installed and enabled in Get Locations
97 you can place any of the above paths in a colorbox iframe by replacing
98 'getlocations' with 'getlocations_box'.
99 To enable this for a link you can use the 'colorbox-load' method,
100 make sure that this feature has been enabled in colorbox
101 and use a url like this:
102 <a href="/getlocations_box/node/xxx?width=700&height=600&iframe=true" class="colorbox-load">See map</a>
103
104 or (advanced use) by adding rel="getlocationsbox" to the url, eg
105 <a href="/getlocations_box/node/xxx" rel="getlocationsbox">See map</a>
106
107 The last method uses the settings in admin/config/services/getlocations for
108 colorbox and uses its own colorbox event handler, see getlocations_colorbox.js.
109 You can define your own event handlers in your theme's javascript.
110 'getlocations_box' has it's own template, getlocations_box.tpl.php which can be
111 copied over to your theme's folder and tweaked there.
112
113 The InfoBubble javascript library is included and can be configured by copying
114 js/infobubble_options.txt to js/infobubble_options.js and editing that.
115
116 Getlocations now has hook_getlocations_markerdir()
117 from jhm http://drupal.org/user/15946
118 This hook allows other modules to add their own marker collections.
119 example:
120
121 function mymodule_getlocations_markerdir() {
122   $markers = drupal_get_path('module', 'mymodule') . '/mymarkers';
123   return $markers;
124 }
125
126 The above example requires the module mymodule to have a folder
127 mymodule/mymarkers which contains the bespoke markersets.
128 These will be added to the available markers when the
129 Marker Cache is regenerated.
130
131 In a Getlocations View, in Format: Getlocations | Settings,
132 if you have selected InfoBubble or InfoWindow in the Marker action dropdown
133 you will see a checkbox 'Replace default content' which when checked will
134 provide a list of available fields to use instead of the default content.
135
136 Geofield and Geolocation support
137 Getlocations provides some default Views to work with the
138 Geofield and Geolocation modules but if you want maps you will have to do
139 some tweaking.
140
141 Geofield:
142 In the Getlocations view, add a block and in 'Fields'
143 add Content: Location (or whatever you called it),
144 Select Formatter: Latitude only
145 Select Data options: Use full geometry
146 Select Format: decimal degrees
147 Under 'More' give it an Administrative title of 'latitude'
148
149 Repeat for longitude
150
151 Then add Content: Type
152 You should now have the following in Fields:
153 Content: Title
154 Content: Nid (make sure this has 'Rewrite the output of this field' and 'Output this field as a link' switched off)
155 latitude
156 longitude
157 Content: Type
158
159 They should be in that order.
160 exclude all from display except Content: Nid
161
162 Then add to Filter criteria
163 Content: Type and select the content type(s) you want
164
165 Under Format: select Getlocations and set up the map
166 Edit the Block title to whatever suits you
167 Save the view, enable the block and test.
168
169 You can do much the same in 'Getlocations links' View
170
171 Geolocation:
172 In the Getlocations view, add a block and in 'Fields'
173 add Content: Location (or whatever you called it),
174 Select Formatter: Latitude text-based formatter
175 Under 'More' give it an Administrative title of 'latitude'
176
177 Repeat for longitude
178
179 Then add Content: Type
180 You should now have the following in Fields:
181 Content: Title
182 Content: Nid (make sure this has 'Rewrite the output of this field' and 'Output this field as a link' switched off)
183 latitude
184 longitude
185 Content: Type
186
187 They should be in that order.
188 exclude all from display except Content: Nid
189
190 Then add to Filter criteria
191 Content: Type and select the content type(s) you want
192
193 Under Format: select Getlocations and set up the map
194 Edit the Block title to whatever suits you
195 Save the view, enable the block and test.
196
197 You can do much the same in 'Getlocations links' View
198
199 Addressfield support.
200 If the Addressfield module is supplying an address in conjunction with Geofield or Geolocation
201 the address will be used to populate the InfoWindow or InfoBubble.
202
203 Theming.
204 Getlocations pages can be themed by copying the relevant function to your theme's template.php,
205 renaming it in the usual manner.
206 eg
207 theme_getlocations_adinfo() becomes MYTHEME_getlocations_adinfo() where MYTHEME is the name of your theme.
208 You can edit it there to suit your needs.
209
210 These functions can be found in the file getlocations.module
211
212 Theming the content of InfoWindow or InfoBubble.
213 This is done with function theme_getlocations_adinfo()
214
215 Theming the map display.
216 This is done with function theme_getlocations_show()
217
218 Theming the Getlocations settings form.
219 This is done with function theme_getlocations_settings_form()
220
221 Theming the Getlocations options form in Views.
222 This is done with function theme_getlocations_plugin_style_map_options_form()
223
224 function template_preprocess_getlocations_box() and
225 function template_preprocess_getlocations_marker_box() are for use in conjunction
226 with the colorbox module and use the files getlocations_box.tpl.php and
227 getlocations_marker_box.tpl.php respectively.
228
229 You can now categorise markers in Views by adding Content: type (output machine name)
230 in the Fields section of a view. This will be passed on to the javascript, so you can add a button
231 to getlocations-view-map.tpl.php (by copying this file to your theme folder)
232 eg
233 <p><input type="button" value="Location off" id="toggle_loc"></p>
234
235 and adding something like:
236
237       // toggle location button
238       if ($("#toggle_loc").is("input")) {
239         $("#toggle_loc").click( function() {
240           k = 'key_1';
241           cat = 'location';
242           $.each(getlocations_markers[k].lids, function (lid, mark) {
243             if (getlocations_markers[k].cat[lid] == cat) {
244               vis = mark.getVisible();
245               if (vis) {
246                 mark.setVisible(false);
247                 $("#toggle_loc").val("Location on");
248               }
249               else {
250                 mark.setVisible(true);
251                 $("#toggle_loc").val("Location off");
252               }
253             }
254           });
255         });
256       }
257
258 to your theme's javascript
259 edit 'key_1' to whichever key your map is using
260 edit 'location' to the machine name of your content type
261 This will give you a button that can switch markers on/off
262
263
264 More information on theming can be found on http://drupal.org/documentation/theme
265
266 Polygons
267 To use polygons on your map you will need to enable the feature either globally
268 under admin/config/services/getlocations or per content type under Manage Display or
269 per map in a View under Format: Getlocations | Settings.
270 You will need to supply coordinates as a pipe (|) delimited list of lat,lon pairs
271 minimum 3 pairs.
272 eg
273 51.501579,-0.193544|51.498373,-0.144449|51.479882,-0.148054|51.484585,-0.184446
274
275 You can also have per polygon settings, here is a list of available options:
276 strokeColor       eg #0000FF
277 strokeOpacity     between 0 and 1
278 strokeWeight      eg 3
279 fillColor         eg #0000FF
280 fillOpacity       between 0 and 1
281 clickable         1 or 0
282 message           any text
283
284 These should be in the form of key:value
285 eg
286 strokeColor:#0000FF
287
288 You should add these to the pipe delimited list, eg
289
290 strokeColor:#0000FF|strokeOpacity:0.8|51.501579,-0.193544|51.498373,-0.144449|51.479882,-0.148054|51.484585,-0.184446
291
292 GeoJSON
293 Getlocations can support GeoJSON objects, see http://www.geojson.org/ for information about this format.
294 You can download the library from https://github.com/JasonSanford/GeoJSON-to-Google-Maps.
295 It should be installed in your libraries folder so you have a path something like this:
296 sites/all/libraries/GeoJSON/GeoJSON.js
297
298 Once the library is installed you can enable it globally, per view or per content type
299
300 Drush integration for getlocations.
301 'drush getlocations-markers' will install the basic getlocations marker set
302 'drush getlocations-geojson' will install the GeoJSON javascript library
303 If you want the library installed somewhere other than sites/all/libraries then provide the path after the command.
304