Tutorial: Geolocation

In this tutorial, we go beyond Hello World and create an application that users can interact with. Our app displays an image and a button. When a user clicks the button, the app retrieves GPS coordinates and displays the coordinates on the screen along with some other location-related information.

You will learn to:

  • Create a basic web application that uses JavaScript, HTML5, and CSS
  • Create a button that triggers an event
  • Retrieve and display the GPS coordinates for the user's location
  • Run and test the application on the Ripple emulator
  • Create a BlackBerry WebWorks config.xml file
  • Package the application using the Ripple emulator
  • Install and test the application on a BlackBerry device simulator

Before you begin

Make sure you have the necessary tools installed. Refer to Setting up your tools, if necessary.

Set up folders and files

For this tutorial, we provide most of the files, and we review in detail the ones that you create.

You need to create your application files where the Ripple emulator can find them.

  1. Navigate to your RippleSites folder. As a reminder, you created it in one of the following locations when you set up your tools:
    • Windows XP: C:\Documents and Settings\<Username>\RippleSites
    • Windows 7: C:\Users\<Username>\RippleSites
    • Mac OS: /Users/<Username>/RippleSites
  2. In the RippleSites folder, create a folder named HelloGeo.
  3. Download the HelloGeo_BB10.zip file to your computer.
  4. Extract the contents of the .zip file into the HelloGeo folder. Confirm that you have the following:
    • a folder named images that contains two image files, hellogeo.png and icon.png
    • a styles.css file
    • a geo.js file

Create the layout

In addition to the files we provide, you need an HTML file to hold the basic layout of your app. Using a text editor, create a file named index.html in the HelloGeo folder. Copy and paste the following code into the file:

<!DOCTYPE html>
<html>
<head>
    <title>HelloGeo</title>
    <meta id="viewport" name="viewport" content="user-scalable=no,
        width=device-width" />
    <link href="styles.css" rel="stylesheet" type="text/css" />
</head>
 
<body>
    <div id="container">
        <div id="world">
            <img src="images/hellogeo.png" width="500" height="500" alt="world" />
        </div>    
        <div id="button">
            <h2>Hello world. Where am I?</h2>
			<button type="button" id="btnGPSDefault">Get my coordinates</button>
        </div>
    </div>

</body>
</html>

Let's review this code.

The !DOCTYPE line identifies this file as an HTML5 file.

<!DOCTYPE html>

This line indicates the title of the app.

<title>HelloGeo</title>

The viewport metadata controls the behavior and initial appearance of the webpage when it is displayed in the browser window. Set user-scalable to no to prevent the user from changing the zoom level. Set width to device-width to force the browser window to match the width of the device.

<meta id="viewport" name="viewport" content="user-scalable=no, width=device-width" />

This line identifies the CSS style sheet associated with our app. Feel free to play around with the properties in the styles.css file.

<link href="styles.css" rel="stylesheet" type="text/css" />

Between the <body> tags, we define containers for the different sections of the screen.

The container div represents the whole screen. If you peek in the styles.css file, you see that the style rule for the container id sets the width and height to correspond to the device screen size. If necessary, you can adjust these values.

<div id="container">

The world div corresponds to where we display the image of the world.

<div id="world">
    <img src="images/hellogeo.png" width="500" height="500" alt="world" />
</div>

Finally, the button div defines the button area. This code creates a button that the user can click. The button isn't complete yet, since we need to associate an action with it. For now, we can check that the button appears on the screen where we expect it.

<div id="button">
    <h2>Hello world, where am I?</h2>
    <button type="button" id="btnGPSDefault">Get my coordinates</button>
</div>

Test your layout in a browser

We can test the basic layout of our app just by using an HTML5-compliant browser. Clicking the button does not have an effect because we haven't associated any JavaScript with it, but we can verify the layout.

  1. Go to the location of the index.html file that you created.
  2. Open the file in your browser. Here is what you should see:
This illustration shows the BlackBerry 10 version of the HelloGeo app as displayed in a browser.

Last modified: 2014-03-10

comments powered by Disqus