User:SignpostMarv Martin/Webmap API Examples

From Second Life Wiki
Jump to navigation Jump to search

This article covers the refactored javascript for the SLURL Map API made by SignpostMarv Martin for Open Hack 2009.

Summary of modifications

  • All functions were moved into a SLURL object, e.g. SLMap becomes SLURL.map
  • Some functions became pluggable
  • Some functions were improved for ease of use

Base HTML

Live Example: http://dev.signpostmarv.name/pub/secondlife/slurl.html

<html4strict><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Hack Day '09: Pluggable SLurl!</title> <meta http-equiv="Content-Type" content="application/xhtml+xml;charset=UTF-8" /> <script src="http://maps.google.com/maps?file=api&v=2&key=[YOUR GOOGLE MAP API KEY HERE]" type="text/javascript"></script> <script src="http://www.google.com/jsapi?key=[YOUR GOOGLE SEARCH API KEY HERE]" type="text/javascript"></script> <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js" type="text/javascript"></script> <script src="http://static.marvulous.co.uk/%C2%B5/js/slurl/mapapi.js" type="text/javascript"></script>

<link rel="stylesheet" type="text/css" href="http://slurl.com/_styles/MAIN.css" /> <script type="text/javascript"> /*<![CDATA[*/ $(document).ready(function() { mapInstance = new SLURL.map(document.getElementById('map-container')); mapInstance.gotoRegion('Hippotropolis'); }); $(document).unload(function() { // Google script that helps prevent memory leaks // (we're looking at you when we say that IE!) GUnload(); /*]]>*/ }); </script> </head> <body>

</body> </html></html4strict>

Adding a Plugin

The key feature of the refactoring (aside from shifting everything into a SLURL object) was to make the SLURL JS "pluggable"- making it easier to extend a SLURL map without needing to create & edit a duplicate of the javascript (which would become difficult to maintain over time the more customisations were made).

Currently, two functions can have callbacks registered with them:

  1. gotoRegion
  2. gotoSLURL

The internals of a plugin can be coded however you want them to, but the callback function for the plugin must be structured along these lines:

gotoSLURL,gotoRegion

<javascript>function my_callBack(slRegionName,x,y) { // do stuff here }</javascript>


Registering a callback

Callback functions are registered to a particular instance of a SLURL map, enabling multiple maps to be used on the same page with different plugins.

For example, to enable Marv's Flickr plugin, the following modifications are made to the base HTML;

1) The Flickr plugin is added below mapapi.js: <html4strict><script src="http://static.marvulous.co.uk/%C2%B5/js/slurl/plugins/flickr.js" type="text/javascript"></script></html4strict> 2) Some extra CSS is added below MAIN.css: <html4strict><link rel="stylesheet" type="text/css" href="http://dev.signpostmarv.name/pub/secondlife/slurl-hacks.css" /></html4strict> 3) The Flickr plugin is configured: <javascript>SLURL_flickr.apiKey = whatever_your_api_key_is; SLURL_flickr.groupId = '51035802764@N01'; // Second Life flickr group ID- the same one linked from the official blog. change to suit. SLURL_flickr.searchMode = 'group'; // the plugin defaults to 'global'- e.g. searching all flickr photos. SLURL_flickr.resultsPerPage = 32; // the number of thumbnails to display SLURL_flickr.prependResultsHTML = ; // Useful for adding a header in before the results.</javascript> 4) The callbacks are registered after the mapInstance has been declared: <javascript> SLURL.addCallBack.gotoSLURL(mapInstance,SLURL_flickr.searchRegion); SLURL.addCallBack.gotoRegion(mapInstance,SLURL_flickr.searchRegion);</javascript>

5) Finally, some extra HTML for containing the flickr results is added to the body:<html4strict>

</html4strict>

Ease-of-use Improvements

Adding a Marker

Key Namespace Alterations

  1. SLURL.map.addMarker (previously SLMap.addMarker)
  2. SLURL.Img (previously Img)
  3. SLURL.Icon (previously Icon)
  4. SLURL.Marker (previously Marker)
  5. SLURL.XYPoint (previously XYPoint)

SLURL.map.addMarker has been altered for ease of use- the previous syntax for adding a single image as a marker required superfluous variables: <javascript> 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
 marker = new Marker(all_images, new XYPoint(997,1002));
 mapInstance.addMarker(marker);</javascript>

The function has been modified in two ways:

  1. A single string can be passed instead of an array
  2. Arrays with fewer than 6 items have the first item padded

These two minor alterations simplify things, making the previous example: <javascript> var yellow_dot_image = new SLURL.Img("b_map_yellow.gif",9,9);

 var yellow_icon = new SLURL.Icon(yellow_dot_image);
 marker = new Marker(yellow_icon,new SLURL.XYPoint(997,1002));
 mapInstance.addMarker(marker);</javascript>