developer sign in
where » create » developer FAQ?

technical reference

reference tutorial examples technical FAQ geospatial API

resources

Developer contest WHERE GUI images

publishing info

publish to WHERE

Developer FAQ

Are cookies supported by the WHERE application? / What parameters are passed to my widget?

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 documentation 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');
Here is a sample widget that illustrates saving:
http://wherephone.com/samples/save.jin
(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 simply 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

This 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:

Label Latitude Longitude Color Color Code
A 42.370 -71.048 White w
B 42.356 -71.063 Black b
C 42.363 -71.066 Purple p
Green Point 42.360 -71.042 Green g
  42.356 -71.046 Red r


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
 These methods work at the List/Choice level, not the individual item level:
getFocus()
size()
isSelected(i)
setFocus(i)
setSelected(i)
(top)


Is there a recommended size for the image logo I should use at the top of my widget interface?/What pixel height/width would be reasonable given the range of screen-sizes among phones?

The icons on the WHERE home page are 22x22 pixels and the function buttons are 22 pixels high. To match the footer height a header should be 22 pixels high. WHERE currently runs on two different screen width phone 176 wide and 240 wide, so if you want you widget to look good on both size phones any splash screen should be centered and no wider than 176 pixels. (top)


How do you view the emulator debug window?

If it is displayed, 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 here on a PC:
C:\Java\jre1.5.0_10\bin
Click on the Advanced tab, expand "Java console" option and then click on "Show console" (top)


How do I publish my widget on WHERE?

More information can be found here. (top)




terms of use | privacy policy | about | FAQ | blog | jobs | contact us
For 24/7 support email support@where.com or call 888-262-1150
WHERE™ is a product from uLocate Communications, Inc. ©2007 All Rights Reserved.