Linden Lab Official:Map API Advanced Examples
We've made improvements and changes to the webmap, effective January 15, 2009.
Some information here may be out of date as we update this wiki with the changes. Thanks for your patience.
Linking to a Second Life coordinate using x and y coordinates (NEW)
We've created an easy function to teleport users to an absolute coordinate, for example 1000.5, 1000.5. If you'd like, skip to the example.
gotoSLURL(997,1002);
The above code will open up the Second Life client and then teleport the user to (997,1002) (where the welcome area fountain is).
Working with maps
Customizing zoom and pan controls
It's easy to remove all the zoom and pan controls or create your own. When you create the SLMap object, simply secify false for the SLMapOptions properties hasZoomControls and hasPanningControls, for example:
mapInstance = new SLMap(document.getElementById('map-container'),
{hasZoomControls: false,
hasPanningControls: false});
The above code sets the map options hasZoomControls and hasPanControls to false.
To create your own zoom and pan controls use the SLMap methods setCurrentZoomLevel(), getCurrentZoomLevel(), zoomIn(), zoomOut, panLeft, panRight, panUp and panDown to skin your maps.
In the following example there are anchored links for each function, which will call a function when it is clicked.
Customised zoom and pan controls
<!-- Common header -->
<script>
var mapInstance;
function loadmap() {
// creates the map
mapInstance = new SLMap(document.getElementById('map-container'),
{hasZoomControls: false, hasPanningControls: false});
// mapInstance = new SLMap(document.getElementById('map-container'),
{disableVoiceInfo: true});
mapInstance.centerAndZoomAtSLCoord(new XYPoint(997,1002),2);
(document.getElementById('zoom_level')).innerHTML = mapInstance.getCurrentZoomLevel();
}
function setZoom(level) {
mapInstance.setCurrentZoomLevel(level);
(document.getElementById('zoom_level')).innerHTML = mapInstance.getCurrentZoomLevel();
}
function zoomIn() {
mapInstance.zoomIn();
(document.getElementById('zoom_level')).innerHTML = mapInstance.getCurrentZoomLevel();
}
function zoomOut() {
mapInstance.zoomOut();
(document.getElementById('zoom_level')).innerHTML = mapInstance.getCurrentZoomLevel();
}
</script>
</head>
<body onload="loadmap()">
<p>This map has the usual pan/zoom controls disabled, and the hyperlinks
below implement custom pan/zoom controls via SLMap Javascript calls.
<h2>Set the zoom level</h2>
<h3>The Current Zoom Level is <span style='color:red' id='zoom_level'></span></h3>
<a href="javascript: setZoom(1);">1</a>
<a href="javascript: setZoom(2);">2</a>
<a href="javascript: setZoom(3);">3</a>
<a href="javascript: setZoom(4);">4</a>
<a href="javascript: setZoom(5);">5</a>
<a href="javascript: setZoom(6);">6</a>
<a href="javascript: zoomIn();">zoom in</a>
<a href="javascript: zoomOut();">zoom out</a>
<h2>Pan Around</h2>
<a href="javascript: mapInstance.panLeft();">left</a>
<a href="javascript: mapInstance.panRight();">right</a>
<a href="javascript: mapInstance.panUp();">up</a>
<a href="javascript: mapInstance.panDown();">down</a>
<br><br>
<div id="map-container"></div>
</body>
Disabling and enabling dragging
Say you'd like to disable dragging on the map. No problem. If you'd like, skip to the example.
mapInstance.disableDragging();
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.
Panning or re-centering 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.
mapInstance.panOrRecenterToSLCoord(new XYPoint(1000,1000), true);
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.
Setting a onStateChangedHandler event 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.
mapInstance = new SLMap(document.getElementById('map-container'), {onStateChangedHandler: doSomething});
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.
Getting current map center and 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.
var bounds = mapInstance.getViewportBounds(); var center = mapInstance.getMapCenter();
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.
Working with markers
There are a variety of window options you can set. Please refer to the API Classes and Methods page for a complete explanation.
Setting a marker's event handlers
The following two features enable you great flexibility in customizing the behavior of maps.
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.
// 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});
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.
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.
// 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);
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
Removing a marker
Markers can be removed by passing the original marker to the removeMarker function. If you'd like, skip to the example.
mapInstance.removeMarker(marker);
The above code simply removes the marker, where marker is a reference to the original marker.
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.
mapInstance.clickMarker(marker);
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.
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.
// 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);
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.
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.
SLPoint('ahern',128,128); // use this instead of XYPoint(997,1002)
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:
SLPoint("da boom") // OR
SLPoint("dA bOOm")