Developer Program Technical FAQ
- Are cookies supported by the WHERE application?
- What parameters are passed to my widget?
- What information is sent in the User Agent when a device sends a request to my server?
- Is there a way to store data on the phone so that it is available the next time a user clicks on my widget?
- How do I get my widget to display correctly on BlackBerry devices?
- Are there any design standards to follow when designing my widget?
- Where do I put my <form> tags so that the input fields are displayed and the parameters are submitted?
- In your WHERE local app you have: call, get directions, view on map, etc. - basically almost all the same items I would need for my widget - is there a way I can just pass you a latitude and longitude or do I need to re-create all that functionality?
- I have a database of locations but they are street addresses, how can I convert them to latitudes and longitudes?
- Can input fields within a choice type="check" have ids?
- How do I determine which input of a choice list is checked?/Can I query the "checked" attribute of a choice item?
- Is there a recommended size for the image logo I should use at the top of my widget interface?
- What file type should my images be?
- What is the best way to write my footer code so it displays correctly on all phones?
- What are my options for viewing/testing my WHERE widget as I develop it?
- How do I publish my widget on WHERE?
Are cookies supported by the WHERE application?
Yes, cookies are fully supported. (top)
What parameters are passed to my widget?
Latitude (lat), Longitude (lng), WHERE registed device id (deviceid), and others are passed with every request from the phone to your widget in addition to any parameters you choose to pass along. The info is sent along with host name and any cookies that your server has set. lat and lng will always contain valid values. If the phone has not determined it's GPS location when a user clicks on your widget, a pop-up screen will be displayed where the user must enter a valid address. See the JIN reference for a list of global variables made available in the request object.
(top)
What information is sent in the User Agent when a device sends a request to my server?
A customized User Agent is passed in when a device sends a request to a server using WHERE.
To see how it's constructed and what information it contains view the User Agent information page.
(top)
Is there a way to store data on the phone so that it is available the next time a user clicks on my widget?
Yes, the record store is available with the save() and load() commands. For example, to save a users name you would issue this command in a script:
save('username', 'john');
To access the name on the next run:
var name = load('username');
(top)
How do I get my widget to display correctly on BlackBerry devices?
You'll need to make some quick changes to your widget's navigation to have it display correctly on BlackBerry. Learn more.
(top)
Are there any design standards to follow when designing my widget?
There are some optional design guidelines that we have layed out on the Examples page to help you design a logical interface that's consistent with our other widgets.
(top)
Where do I put my <form> tags so that the input fields are displayed and the parameters are submitted?
This is where Jin and HTML differ. <form> tags must be outside the <body> tags of a page. To submit user input with a form, you must use scripting to set the forms parameters. Below is a simple example that shows how to do this:
<jin>
<script>
function submitForm(){
document.myForm.myParameter.value = document.userInput.value;
document.myForm.submit();
}
</script>
<form id="myForm" action="http://www.where.com/jin/myForm.jin" method="GET" accept-encoding="GZIP">
<input type="hidden" id="myParameter" value=""/>
</form>
<body>
<pr>
<input id="userInput" type="text" value="user entry"/>
</pr>
<pr>
<input type="button" bgfocus="0xFF0000" value="Submit Form" onSelect="submitForm()"/>
</pr>
</body>
</jin>
When the user clicks on the "Submit Form" button, the submitForm() function is executed. The function first sets the "myForm" parameter "myParameter" with this line:
document.myForm.myParameter.value = document.userInput.value;
the function then submits the form:
document.myForm.submit();
Other than the above differences the behavior of JIN and HTML forms are quite similar.
(top)
In your WHERE local app you have: call, get directions, view on map, etc. - basically almost all the same items I would need for my widget - is there a way I can just pass you a latitude and longitude or do I need to re-create all that functionality?
Yes, you can simplya pass a latitude and longitude to our map and directions widget. Below is a form that will return a Jin page displaying a map:
<form id="mapForm" action="http://widget.ulocate.com/jin/map.jin" method="GET">
<input type="hidden" id="lat" value=""/>
<input type="hidden" id="lng" value=""/>
<input type="hidden" id="name" value=""/>
<input type="hidden" id="width" value=""/>
<input type="hidden" id="height" value=""/>
<input type="hidden" id="marker" value="1"/>
</form>
lat and lng are decimal degrees, name is the label on the center marker (red star) in the center of the map, and width and height are desired map size in pixels.
"marker" parameter defines if a center marker should be draw. Default is to draw the marker and if marker is not passed, the marker is drawn.
- Do not draw marker: <input type="hidden" id="marker" value="0"/>
- Draw marker: <input type="hidden" id="marker" value="1"/>
You can specify zoom levels using the "zoom" parameter. Possible values are 0-13 (default is 3). Scale values are:
0 > 6000
1 > 12000
2 > 24000
3 > 48000
4 > 96000
5 > 192000
6 > 400000
7 > 1600000
8 > 3000000
9 > 6000000
10 > 12000000
11 > 24000000
12 > 48000000
13 > 96000000
Here is a form you can submit that will return directions from one lat,lng to another:
<form id="dirsForm" action="http://widget.ulocate.com/jin/getdirection.jin" method="GET">
<input type="hidden" id="olat" value=""/>
<input type="hidden" id="olng" value=""/>
<input type="hidden" id="dlat" value=""/>
<input type="hidden" id="dlng" value=""/>
<input type="hidden" id="width" value=""/>
<input type="hidden" id="height" value=""/>
<input type="hidden" id="back" value="1"/>
<input type="hidden" id="pedestrian" value="false"/>
</form>
olat, olng are the starting point lat,lng. dlat, dlng are the destination lat, lng. width and height are the phone's screen size and are available with screenWidth() and screenHeight() Script functions. back is the number of screens to skip back with the direction page's "Back" button. pedestrian indicates whether or not to use walking directions (ignores one way streets).
(top)
When I use the map widget it draws the center point - can I plot additional points?
Yes, you can pass a list of points as a parameter to the map widget:
<form id="mapForm" action="http://widget.ulocate.com/jin/map.jin" method="GET">
<input type="hidden" id="lat" value=""/>
<input type="hidden" id="lng" value=""/>
<input type="hidden" id="name" value=""/>
<input type="hidden" id="width" value=""/>
<input type="hidden" id="height" value=""/>
<input type="hidden" id="points" value="A,42.370,-71.048,w,B,42.356,-71.063,b,C,42.363,-71.066,p,Green Point,42.360,-71.042,g,,42.356,-71.046,r"/>
</form>
The "points" parameter is a list of comma separated values and must be in this order: label, Latitude, Longitude, color.
You can omit a value for label but you must not omit the comma that separates the label value from the latitude value: ",,42.00,-71.00,b".
When adding points using the "points" parameter, the map automatically zooms to fit all the points (including center marker).
The above will draw five extra points on the map:
|
|
I have a database of locations but they are street addresses, how can I convert them to latitudes and longitudes?
Converting addresses to latitude and longitude is called geocoding. a service that is free for non-commercial use is available here: http://geocoder.us/
For commercial use they only charge 1/4 of a penny per address.
(top)
Can input fields within a choice type="check" have ids?
for example:
<choice type="checkList" id="items"..>
<input type="choice" id="choice1"..>
</choice>
Yes, input fields inside choices can have ID's. In fact any element inside the <jin> tag can have an ID.
You can access the elements as:
document.getNodeById('choice1');
or
document.items.choice1;
document.getNodeById() is a less efficient method of retrieving a node in the document, but at times can
make for far less scripting in a page. This is due to the representation of the id as a string. For example ...
for (var i = 0; i < 10; i++) {
var choice = document.getNodeById('choiceItem'+i);
// do something with the choice item
}
Using document.getNodeById(), you must beware that you don't have two nodes with the same id. document.getNodeById() will always retrieve the first node with matching id in the DOM.
document.items.choice1 is a far more efficient method of identifying a node because it traverses directly to the node.
(top)
How do I determine which input of a choice list is checked? / Can I query the "checked" attribute of a choice item?
If you want to access the "checked" attribute of individual ListItems / ChoiceItems, then the attribute must be predefined, and the ChoiceGroup will manage setting the attribute value. A faster method is to use a script to check each input:
<script>
function changeIt() {
var list = document.checkList;
var index = 0;
for (var i = 1; i < list.size(); i++) {
if (list.isSelected(i) == true) { index = i; i = list.size(); }
}
// now you have the selected index, you could index into
// the list to get value via list.nodeAt(index) for example
}
</script>
<body>
<choice type="checkList" id="items">
<input type="choice" id="choice1">option 1</choice>
<input type="choice" id="choice2">option 2</choice>
</choice>
</body>
The following methods work at the List/Choice level, not the individual item level:
getFocus()
(top)
size()
isSelected(i)
setFocus(i)
setSelected(i)
Is there a recommended size for the image logo I should use at the top of my widget interface?
WHERE currently runs on different screen widths ranging from 176px to 320px wide, so if you want you widget to look good on all phones any splash screen should be centered and no wider than 176 pixels. The other option is to have different images for different sized screens and display them dynamically based on screen width (see Global Variables).
(top)
What file type should my images be?
For the best compatibility on all phones, we use .png images exclusively and recommend developers do the same.
(top)
What is the best way to write my footer code so it displays correctly on all phones?
There are two ways to do this:
- Have footer images for each screen size which are set based on the widget of the screen. You can acquire this width from the GET parameter 'screenwidth' (see Global Variables for a list of these paramaters made available by WHERE). Directories with images for each screen size can be found here (the folders named 176, 240, etc. correspond to 176px, 240px, etc.). Look here to see some example code for this.
- Use our automatically-sized images. You can find these on our WHERE GUI images page. If you use these links for your images, all the work is done for you; when a request for one of these is sent from a phone, the correct-sized image will be returned (based on the User Agent). This method may not produce correct results in the emulator, however it is simple to implement and works well.
What are my options for viewing/testing my WHERE widget as I develop it?
Since WHERE is a mobile application, there is no way to view your WHERE application in a web browser. For this reason, we provide two ways to view your WHERE application during development: handset testing and emulator testing.
Phone Emulator Testing:
Any registered WHERE developer can use the WHERE phone emulator to view their application. This emulator runs as a Java applet and works on most PCs and Macs. If you have any troubles getting the emulator working on your computer, take a look below. You can also contact us at create@where.com.
The easiest way to get started developing with WHERE is with our online emulator.
The emulator that most developers will use is the online Samsung A900 emulator accessible from the developer dashboard.
More specifically, the two online device emulators available are the Samsung A900 with screen width of 240px and the Samsung A960, with screen width of 176px:
Samsung A900: http://webstart.mpowerplayer.com/developer.where.com/create/emulator/240.jad?skin=where
Samsung A960: http://webstart.mpowerplayer.com/developer.where.com/create/emulator/176.jad?skin=where
The emulator uses Java Web Start, and should come up shortly as long as your Java runtime environment is properly installed. Subsequent starts of the emulator will be much faster. If the emulator does not appear, most likely there is a problem with your Java runtime environment. You can find out more about Java Web Start here.
After the emulator starts, the Java console should appear. The Java console provides all the information available to help debug your widget. If the Java console does not appear, right click on the Java coffee cup icon in the system tray. If there is no coffee cup icon you need to run javacpl.exe which is most likely located here or a similar path:
C:\Program Files\Java\jre1.5.0_10\bin
Once the Java console has opened, click on the "Advanced" tab, expand the "Java console" option and then click on "Show console". Exit mpowerplayer completely and restart. There may be a mpowerplayer icon in the system tray. Make sure you exit that as well.
When your site is setup to run JIN pages, simply point the emulator to your start page. Thats it ! You're ready to develop a GPS capable mobile application.
Sprint SDK:
The Sprint SDK is another emulator option which provides a choice of 240px and 176px width devices.
Download the 240px and 176px ZIPs:
240px width: http://developer.where.com/create/emulator/240.zip
176px width: http://developer.where.com/create/emulator/176.zip
Open the ZIP and take a look at "readme.txt" for instructions on setting up your project. It's very straighforward.
Nokia SDK:
The Nokia SDK is another emulator option.
Download the 240px ZIP:
Nokia N95: http://developer.where.com/create/emulator/app-prod-where-N95EMU.zip
Handset Testing:
If you have a supported handset that runs the WHERE application, you can test directly on your phone. Visit where.com to see if WHERE runs on your phone. If you have a supported phone and don't wish to pay the monthly subscription for WHERE, please contact us at create@where.com and we can provide you with a free version for development purposes.
The process for provisioning a widget to a handset is as follows:
- Go to http://www.where.com/ and sign in to your consumer account (the one associated with your phone).
- Click on the "developers" menu item or visit http://developer.where.com/ to navigate to the developer account login screen and sign in.
- Navigate to the "dashboard" where your custom widgets are displayed.
- Under the particular widget, click the arrow to expand "Details" and click the link to "provision" your widget to a consumer handset. This should redirect you to your consumer account where you should see your phone, now with the new widget added.
(top)
How do I publish my widget on WHERE?
More information can be found at our program overview and also on the publishing info page.
(top)
