Cuarto parche ->no funcional<- de implementación de Ajax con jQuery en ver+ubicaciones.
[ecomupi.git] / include / maps / README
blob7f8b6a01d2bc09b1385998728919fd7bacf99a9a
1 NAME:
3     GoogleMapAPI - A library used for creating google maps.
5 AUTHOR:
6     Monte Ohrt <monte [AT] ohrt [DOT] com>
8 LATEST VERSION:
9     2.5 - Sep 20th, 2007
11 SYNOPSIS:
13     <?php
14     require('GoogleMapAPI.class.php');
16     $map = new GoogleMapAPI('map');
17     // setup database for geocode caching
18     $map->setDSN('mysql://USER:PASS@localhost/GEOCODES');
19     // enter YOUR Google Map Key
20     $map->setAPIKey('YOURGOOGLEMAPKEY');
21     
22     // create some map markers
23     $map->addMarkerByAddress('621 N 48th St # 6 Lincoln NE 68502','PJ Pizza','<b>PJ Pizza</b>');
24     $map->addMarkerByAddress('826 P St Lincoln NE 68502','Old Chicago','<b>Old Chicago</b>');
25     $map->addMarkerByAddress('3457 Holdrege St Lincoln NE 68502',"Valentino's","<b>Valentino's</b>");
26     ?>
28     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
29     <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
30     <head>
31     <?php $map->printHeaderJS(); ?>
32     <?php $map->printMapJS(); ?>
33     <!-- necessary for google maps polyline drawing in IE -->
34     <style type="text/css">
35       v\:* {
36         behavior:url(#default#VML);
37       }
38     </style>
39     </head>
40     <body onload="onLoad()">
41     <table border=1>
42     <tr><td>
43     <?php $map->printMap(); ?>
44     </td><td>
45     <?php $map->printSidebar(); ?>
46     </td></tr>
47     </table>
48     </body>
49     </html>
53 OUTPUT:
55     View the output of the above example here:
57     http://www.phpinsider.com/php/code/GoogleMapAPI/demo/
59     
60 DESCRIPTION:
62     GoogleMapAPI - A library used for creating google maps using the
63     Google Map public API. Features include multiple map markers, customizable
64     icons, map directions built into info window, and sidebar generation.
65     
66     More information on the Google Map API can be found here:
67     
68     http://www.google.com/apis/maps/
69     
71 DISCUSSION:
72 -----------
74     Discussions are currently held in the Smarty add-on forum (although Smarty
75     is not necessary to use GoogleMapAPI.)
77     http://www.phpinsider.com/smarty-forum/viewforum.php?f=19
78     
80 BASE CLASS METHODS:
81 -------------------
83     GoogleMapAPI($map_id = 'map', $app_id = 'MyMapApp')
84     ---------------------------------------------------
85     
86         Class Constructor.
87         The map id is needed only if you have multiple maps on the same page.
88         The App ID is used for the Yahoo GeoCode API, if you use Yahoo for lookups.
89         Use a unique App ID per application.
90         
91         Example:
92         
93         // use defaults
94         $map = new GoogleMapAPI();
96         // set custom map id and app id
97         $map = new GoogleMapAPI('mymap','myapp');
100     setDSN($dsn)
101     ------------
102     
103         Used to set the database DSN. The database is used to cache
104         geocode lookups (highly recommended!) The PEAR::DB module
105         is required for database access. You will need to create
106         the following database schema (mysql example given):
107         
108         CREATE TABLE GEOCODES (
109           address varchar(255) NOT NULL default '',
110           lon float default NULL,
111           lat float default NULL,
112           PRIMARY KEY  (address)
113         );
114         
115         Example:
116         
117         $map->setDSN('mysql://DBUSER:DBPASS@DBHOST/DBNAME');
118         $map->setDSN('mysql://geo:foobar@localhost/GEOCODES');
120     
121     setAPIKey($key)
122     ---------------
123     
124         Sets the Google Map API Key. This is mandatory, you will need
125         an API Key for your hostname! You can register free here:
126         
127         http://www.google.com/apis/maps/signup.html
129         Example:
130         
131         // enter YOUR registered API Key
132         $map->setAPIKey('ABQIAAAAxp5FF-A0RhHOnnTBwrlRbx');
135     setWidth($width)
136     ----------------
137     
138         Sets the width of the map window. This can be either px or %.
139         Default is 500px.
140     
141         Example:
142         
143         $map->setWidth('500px');
144         $map->setWidth('100%');
146     
147     setHeight($height)
148     ------------------
149     
150         Sets the height of the map window. This can be either px or %.
151         Default is '500px'.
152     
153         Example:
154         
155         $map->setHeight('500px');
156         $map->setHeight('100%');
157         
158         
159     enableMapControls()
160     -------------------
161     
162         This will enable the map controls to zoom/move around the map.
163         Enabled by default.
166     disableMapControls()
167     --------------------
168     
169         This will disable the map controls to zoom/move around the map.
170         Enabled by default.
173     setZoomLevel()
174     --------------
175     
176         This sets the default map zoom level.
177         
178         Example:
179         
180         $map->setZoomLevel(4);
183     setControlSize($size)
184     ---------------------
185     
186         This sets the map control size. Relevant only if map controls are
187         enabled. large = map zoom/move with slider. small = zoom/move without
188         slider. Large is default.
189         
190         Example:
191         
192         $map->setControlSize = 'small';
195     enableTypeControls()
196     --------------------
197     
198         This will enable the map type controls (map/satellite/hybrid).
199         Enabled by default.
202     disableTypeControls()
203     ---------------------
204     
205         This will disable the map type controls (map/satellite/hybrid).
206         Enabled by default.
209     setMapType($type)
210     -----------------
211     
212         This sets the default map type. Relevant only if map type controls are
213         enabled. map = default map. satellite = satellite view. hybrid = hybrid
214         view.
215         
216         Example:
217         
218         $map->setMapType('map'); // default
219         $map->setMapType('satellite');
220         $map->setMapType('hybrid');
221         
222         
223     enableSidebar()
224     ---------------
225     
226         This enables the map sidebar. Use printSideBar() or getSideBar() to
227         output the sidebar text. Enabled by default.
230     disableSidebar()
231     ----------------
232     
233         This disables the map sidebar. Enabled by default.
235     
236     enableDirections()
237     ------------------
238     
239         This enables map directions in the bottom of the pop-up info window.
240         Enabled by default.        
243     disableDirections()
244     -------------------
245     
246         This disables map directions in the bottom of the pop-up info window.
247         Enabled by default.
249     enableZoomEncompass()
250     ---------------------
251     
252         This enables zoom encompass so default map zoom is as small as possible
253         and include all map markers.
254         Enabled by Default.
256     disableZoomEncompass()
257     ----------------------
258     
259         This disables zoom encompass.
260         Enabled by Default.        
263     setBoundsFudge($val)
264     --------------------
265     
266         Set the map boundary fudge factor. This will adjust how much map
267         boundary encompasses the map markers. (0.01 is default.)
268         
269         Example:
270         
271         $map->setBoundsFudge(0.01);
272         
273         
274     setBrowserAlert($message)
275     -------------------------
276     
277         This sets the alert message that pops up when a browser is not
278         compatible with the Google Map API. Default is:
279         "Sorry, the Google Maps API is not compatible with this browser."
280         
281         
282     setJSAlert($message)
283     --------------------
284     
285         This sets the alert message that displays when javascript is disabled.
286         Default: "<b>Javascript must be enabled in order to use Google Maps.</b>"
287     
288         
289     enableOnLoad()
290     --------------
291     
292         This enables the onLoad() javascript function, which is used by default.
293         This allows the map javascript to be put into the <head></head> tag,
294         then loaded upon page entry with either <body onload="onLoad()"> right
295         in the body tag, or use printOnLoad() to place this elsewhere. With onLoad
296         disabled, the map javascript must be embedded inside the <body></body>
297         tags. Using onLoad() is the best method to use for browser
298         compatability.
301     enableInfoWindow()
302     ------------------
303     
304         enables info windows on map markers.
305         Enabled by default.
306     
308     disableInfoWindow()
309     -------------------
311         disables info windows on map markers.
312         Enabled by default.
315     enableScaleControl()
316     --------------------
317     
318     enables the map scale.
319     Enabled by default.
320     
322     disableScaleControl()
323     ---------------------
324     
325     disables the map scale.
326     Enabled by default.
329     enableOverviewControl()
330     -----------------------
331     
332     enables the map overview.
333     Disabled by default.
336     disableOverviewControl()
337     ------------------------
338     
339     disable the map overview.
340     Disabled by default.
342         
343     disableOnLoad()
344     ---------------
345     
346         This disables the onLoad() javascript function. (see enableOnLoad())
347         Enabled by default.
348         
349         
350     setInfoWindowTrigger($type)
351     ---------------------------
352     
353         This sets the info window trigger behavior. click = info window comes up
354         when clicking on a marker. mouseover = info window comes up when mousing
355         over a marker. Default is click.
356         
357         Example:
358         
359         $map->setInfoWindowTrigger('mouseover');
360                 
361                 
362     addMarkerByAddress($address,$title = '',$html = '')
363     ---------------------------------------------------
364     
365         This adds a marker to the map. The address must be a fully qualified
366         address that can be used by the available geocode lookup services.
367         
368         To add markers with geocodes directly, see addMarkerByCoords().
369         
370         The title is used for the sidebar navigation link. The html is used
371         in the info window that pops up when you click on the map marker. If
372         no html is provided, the title will be used.
373         
374         Note: map centering is done automatically as markers are added.
375         
376         Note: You can use tabbed windows by passing an array of
377             title=>text values as the $html parameter. If driving directions
378             are enabled, they show up under the first tab.
379                 
380         Example:
381         
382         $map->addMarkerByAddress('621 N 48th St # 6 Lincoln NE 68502','PJ Pizza','<b>PJ Pizza</b>');
383                 
384                 
385     addMarkerByCoords($lon,$lat,$title = '',$html = '')
386     ---------------------------------------------------
387     
388         This adds a map marker by geocode (lon/lat) directly. See
389         addMarkerByAddress() for more details.
391         Example:
392         
393         $map->addMarkerByAddress(-96.6539,40.8191,'PJ Pizza','<b>PJ Pizza</b>');
394         
395     
396    
397     addPolyLineByAddress($address1,$address2,$color,$weight,$opacity)
398     -----------------------------------------------------------------
399     
400         This adds a polyline between the two given addresses. You can optionally
401         supply a color (in #ffffff hex notation), weight (thickness in pixels),
402         and opacity (in percentage 0-100).
403         
404         Example:
405         
406         $map->addPolyLineByAddress(
407             '3457 Holdrege St Lincoln NE 68502',
408             '826 P St Lincoln NE 68502','#eeeeee',5,50);
409                 
410         
411     addPolyLineByCoords($lon1,$lat1,$lon2,$lat2,$color,$weight,$opacity)
412     --------------------------------------------------------------------
413     
414         This adds a polyline between the two given geocoordinate points. You can optionally
415         supply a color (in #ffffff hex notation), weight (line thickness in pixels),
416         and opacity (in percentage 0-100).
418         Example:
419         
420         $map->addPolyLineByCoords(-96.67,40.8279,-96.7095,40.8149,'#eeeeee',5,50);
422                 
423     adjustCenterCoords($lon,$lat)
424     -----------------------------
425     
426         This adjusts the map center coords by the given lon/lat. This is done
427         automatically as you add markers to the map, or you can do it manually
428         with this function. Note: this function is used internally by the
429         library, it isn't normally necessary unless you have a specific need and
430         you know what you are doing.
432         
433     setCenterCoords($lon,$lat)
434     --------------------------
435                 
436         This sets the map center coords to the given lon/lat. Center coords are
437         calculated automatically as you add markers to the map, or you reset it
438         manually with this function. Note: this function is used internally by
439         the library, it isn't normally necessary unless you have a specific need
440         and you know what you are doing.
443     setLookupService('GOOGLE')
444     -------------------------
445                 
446         This sets the geocode lookup service. Default is GOOGLE, which uses the
447         GOOGLE Geocode API. If you use the YAHOO Geocode API, be sure to set
448         your application ID when instantiating GoogleMapAPI. NOTE: Yahoo API
449         works only for US addresses (AFAIK).
450     
451     
452     setMarkerIcon($iconImage,$iconShadowImage,$iconAnchorX,$iconAnchorY,$infoWindowAnchorX,$infoWindowAnchorY)
453     ----------------------------------------------------------------------------------------------------------
454     
455         This sets the icon image for ALL the map markers. Call this once. If you
456         want to set a different icon for each marker, use addMarkerIcon()
457         instead.
458         
459         You must supply a separate image for the icon and its shadow.
460         iconAnchorX/Y is the X/Y coordinates of the icon for the map point.
461         infoWindowAnchorX/Y is the X/Y coordinates of the icon where the info
462         window connects.
463         
464         The iconImage and iconShadowImage can be either fully qualified URLs, or
465         a relative path from your web server DOCUMENT_ROOT. These images MUST
466         exist and readable so the library can calculate the dimensions.
467         
468         Example:
469         
470         $map->setMarkerIcon('/images/house.png','/images/house_shadow.png',0,0,10,10);
473     addMarkerIcon($iconImage,$iconShadowImage,$iconAnchorX,$iconAnchorY,$infoWindowAnchorX,$infoWindowAnchorY)
474     ----------------------------------------------------------------------------------------------------------
475     
476         This sets the icon image for the CURRENT map marker. IMPORTANT: you MUST
477         call addMarkerIcon() once for every marker. Do not use setMarkerIcon()
478         if you use this function.
479         
480         You must supply a separate image for the icon and its shadow.
481         iconAnchorX/Y is the X/Y coordinates of the icon for the map point.
482         infoWindowAnchorX/Y is the X/Y coordinates of the icon where the info
483         window connects.
484         
485         The iconImage and iconShadowImage can be either fully qualified URLs, or
486         a relative path from your web server DOCUMENT_ROOT. These images MUST
487         exist and readable so the library can calculate the dimensions.
488         
489         Example:
490         
491         $map->addMarkerIcon('/images/house.png','/images/house_shadow.png',0,0,10,10);
494     printHeaderJS()
495     ---------------
497         This prints the header javascript that goes into the <head></head> tags.
498         To return the header javascript in a variable, use getHeaderJS().
499         
500         Example:
501         
502         <head>
503         <?php $map->printHeaderJS(); ?>
504         </head>
505     
507     getHeaderJS()
508     -------------
509     
510         This returns the header javascript that goes into the <head></head> tags.
511         To print the header javascript directly, use printHeaderJS().
512         
513         Example:
514         
515         <?php
516         $headerjs = getHeaderJS();
517         ?>
518         <head>
519         <?php echo $headerjs; ?>
520         </head>
521         
522         
523     printMapJS()
524     ------------
526         This prints the map javascript. If onLoad() is enabled, put this in the
527         <head></head> tags, and supply <body onload="onLoad()"> in the body tag
528         (or use printOnLoad()).
529         
530         Otherwise, put this just before the </body> tag to make it load
531         automatically. Note that using onLoad() is recommended over this method.
532         
533         To return the map javascript in a variable, use getMapJS().
534         
535         Example:
536         
537         <head>
538         <?php $map->printMapJS(); ?>
539         </head>
540     
541     
542     getMapJS()
543     ----------
545         This returns the map javascript that goes into the <head></head> tags.
546         To print the map javascript directly, use printMapJS().
547         
548         Example:
549         
550         <?php
551         $mapjs = $map->printMapJS();
552         ?>
553         <head>
554         <?php echo $mapjs; ?>
555         </head>
558     printOnLoad()
559     -------------
561         This prints the onLoad() javascript call. This is an alternate to
562         using <body onload="onLoad()"> in the body tag. You can place
563         this anywhere in the html body.
564         
565         To return the onLoad() javascript in a variable, use getOnLoad().
566         
567         Example:
568         
569         <head>
570         <?php $map->printMapJS(); ?>
571         </head>
572         <body>
573         <?php echo $map->printMap(); ?>
574         <?php $map->printOnLoad(); ?>
575         </body>
576     
577     
578     getOnLoad()
579     -----------
581         This returns the map javascript that goes into the <head></head> tags.
582         To print the map javascript directly, use printMapJS().
583         
584         Example:
585         
586         <?php
587         $onload = $map->getOnLoad();
588         $mapjs = $map->getMapJS();
589         $map = $map->getMap();
590         ?>
591         <head>
592         <?php echo $mapjs; ?>
593         </head>
594         <body>
595         <?php echo $map; ?>
596         <?php echo $onload; ?>
597         </body>
599         
600         
601     printMap()
602     ----------
604         This prints the map html.
605         To return the map html in a variable, use getMap().
606         
607         Example:
608         
609         <head>
610         <?php $map->printMapJS(); ?>
611         </head>
612         <body onload="onLoad()">
613         <?php echo $map->printMap(); ?>
614         </body>
616         Example 2 (using printOnLoad):
617         
618         <head>
619         <?php $map->printMapJS(); ?>
620         </head>
621         <body>
622         <?php echo $map->printMap(); ?>
623         <?php echo $map->printOnLoad(); ?>
624         </body>
626     
627     
628     getMap()
629     --------
631         This returns the map html in a variable.
632         To print the map html directly, use printMap().
633         
634         Example:
635         
636         <?php
637         $map = $map->getMap();
638         ?>
639         <body onload="onLoad()">
640         <?php echo $map; ?>
641         </body>
644     printSidebar()
645     --------------
647         This prints the sidebar html.
648         To return the sidebar html in a variable, use getSidebar().
649         
650         Example:
651         
652         <body onload="onLoad()">
653         <table>
654          <tr>
655           <td>
656            <?php $map->printMap(); ?>
657           </td>
658           <td>
659            <?php $map->printSidebar(); ?>
660           </td>
661          </tr>
662         </table>
663         </body>
664     
665     
666     getSidebar()
667     ------------
669         This returns the sidebar html in a variable.
670         To print the sidbar html directly, use printSidebar().
671         
672         Example:
673         
674         <?php
675         $map = $map->getMap();
676         $sidebar = $map->getSidebar();
677         ?>
678         <body onload="onLoad()">
679         <table>
680          <tr>
681           <td>
682           <?php echo $map; ?>
683           </td>
684           <td>
685            <?php echo $sidebar; ?>
686           </td>
687          </tr>
688         </table>
689         </body>
690                 
691     
692     getGeocode($address)
693     --------------------
694     
695         This looks up the geocode of an address. It will use the database cache
696         if available. If you want to lookup a geocode without using the database
697         cache, use geoGetCoords(). Note: this function is used internally by the
698         library, it isn't normally necessary unless you have a specific need and
699         you know what you are doing.
700         
701         Example:
702         
703         $geocode = $map->getGeocode('237 S 70th suite 220 Lincoln NE 68510');
704         
705         echo $geocode['lat'];
706         echo $geocode['lon'];
707         
708         
709     getCache($address)
710     ------------------
711     
712         This will get the cached geocode info for an address from the database
713         cache, or return FALSE if nothing is available. Note: this function is
714         used internally by the library, it isn't normally necessary unless you
715         have a specific need and you know what you are doing.
716         
717         Example:
718         
719         $geocode = $map->getCache('237 S 70th suite 220 Lincoln NE 68510');
720         
721         echo $geocode['lat'];
722         echo $geocode['lon'];
723         
725     putCache($address,$lon,$lat)
726     ----------------------------
727     
728         This will insert geocode info for the given address into the database
729         cache. Note: this function is used internally by the library, it isn't
730         normally necessary unless you have a specific need and you know what you
731         are doing.
732         
733         Example:
734         
735         $map->putCache('237 S 70th suite 220 Lincoln NE 68510',-96.62538,40.812438);
736         
738     geoGetCoords($address)
739     ----------------------
740     
741         This looks up the geocode of an address directly (not from cache.) Note:
742         this function is used internally by the library, it isn't normally
743         necessary unless you have a specific need and you know what you are
744         doing.
745         
746         Example:
747         
748         $geocode = $map->geoGetCoords('237 S 70th suite 220 Lincoln NE 68510');
749         
750         echo $geocode['lon'];
751         echo $geocode['lat'];
753     geoGetDistance($lat1,$lon1,$lat2,$lon2,$unit)
754     ---------------------------------------------
756         This gets the distance between too coordinate points using the great
757         circle formula. $unit can be M (miles),K (kilometers),N (nautical
758         miles),I (inches), or F (feet). Default is M.   
759         
760         Example:
761         
762         $distance = $map->geoGetDistance($lat1,$lon1,$lat2,$lon2,$unit);
764         
765         
766 INTEGRATING GOOGLE MAPS WITH SMARTY TEMPLATES
767 ---------------------------------------------
769     Integrating with Smarty is as simple as assigning the necessary vars to the
770     template and then displaying them. Note: This example does not cover how to
771     setup Smarty, please use the Smarty documentation.
772     
773     Example:
774     
775     <?php
776     require('Smarty.class.php');
777     require('GoogleMapAPI.class.php');
779     $smarty = new Smarty();
780     $map = new GoogleMapAPI();
781     
782     // setup database for geocode caching
783     $map->setDSN('mysql://USER:PASS@localhost/GEOCODES');
784     // enter YOUR Google Map Key
785     $map->setAPIKey('YOURGOOGLEMAPKEY');
786     
787     // create some map markers
788     $map->addMarkerByAddress('621 N 48th St # 6 Lincoln NE 68502','PJ Pizza','<b>PJ Pizza</b>');
789     $map->addMarkerByAddress('826 P St Lincoln NE 68502','Old Chicago','<b>Old Chicago</b>');
790     $map->addMarkerByAddress('3457 Holdrege St Lincoln NE 68502',"Valentino's","<b>Valentino's</b>");
791     
792     // assign Smarty variables;
793     
794     $smarty->assign('google_map_header',$map->getHeaderJS());
795     $smarty->assign('google_map_js',$map->getMapJS());
796     $smarty->assign('google_map_sidebar',$map->getSidebar());
797     $smarty->assign('google_map',$map->getMap());
798     
799     // display the template
800     $smarty->display('index.tpl');
801     ?>
802     
803     contents of index.tpl:
804     ----------------------
805     
806     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
807     <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
808     <head>
809     {$google_map_header}
810     {$google_map_js}
811     <!-- necessary for google maps polyline drawing in IE -->
812     <style type="text/css">
813       v\:* {ldelim}
814         behavior:url(#default#VML);
815      {rdelim} 
816     </style>
817     </head>
818     <body onload="onLoad()">
819     <table>
820       <tr>
821         <td>{$google_map}</td>
822         <td>{$google_map_sidebar}</td>
823       </tr>
824     </table>
825     </body>
826     </html>
829 CREDITS:
830 --------
832 Excellent Google Maps tutorials by Mike:
833 http://www.econym.demon.co.uk/googlemaps/index.htm
835 People who have helped/contributed:
837 Charlie Dawes
838 Jake Krohn
839 Clark Freifeld <clark AT users DOT sourceforge DOT net>
840 Angelo Conforti
841 Jerome Combaz
842 drakos7 (from forums)
843 nmweb (from forums)
845 Anyone I missed, drop me a line!
847 Monte Ohrt <monte [AT] ohrt [DOT] com>