Building a Enabled PhoneGap App - Part 4

This post is more than 2 years old.

Welcome to the fourth part of my blog series on building a enabled PhoneGap application. If you haven't yet read the earlier entries in this series, please see the links at the bottom for background and the story so far. In today's entry we're going to add geolocation to the application. This will be supported both in the tip reporting mechanism as well as in the page that fetches tips.

Luckily, makes building location-aware applications very easy. In fact the code for these features are so simple you can add them within five minutes. Unfortunately, what isn't so easy is deciding how to use these features. I'm finding that more and more it isn't so much a problem of "How do I do X" but more "How do I X in a way that best works for my users." Consider the simple fact that geolocation can - and does - fail. What do I do? Do I let users enter an address? Do I display a small map so they can touch to select their location? What if they lie? Or what if they are just wrong?

At the end of the day - I don't think I'm a UX (User Experience) expert. Like most folks I recognize good UX versus bad UX, but it is much harder to decide what the best choice is when building your own apps. Hopefully a year or two from now I can say, confidently, that I'm making the right decisions. For now though I'm going to struggle through it (and - of course - share these struggles with you guys).

For now I've decided to make geolocation required. For adding a tip you will be prevented from saving the data if the geolocation check fails. For displaying tips, if we can't get your location, we don't bother getting any of the stored data.

Let's begin by looking at the changes to the tip form page. The first thing I did was add "disabled" as an attribute to the submit button. This means the page loads with the form immediately disabled. Next, I wrote the following snippet that will execute when the Add page loads.

currentLocation is defined in the root of my JavaScript file so it is a global variable. If everything works well, then we simply enable the form button. Otherwise, the user gets an error.

Once we have the user's location, how do we store it? supports what are known as GeoPoints. Any data type can support a geopoint, but only one geopoint. A geopoint is simply a longitude/latitude data pair. Using it is quite simple though. Consider this code taken from the form submission handler.

Compared to our previous example, there are only two changes. First, I make an actual Geopoint with my location data. Then I simply add this value to the tip object. Remember that I said that we can - if we want - change the structure of our data at any time. After the application is released this is probably a bad idea (and I'll talk about how you can avoid that in the next entry), but for now it is pretty helpful.

That's it for the storage aspect. Any records created with this geopoint can now be searched in new and interesting ways. If you remember, our previous code for the "get" page grabbed everything from the database. This was as simple as creating a query and just running find on it. I wish it were more complex.

Here is where the beauty of's Query system comes to play. If we want to filter the results, we can simply add more options to the object. For example, assuming I have your location, it takes one line to find data near you:

query.near("location", myLocation);

Seriously - that's it. In my tests this seemed to be within 50 miles or so. Oddly the docs for "near" do not specify exactly what near is. Near like the Sun? Near like Starbucks? I'm just not sure. However, they do provide a few alternatives. These are much more complex though. Instead of typing near, I have to type "withinMiles":

query.withinMiles("location", myLocation, 30);

Yes - I'm being a bit of an ass - but I can't stress enough how darn cool this is. (In case you don't live in a proper country with Imperial units, they also support withinKilometers.) I decided that for my application I wanted to return tips within 30 miles and reports that were no older than 7 days. Adding the date filter was three lines of code that I could have written as one:

var lastWeek = new Date();
query.greaterThan("createdAt", lastWeek);

Here's the entire logic for retrieving data on the Get page.

You may notice that I've moved the render portion into its own function. For the mapping portion of this application I decided to try the free mapping service Leaflet. Leaflet is not only free, but really easy to use too. Here's the function I use to render out to the map:

Even if you've never seen Leaflet before, you can probably read that easily enough and see what it is doing. For each result I add a marker along with a little info window you can click to get the details. You can see an example of this below:

All in all - I've now got a complete, if basic, application. Don't forget you can see the complete source code for the application at the GitHub Repo and you can download builds of the application on the public PhoneGap Build site.

In the next, and final, part to this series, I'm going to discuss what can, and should, be done both on the PhoneGap side as well as the side.

Raymond Camden's Picture

About Raymond Camden

Raymond is a senior developer evangelist for Adobe. He focuses on document services, JavaScript, and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support. You can even buy me a coffee!

Lafayette, LA

Archived Comments

Comment 1 by Sean posted on 10/7/2012 at 3:22 AM

looking forward to the next post in the series!!

Comment 2 by Raymond Camden posted on 10/7/2012 at 3:35 AM

Thanks. I'm a bit disappointed by the amount of comments on this series - but - heck - its been fun to write. ;)

Comment 3 by sam posted on 10/9/2012 at 3:49 AM

this series is awesome and really helping me to get started with parse.. I was initially a bit scared of parse, because not familar with backbone, but your example shows a simple enough example to get me started.. what about notification services.. that would be cool to see you hooking into..

Comment 4 by Raymond Camden posted on 10/9/2012 at 5:27 AM

I really do want to do notifications - I'm just not sure how I'll get it into the app. The obvious way would be for the user to say, "Yes, I want notifications", and they get a notice when some reports a tip. Which... kinda makes sense. I'll try to do that this week.

Really happy you're liking it Sam!

Comment 5 by Pete posted on 10/9/2012 at 11:50 AM

It's a good series Ray, probably one of the most useful things I've read recently. It's a great tutorial, but I suppose was waiting for the final post before posting a comment!

Are you going to go through and do app store submissions?

Comment 6 by Raymond Camden posted on 10/9/2012 at 4:00 PM

Pete: I was considering it. Honestly, I don't know if Apple will accept it. Also, as much as I want this to be a "real" app, at the end of the day, the main point is to educate. So for example, notifications I think would be incredible. I may add them in a silly way just to get to a point where I can demo it. I'd rather do that even if it means i can't really release it as an app. Does that make sense?

Anyway - right now my thoughts are:

1) Ignore my last comment above and do Notifications
2) Then do the final entry talking about 'final' stuff for PG and Parse.

I kinda wanted to do Facebook connect as well, but I may just do that in a post by itself.

Comment 7 by Pete posted on 10/9/2012 at 4:05 PM

It doesn't matter if they reject it, it'd be a good end to the guide to show people how to submit. Getting the right sized screen shots etc, the difference between Google and Apple.

And Facebook connect would be good to see, I'm struggling with that in a PG app at the moment.

Comment 8 by Raymond Camden posted on 10/9/2012 at 4:06 PM

My problem with that though is that the submission process is pretty big, and I'd say a bit OT for the main thrust of this series. Plus, there are guides already out on this.

But - I could look into it - and possibly even recommend good guides for this.

Let me consider it for a post series followup. :)

Comment 9 by Raymond Camden posted on 10/10/2012 at 5:11 AM

I looked into Notifications today and wow - it was a bit more difficult than I thought. I'm going to blog it tomorrow, but as a separate blog entry, not part of this series. That distinction probably isn't that important. ;)

Comment 10 by Greg posted on 10/16/2012 at 12:29 AM

Thanks for the tutorials - trying to figure out what BaaS to use and this is helping push me towards parse. Any suggestions on how to set up offline use and being able to store data offline and check for updated content?

Comment 11 by Raymond Camden posted on 10/16/2012 at 12:39 AM

Is this what you mean?

Comment 12 by Greg posted on 10/16/2012 at 12:43 AM

Thanks - Just came across that as well. It is a close, but I would like to keep the full set of data on the device and only retrieve the content if it has been changed.

Comment 13 by Raymond Camden posted on 10/16/2012 at 12:52 AM

Then you need some way to note a change. Perhaps your server could use a table that just records a 'lastmod' value. Whatever the way you do it, you would have your mobile app ask the server to see if it is fresher than now, and then do the updates.

Does that make sense?

Comment 14 by Greg posted on 10/16/2012 at 1:07 AM

Yep, that makes sense, thanks. I will see if I can get something simple working.

Comment 15 by Terry Collinson posted on 12/5/2012 at 10:34 PM

Great series and a got a standalone page with all the Parse and map functionality working perfectly. But when I try and integrate it into my PG,JQM app the map doesn't fire. I have moved all the library Parse/Leaflet js/css files to the home page and visible in the resource tab loaded. Left the custom js file getting the data which is ok in the console. Googling suggests JQM and DOM but that's beyond me at the moment. Any suggestions? Thanks

Comment 16 by Raymond Camden posted on 12/7/2012 at 5:24 PM

Well, it could be anything really. If you are testing Android, can you try console debugging via DDMS? (See my other blog post on that.)

Comment 17 by Phil Barnett posted on 4/24/2014 at 5:40 PM

Great series of tutorials - many thanks

I downloaded the code from GitHub.

I re-built the app on Phonegap Build. The only change I made was to change 'phonegap-version' to version 3 in config.xml (phonegap wont build it with version 1 any more). and to put the reference to phonegap.js in index.html.

I can install the app on my Android tablet however it doesn't work. If I click on 'Add tip' I get the form however when I click on 'send tip' nothing happens. Also when I click on get tips I don't get the map.

It's working fine for me locally in the browser, both within Ripple and outside it. Also the app works fine on my Android when installed directly from Google Play.

Any ideas?

Comment 18 by Raymond Camden posted on 4/24/2014 at 5:44 PM

So to be clear, it works via Play, but not when you use PG Build?

Comment 19 by Phil Barnett posted on 4/25/2014 at 4:30 PM

Yes that's right
Google Play (the app you put on Google Play) - works
Locally in Ripple / Chrome - works
PG Build (re-built as per my last message) - doesn't work

Comment 20 by Raymond Camden posted on 4/25/2014 at 6:54 PM

Not sure what it could be then. If it works when you build locally but no in PGBuild, you may need to open a support request with them.