Difference between revisions of "Linden Lab Official:Map API"

From Second Life Wiki
Jump to navigation Jump to search
 
(162 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{:API Portal/navigation}}
{{Supported API}}
{{:API Portal/navigation|map}}
Extend the reach of your Web site into Second Life using the ''Second Life Map API'', which enables you to embed interactive Second Life maps directly into your web pages. These maps look and act much like Google Maps, except that, instead of the Earth, they display the topography of the Second Life virtual world. See http://maps.secondlife.com/ for an example.


__TOC__
When you use the Map API to embed Second Life maps on your site, your visitors can:


* Click and drag the mouse pointer to pan the map view up, down, left, and right.
* Double-click to zoom in by one level (power of two) and display the teleport window.
* Click anywhere on the map to open a "teleport" window.
* Use the mouse wheel or pan controls to zoom in and out.


'''Update notice:  We've made improvements and changes to the webmap, effective January 15, 2009.
For more information, see [[Map API Introduction]].
'''Some information here may be out of date as we update this wiki with the changes.  Thanks for your patience. 
<br clear="all"/>
 
== Getting Started ==
 
=== What is the Webmap API? ===
 
The Second Life Webmap API allows you to embed Second Life Maps onto your web pages.  If needed for your application, you can also [http://wiki.secondlife.com/wiki/Webmap_API#Accessing_map_images_directly directly access] the webmap images.  Enough talk, lets jump into the code.
 
'''Disclaimer:'''
This API is still in beta. This means URLs and API signatures may change. Check this page for announcements.
 
=== API Requirements ===
The Second Life Webmap API is currently being changed to use the Google Maps API as the core of the API.  You will need to signup for the Google Maps API to get a key that will enable you to use the Google Maps API.
 
[http://www.google.com/apis/maps/signup.html Sign Up for the Google Maps API]
 
You will also need a copy of [http://www.prototypejs.org/ prototype.js] and [http://script.aculo.us/ scriptaculous.js]
 
Versions to use:<br/>
prototype.js &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'''version 1.5.0'''<br/>
scriptaculous.js &nbsp;&nbsp;'''version 1.7.0'''<br/>
 
And finally, you will need the Second Life Map API wrapper for the Google Maps API.  This wrapper creates the same functionality that was available in the previous Second Life Map API.
 
[http://s3.amazonaws.com/static-secondlife-com/_scripts/slmapapi.js Second Life Map API Wrapper]
 
'''WARNING:'''
The above file is a beta file.  It also has hardcoded functions related to the voice enabled status of regions displayed.
 
== Basic Examples ==
=== First Example: A Basic Map ===
 
The steps for creating this example are as follows:
 
For your pages using the webmap API, first include the references to protoype.js and scriptaculous.js:<br/>
<pre><script src="prototype.js" type="text/javascript"></script>
<script src="scriptaculous/scriptaculous.js" type="text/javascript"></script>
</pre>
<br/>
Next you must include the reference for the Google Maps API:<br/>
<pre>
<script src=<nowiki>"http://maps.google.com/maps?file=api&amp;v=2&amp;key={YOUR GOOGLE MAPS KEY GOES HERE}"</nowiki> type="text/javascript"></script>
</pre>
<br/>
Finally you must include the reference to the Second Life MapAPI wrapper for the Google Maps API:<br/>
<pre>
<script src="<nowiki>http://s3.amazonaws.com/static-secondlife-com/_scripts/slmapapi.js</nowiki>" type="text/javascript"></script>
</pre>
<br/>
Next you'll need to create a div element which will contain your map. Note, if you would like the position attribute of this div element to be absolute, please either set it programmatically via javascript or using the style attribute tag. Setting the position attribute of this element in the CSS style sheet will not work.<br/>
<br/>
<pre>
<div id='map-element'></div>
</pre>
<br/>
Nex't you'll need to add the following javascript to your page to instantiate the map and center it. <br/><br/>
<pre>
mapInstance = new SLMap(document.getElementById('map-container'));
mapInstance.centerAndZoomAtSLCoord(new XYPoint(1000,1000),3);
</pre>
<br/>
<br/>
We've added this javascript to a function that gets called when the page loads (by setting the body's onload event handler). After the div element is passed to the map constructor, all that is left to do is to center the map and set the zoom.
<br/><br/>
'''About Coordinates:'''<br/>
The coordinates used for the Webmap are based on our grid system for positioning regions. If you are curious what position corresponds to which XY coordinate, please use this application.
<br/><br/>
'''About Zoom Levels:'''<br/>
Currently there are six zoom levels, one through six, one being the closest and six being the farthest. Each level zooms by a power of two. In other words, at zoom level five, each region is twice the width as it was at zoom level six.
<br/><br/>
After you've finished adding this code to your page, you'll have working Second Life Map on your homepage. The next sections will cover some other features of the map like adding markers and windows.
<br/><br/>
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Second Example: A Map with Markers ===
 
This example shows how to make a map with a marker. The code is the same as the first example, with extra lines of javascript added after the initialization of the map.
<pre>
// creates the icons
var yellow_dot_image = new Img("b_map_yellow.gif",9,9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];
 
// creates the marker
var marker = new Marker(all_images, new XYPoint(997,1002));
mapInstance.addMarker(marker);
</pre>
 
The code above first creates the icon for the marker, then it to the map at (997, 1002) (where the Welcome Area Fountain is). Clicking on this marker does nothing, but read the following sections to find out how to do more.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
=== Third Example: A Map with Windows ===
This example shows how to create a map a window. The code is the same as the first example, with extra lines of javascript added after the initialization of the map. In addition, the map is centered in a different location in order to make the window fully visible.
 
<pre>
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!!");
mapInstance.addMapWindow(mapWindow, new XYPoint(997,1002));
</pre>
 
The code above adds an open window to the map positioned again at xxx.x, xxx.x, right above the Welcome Area Fountain. Note, after you close the window there is no way of bringing it back, unless you are using markers with windows. Read on to find out how to do this.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
=== Fourth Example: Markers with Windows ===
This example shows how to create a map with a marker which opens a window when clicked. The code is a combination of the first, second and third examples. We have the following after we initialize the map:
 
<pre>
// creates the icons
var yellow_dot_image = new Img("b_map_yellow.gif",9,9);
var yellow_icon = new Icon(yellow_dot_image);
var all_images = [yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon, yellow_icon];
 
// creates the marker
var marker = new Marker(all_images, new XYPoint(997,1002));
mapInstance.addMarker(marker);
 
// creates a window
var mapWindow = new MapWindow("This is where the welcome area fountain is!! <br><img src='fountain.gif'>");
 
// adds the marker to the map
mapInstance.addMarker(marker, mapWindow);
</pre>
 
The code above adds a marker and when clicked, opens an window. If the window is closed, it can be opened again by clicking on the marker again.
 
In these 4 examples we've shown you all the basic uses of the map. Yep, its really pretty simple if you ask us. If you want to read about some more advanced features of the map, you can read the next section.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
== Advanced Examples ==
=== Using Second Life Region Names (NOT IMPLEMENTED) ===
I know you've been wondering, what if I don't know which XY coordinate corresponds to which region name? Well, with this feature you can now use region names to define locations on the map instead of XY coordinates. If you'd like, skip to the example.
 
<pre>
SLPoint('ahern',128,128); // use this instead of XYPoint(997,1002)
</pre>
 
The above code simply creates an SLPoint located at the Welcome Area. Instead of having to figure out the XY coodinates, we were just able to use the region name. With this SLPoint now we can do whatever we want with it, like recenter the map here, put a window here, or put a marker here.
 
Note - The region name is case insensitive, so to specificy "Da Boom" region, you could use:
 
<pre>
SLPoint("da boom") // OR
SLPoint("dA bOOm")
</pre>
 
 
----
 
 
=== Linking to a Second Life Coordinate using XY Coordinates (NEW) ===
We've created an easy function to use in order to teleport your users to an absolute coordinate, for example 1000.5, 1000.5. If you'd like, skip to the example.
 
<pre>
gotoSLURL(997,1002);
</pre>
 
The above code will open up the Second Life client and then teleport the user to (997,1002) (where the welcome area fountain is).
 
 
 
 
=== Removing a Marker ===
Markers can be removed by passing the original marker to the removeMarker function. If you'd like, skip to the example.
 
<pre>
mapInstance.removeMarker(marker);
</pre>
 
The above code simply removes the marker, where marker is a reference to the original marker.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Removing Zoom and Pan Controls / Making your Own ===
If you'd like to remove all the panning and zooming controls, or would like to create your own, its all pretty easy. If you'd like, skip to the example.
 
<pre>
mapInstance = new SLMap(document.getElementById('map-container'), {hasZoomControls: false, hasPanningControls: false});
</pre>
 
The above code sets the map options hasZoomControls as false and hasPanControls as also false.
 
Now, if we'd like to create our own zoom and pan controls, its not that hard either. We have created functions setCurrentZoomLevel(), getCurrentZoomLevel(), zoomIn(), zoomOut, panLeft, panRight, panUp and panDown so that you can essentially skin your maps.
 
In our example we've created an anchored link for each function, which will call its respective function when it is clicked.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Disabling/Enabling Dragging ===
Say you'd like to disable dragging on the map. No problem. If you'd like, skip to the example.
 
<pre>
mapInstance.disableDragging();
</pre>
 
 
This one is simple, simply call disableDragging on the map object. When you are done just call enableDragging() on the map object to make it all normal again.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Panning or Recentering the Map ===
This feature will let you pan the map to a specific coordinate. If the coordinate is not currently visible on the map, the map will instead just recenter the map to this location. If you'd like, skip to the example.
 
<pre>
mapInstance.panOrRecenterToSLCoord(new XYPoint(1000,1000), true);
</pre>
 
The above code pans or recenters to (1000,1000) depending on the current view. The second parameter is optional, and if it is set to true, centers the map on the coordinate even if it is currently in the viewport.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Setting a Marker's Event Handlers ===
The following two features are pretty cool in our opinion. In a nutshell they'll allow you to do some interesting things. If you'd like, skip to the example.
 
Lets say you want to something else to happen besides a window opening when a marker is clicked. Like, for example, to retrieve a page about that specific coordinate or to show trigger some other javascript functionality you have on your page? Well, all this is possible.
 
<pre>
// creates a function that we will bind to the marker click action
var doMarkerAction = function(marker) {
alert("an event occured at (" + marker.slCoord.x + "," + marker.slCoord.y + ")");
};
 
// creates the marker and sets its event handlers
var marker = new Marker(all_images, new XYPoint(997,1002), {clickHandler: doMarkerAction, onMouseOutHandler: doMarkerAction, onMouseOverHandler: doMarkerAction});
</pre>
 
The code above simple sets the click handler, onmouseover, and onmouseout handlers of the marker to a function we've defined: doMarkerAction(). The marker is passed as a parameter to this function, so, if we want, we can remove it from the map, or just see what coordinate it lies on.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Setting a Double Click Handler ===
This feature of the map is very similar to the previous example, except it instead of the user having to click on a marker, he can click on anywhere on the map. Cool? Yes we think so. Heres an simpler example to look at.
 
<pre>
// creates a function that we will bind to the double click action
var doubleClickHandlerFunction = function(x,y) {
alert("you double clicked at (" + x + "," + y + ")");
};
 
// creates the map
var mapInstance = new SLMap(document.getElementById('map-container'),{doubleClickHandler: doubleClickHandlerFunction});
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997.5,1001.5),2);
</pre>
 
The above code will fire off a javascript alert with the X and Y coordinate clicked. The X and Y coordinate will be passed as parameters to the function you specify to be the double click handler.
 
Similarly to the doubleClickHandler option, you can now set the singleClickHandler option. Please refer to this example
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Setting a On State Changed Handler ===
Lets say whenever the user moves around or zooms on the map, we want to fire off some function. With the onStateChangedHandler option, we can set a handler function to be called whenever this happens. If you'd like, skip to the example.
 
<pre>
mapInstance = new SLMap(document.getElementById('map-container'), {onStateChangedHandler: doSomething});
</pre>
 
Whenever the state of the map changes, the doSomething function will be called. Hint: This feature is very handy when you only want to show markers currently in the user's viewport: whenever this handler is called, simply remove all the current markers, then grab a new set of markers to place on the map based on the current map bounds.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Triggering a Marker Click ===
This feature simulates clicking a certain marker. If the marker currently isn't in the map viewport, it will recenter the map to this coordinate. If you'd like, skip to the example.
 
<pre>
mapInstance.clickMarker(marker);
</pre>
 
Tips: This feature can come in handy if you are listing links somewhere else on the page, and want links to open up markers with more information.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Get Current Map Center / Map Bounds ===
These features will let you see where the map is currently centered and what the current bounds of the map are. If you'd like, skip to the example.
 
<pre>
var bounds = mapInstance.getViewportBounds();
var center = mapInstance.getMapCenter();
</pre>
 
The getCodeBounds function will return a Bounds object, which basically contains xMin, xMax, yMin, and yMax attributes of the current viewport. The getMapCenter function will return an XYPoint object representing the center of the map.
 
Tips: We can imagine this feature would be handy if you were only showing markers inside the current map viewport, or showing markers based on the proximity from the map center.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Using PNG Images and Shadows with Markers ===
You can also use PNG Images to make your icons even more pretty. If you'd like, skip to the example.
<pre>
// creates the icons
var forsale_sign = new Img("forsale.png",80,83, true); // note how the fourth parameter is set true!
var forsale_shadow = new Img("forsale-shadow.png",98,83, true);
var forsale_icon = new Icon(forsale_sign, forsale_shadow);
var all_images = [forsale_icon, forsale_icon, forsale_icon, forsale_icon, forsale_icon, forsale_icon];
 
// creates the marker
var marker = new Marker(all_images, new XYPoint(995,1004));
mapInstance.addMarker(marker);
</pre>
The above code is almost identical to example two, except that when we define an Img, we specify a fourth argument in the constructor, telling the class to create the image with an alpha channel (alpha channel basically means that fancy transparency you cant get with GIF's). Also, when we create the Icon, we also specify another Img as the second argument, which specifies a shadow. Thats pretty much all you have to do to get pretty PNG icons.
 
[[MapAPIExamples|Map API Example Source Code]]
 
----
 
 
=== Setting Marker and Window Options ===
There are a variety of window options you can set. Please refer to the API Classes and Methods page for a complete explanation.
 
 
 
== Accessing map images directly ==
You can also access the map images directly by reading them from the Amazon S3 servers. 
 
The file format:
 
http://map.secondlife.com.s3.amazonaws.com/Z/XXXXX/YYYYY/map-Z-X-Y-objects.jpg
 
Z = Zoom level desired. 1 is always the most zoomed in view, meaning individual region tiles. The current max/world zoom is 8.
 
X,Y = The X and Y coordinates on the SL Grid of the region. Ex: region Ahern = (997,1002).
 
The directory names are padded to 5 characters with leading zeros.
 
Tiles with zoom great than 1 are stored at the lower left corner coordinate of the tiles that are included in the image.
Inotherwards, you can find the zoom tile containing region /1/X/Y for zoom level Z at /Z/X - (X % Z)/Y - (Y % Z)
 
 
http://map.secondlife.com.s3.amazonaws.com/2/00498/00804/map-2-498-804-objects.jpg
 
Example: if zoom = 2, the 4 region tiles with filenames:
 
 
-http://map.secondlife.com.s3.amazonaws.com/1/01000/01000/map-1-1000-1000-objects.jpg-
 
-http://map.secondlife.com.s3.amazonaws.com/1/01001/01000/map-1-1001-1000-objects.jpg-
 
-http://map.secondlife.com.s3.amazonaws.com/1/01000/01001/map-1-1000-1001-objects.jpg-
 
-http://map.secondlife.com.s3.amazonaws.com/1/01001/01001/map-1-1001-1001-objects.jpg-
 
Are compressed into the single tile:
 
-http://map.secondlife.com.s3.amazonaws.com/2/01000/01000/map-2-1000-1000-objects.jpg-
 
Other Examples:
 
-http://map.secondlife.com.s3.amazonaws.com/8/01024/00896/map-8-1024-896-objects.jpg- Zoomed all the way out - tile from full world view
 
-http://map.secondlife.com.s3.amazonaws.com/1/01027/01019/map-1-1027-1019-objects.jpg- (A single tile contained in the view above, zoomed all the way in)
 
== Where do I go from here? ==
With this new api in hand, we build something really cool. We've tried to develop with the idea that everything we can do, you should be able to do as well.
 
While we've developed this API around features we think we would need, we do understand there is always room for improvement. So, if you encounter problems or bugs, have feature requests for new api methods, or have something really cool to show us, please email webmap@secondlife.com.
 
Happy coding from the Second Life Web team.
 
== Browser Compatibility ==
The map has been tested to work in Internet Explorer 6.0, Internet Explorer 7.0, Firefox 1.0 or greater and Safari 2.0. Other browsers may work but little issues may appear. Unless otherwise noted, all features work in all supported browsers.

Latest revision as of 13:27, 4 May 2011

NOTE: This is an official Second Life API provided and documented by Linden Lab. Its use is subject to the API Terms of Use.

Extend the reach of your Web site into Second Life using the Second Life Map API, which enables you to embed interactive Second Life maps directly into your web pages. These maps look and act much like Google Maps, except that, instead of the Earth, they display the topography of the Second Life virtual world. See http://maps.secondlife.com/ for an example.

When you use the Map API to embed Second Life maps on your site, your visitors can:

  • Click and drag the mouse pointer to pan the map view up, down, left, and right.
  • Double-click to zoom in by one level (power of two) and display the teleport window.
  • Click anywhere on the map to open a "teleport" window.
  • Use the mouse wheel or pan controls to zoom in and out.

For more information, see Map API Introduction.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Linden_Lab_Official:Map_API&oldid=1142362"