Click on any phrase to play the video from that point.
[Adobe Developer Connection]
Hi, I'm Adobe Developer Evangelist Kevin Hoyt.
We've been talking about the PhoneGap APIs and deploying
and leveraging native capabilities through web standards.
It's been a fun tour so far, but there's more to come.
This time we're going to take a look at using the Compass on the device
and relaying that information via PhoneGap into our HTML or JavaScript in CSS.
So we take a look at Dreamweaver here,
the power house where all the magic happens.
I've got some code going, and we'll take a look at that code in just a minute,
but also over here on my live view I have the application running.
It gives you an idea of what it will look like when it's actually deployed to the device.
I've got a heading text field here where we''ll actually dump off the raw data
coming from the compass in terms of the heading.
I have a graphic display of that heading as well, and there,
there's a red needle and a blue needle.
These are actually just one big needle, and it will rotate using CSS3 transforms
to the degree which is the current heading coming from the compass on the device.
The last button down here is a "Watch Heading" button so we can either
stop or start watching the compass.
We don't always have to watch the compass.
If you decide that you want to leverage the compass,
you don't have to just jump in and always be watching it.
You can watch it at certain opportune times in the process of your application.
So now let's take a look at the code here.
We've got some CSS for the application,
and for this particular application, we're going to use PhoneGap and jQuery.
You can see the logic that is in this compass JS,
but just to kind of quickly show you through the HTML,
there is a div here where we keep our main panel.
I've got a heading label, got a heading text field,
and that's where we're going to put the heading
information coming off of the compass.
Then, I have an image here for the compass rose, and then an image here for the needle.
They're separate though their actually positioned in the same place,
and we're just going to rotate that needle
depending on the heading coming from the compass.
Then, there's a div here that represents the button for us to click.
Now I want to go over to the JavaScript file,
and we have a document dot add event listener device ready.
A device ready is that magic that says, "Hey, the WebKit has started,
the native application has started, PhoneGap has been able to establish
a communication between the two, and we're ready to go."
So, I've got device ready, that's an event that
PhoneGap is going to throw out there for us to use.
Now, when the device is ready, we're going to use a watch ID.
Just like with JavaScript, normally, when you're using set interval,
you'll get a watch ID back off of that so you can clear it or stop it from watching
or running that interval at a later point.
We're doing the same thing here.
We're going to stop that watch from happening down the road,
so we want to keep track of that ID.
On our button that's labeled "Watch the Compass"
we want to go ahead and watch when that is clicked.
In this case, I'm using a touch start event.
Now, touch start, touch move, touch end are touch events
that you'll find on mobile devices.
They're more responsive because they're a little closer to the OS.
They're a little more responsive than using the traditional click and mouse events.
In fact, in many cases, mouse events just flat out won't work.
So we're going to use touch start, which is for us going to say, "Hey, that's a click."
We're going to go ahead and launch off some logic here.
It the watch ID is 0, which means it's not currently launching the compass,
then go ahead and start it up.
Now, I've got an options block here,
just a little object we're going to create,
and it's got a one single property called "frequency,"
and this frequency, in this case, is set at 100,
which is actually the default, so every 100 milliseconds poll the compass,
and see what the data coming off is.
We're going to pass that along to when we actually invoke the compass.
We're going to use Navigator for most of when you're using PhoneGap.
You'll find that Navigator object, and then whatever functionality it is off that.
So in previous sections we've done accelerometer or the camera.
In this case, it's going to be navigator.compass.watchheading,
and then we're going to pass a success function,
an error function, and then the options.
We've already talked about the options.
In this case, it's just a frequency of how often to actually poll the compass
and take a look at that.
If it had an error, we can console.log, and that'll show up in our console,
or we can use the alert notification, or you can modify the HTML on the page;
whatever works for you,
and then the most important part here is if we have a success,
we're going to call this function that has a heading,
and that's to be the heading coming off of the compass,
and we're going to go ahead and I'm going to do a little bit of rounding
of that, and I'm going to concatenate the number for the heading
with a term DEG for degrees, and that's what we're going to use for our CSS
in the terms of the transform, and be able to move that needle around,
and then we'll go ahead and say, "Txt heading," which is the raw text--
raw field that we're actually going to display the text from,
and that's going to be heading.magneticheading.
Now there's actually--it turns out that the heading object that comes back
into the success function has a couple different options.
There's magnetic heading.
There's true heading.
There's the deviation or how accurate that heading is,
and not all devices support all those different types of headings.
So, the one supported by most of the devices is magnetic heading,
and that's what we're going to use,
and if you're not a pilot or a sailor,
you probably really don't need to worry about true heading
or deviation and so on.
So, magnetic heading will work for us for now,
and then we're going to go ahead and take that image needle,
which is that red and blue needle that I've overlayed on the compass rose there.
Do a little WebKit transform here,
and rotate for the degrees of rotation coming off of the compass,
and if we click on that button, and the watch is
already running, there's some value in the watch,
and we'll go ahead and stop watch in the compass,
and so it's going to be navigator.compass.clearwatch,
and pass it to watch ID.
Clear the watch ID back to 0, and reset the button label.
So that is our complete application of leveraging the compass.
Let's go ahead, and I'm just going to pop on over to Eclipse here,
and I'm going to go ahead and run this application,
and it's going to compile it, and push it off onto the emulator here,
and wallah!
Now we have our compass, but you'll notice it--
you know if I turn my laptop,
it's not going to turn the compass because there's no compass in my laptop.
So that doesn't work in the simulator.
At least you can see what it's going to look like and how it will generally function,
but to really get the idea of how the compass works,
we're going to go ahead and take my handy dandy Droid X device,
plug that into the USB port,
back on over to Eclipse here, and now with this Droid X device mounted,
when we run the program again,
we'll get a new dialogue that says, "Do you want to run this in the emulator or
do you want to run this on the device?"
I'll go ahead and select the device,
and say, "Okay,"
and then it will compile it.
Take it over and install it,
and give that a minute to come over,
and so there it is on the device,
and now I'll just say, "Watch heading,"
and that'll start watching, and then you can see the heading up here,
and the raw value so we're just about true North-South there,
but if I tilt it,
you can see the heading turn and the little compass needle turn respectively.
So now we'll never get lost.
We have our handy dandy compass.
We can be out there in the ocean, and we'll stop heading,
and put that guy down.
Now, that's how to use the compass API as part of PhoneGap.
Then, again, not all devices have compasses.
So this particular API will only work on those devices that do.
In this case, this Droid X has a compass
and that's what we're going to go ahead and tap into,
but not all devices have that.
Now, we've talked about a lot of different APIs.
This time we talked about a compass.
There's actually more PhoneGap APIs ahead, so come on back.
I'll be waiting.
[Adobe Developer Connection]
