I'm a huge Blackberry fan. I have had a Blackberry for close to 6 years now and have never looked back. They do what they are designed to do (email and phone), no questions asked. I've used windows mobile phones and have a few friends that have them and it seams like they are always having issues. The iPhone is definitely a strong competitor but without a real keyboard and push email its not an option for me. There is one huge are area that Blackberrys and RIM (Research In Motion) is lacking in and that's developer support. While there are many things to complain about the issue that pains me the most as a web developer is the Blackberry Browser.
The iPhone browser rocks. The Blackberry Browser doesn't. Its like developing for IE 4.0. There is limited xhtml and css support and if you follow the documentation its possible to create a functional website that looks decent on the device. There is very little javascript support, but it does have support to get GPS coordinates from a device with builtin GPS, like the Blackberry 8800, 8820, and 8310, which could be used to create some very cool location based websites. Unfortunately the documentation is completely wrong. The information in the content developer guide is just plain wrong and sample code on the blackberry developer website isn't even valid javascript.
Here is what I have found to be a more accurate description of the blackberry.location javascript API in the blackberry browser based on my testing using a Blackberry 8800 running v4.1.1.90:
blackberry.location.latitude & blackberry.location.longitude:
The current latitude and longitude of the device. The first time you access either of these properties the user is prompted if they would like to let the website access location information. There is currently no setting on the device or on the enterprise server to disable this prompt or whitelist specific sites. If the user selects "No" then "0" will be returned for the latitude & longitude.
blackberry.location.setAidMode(aidMode):
This method sets the GPS aid mode to be used. 0 - Cell Site, 1 - Assisted, 2 - Autonomous. The documentation is mostly correct on this method. "Autonomous" is the most accurate and most supported but also the slowest. The other two methods require carrier support and my carrier doesn't support it so I couldn't test them.
blackberry.location.refreshLocation():
This method request and update of the location from the device. This method is non-blocking so if you try to read the laitude/longitude right after calling this method you may or may not get the newest information. This method returns true on success. If you have set an invalid AidMode (0 or 1 and the carrier doesn't support that feature) this method will return false and the callback method will never be called.
blackberry.location.onLocationUpdate(callbackJS)
This method is the worst a far as incorrect documentation goes. This method sets a callback function that is called after you call refreshLocation() and the device actually has the new location data. However in my testing it appears that this does not get called once per refreshLocation() call. After you call refreshLocation() the callback function is invoked continuously when the location changes (about every 10-15 seconds in my testing). Another very important note is that you have to pass this method a string that gets evail-ed (like you can do with setTimeout).
Here is a sample that puts all of the pieces together. It simply shows a javascript alert with the latitude and longitude when the location is updated:
1: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Mobile 1.0//EN" "http://www.wapforum.org/DTD/xhtml-mobile10.dtd">
2: <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3: <head>
4: <title>GPS Testing</title>
5: <script "text/javascript">
6:
7: // called when location object changes
8: function locationCB()
9: {
10: alert("Latitude " +
11: blackberry.location.latitude);
12: alert("Longitude " +
13: blackberry.location.longitude);
14: return true;
15: }
16:
17: // test to see if the blackberry location API is supported
18: if( window.blackberry && blackberry.location.GPSSupported) {
19: document.write("GPS Supported");
20:
21:
22: // Set our call back function
23:
24: //WRONG: this would call our call back function immediatly, not after the refresh
25: //blackberry.location.onLocationUpdate(locationCB());
26:
27: //WRONG: the blackberry browser won't support passing a method.
28: //It will error on refresh and all javascript processing on the page will stop
29: //blackberry.location.onLocationUpdate(locationCB());
30:
31:
32: // RIGHT: pass a string that calls our method
33: blackberry.location.onLocationUpdate("locationCB()");
34:
35: // set to Autonomous mode
36: blackberry.location.setAidMode(2);
37:
38: //refresh the location
39: blackberry.location.refreshLocation();
40: }
41: else
42: {
43: document.write("This Device doesn't support the Blackberry Location API");
44: }
45: </script>
46:
47: </head>
48: <body>
49: </body>
50: </html>
Hopefully someday we will get a more feature rich, fully documented, Blackberry browser with DOM and AJAX support (Firefox mobile anyone?). Until then hopefully I have saved someone days of debugging incorrectly documented features.