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 working through the PhoneGap APIs in this series,
and this time, we're going to start talking about contacts.
This is one of my favorite features of PhoneGap
because capabilities reach in to the iOS contacts
and either create contacts or search them and be able to leverage data
that comes with those contacts in your PhoneGap application.
So if we take a look at Dreamweaver here, where all the magic happens.
I've got 2 views.
I've got a split view going on with code on the left,
and a live view of the application on the right.
So on the right here, we can see Contacts title bar, First name, Last name, Email, Mobile.
One of the fun things I like about the emerging web standards is some of the new capabilities.
So for example, the input tag has a placeholder attribute now that let's you have, in this case,
a grayish kind of default filler for that text field,
and when we actually tab on that text field the filler goes away--
the placeholder goes away, and we can put in our values.
One of the things we'll see as we get this application actually running on the device
is how the different types of inputs that we now have available to us can reflect the keyboard
that gets displayed on the device. Super cool stuff!
But for now, let's just go through the code and figure out how to work with the contacts
to begin with.
So let's come over here to the contacts JavaScript,
and I've got 2 different buttons there.
One is for creating a contact and then one is for finding a contact.
So we'll take a look at creation first.
So we have this btnCreate, which is the button that's clicked on for create,
and I will be using touchstart which is on mobile devices.
The touch events seem to be more responsive than, for example, using a click event.
So let's say touchstart, and then we're going to say new contact.
Rather we're going to say here's a contact property not a variable,
and we're going to use that navigator object,
just like we do with all the other PhoneGap APIs--
navigator, in this case, .contacts.create.
And what that's going to do is, spit back to us a contacts object ready to be manipulated
and stored into the device contacts listing.
Now here we have a contact.displayName, contact.nickname,
and I'm just going ahead and appending the first and last name fields from the
text fields the user has entered, and putting those into the display name
and nickname fields.
There is also a formal ContactName object.
Now that's part of the PhoneGap APIs, and the contact name object lets you do things like
given name, family name, honorific names, prefixes, suffixes, and things like that.
I'm going to go ahead and just use givenName which is my first name,
and then the familyName, which is the last name,
and then there's a contact.emails and this is actually an array
because you might have an email for your personal.
You might have an email for work.
You might have some other email address, so you can specify those different types
of emails and in an array, each email entry is going to be a contact field object,
which again also is part of the PhoneGap API, and in this case,
I'm going to have 1 for home, and that's going to get the email from the textfield
in my user interface and use that.
I might choose to have work or other labels in there as well.
Same thing kind of goes for phone numbers.
So contact.phoneNumbers is an array because I might have more than 1 phone number--
work phone number, mobile phone number, or a home phone number and so on and so forth,
fax number and so on.
So we have that.
We'll also be in array of contact field objects, and in this case,
mobile is the one that I have in my user interface and the one that we'll be using.
We'll go ahead and pull that from that field.
Now once I have decided that all of the different contact elements that I'm interested
in capturing have been captured, in this case, I only have those 4 fields,
so not a whole lot of data to capture.
But once I have that object populated, I can go ahead and save it.
So as we go ahead and get that contact object from PhoneGap,
there's a method on that object called save, which we can use to actually save it
to the contacts directory on the actual operating system.
So we say, contact save and just like most PhoneGap calls,
you get a call back depending on whether or not it is successful or has errored,
and in this case, the success.
What we're going to do is just clear out all the values
in the user interface so that'll tell the user, hey this has been saved.
The populated fields have been removed.
I don't know if that is the most efficient UX approach,
but that's what I've used in this case,
and then if it's an error, we're going to use console.log to error to show an error message
out to the console.
Now that is creating a contact, so again, you use the PhoneGap API
to create a contact object, populate the fields you want,
and then say contactinstance.save,
and that will save it out to the system.
The next then is to be able to find a contact that's already existing or already out there.
So in this case, I have a button called find, so btnfind and we're going to
listen for a touchstart, which again is the cool end of a click.
In this case, the field I'm going to be looking for is star.
Star means look through all the fields and it also means--and this is really important--
it also means return all the fields.
In this particular instance, PhoneGap tries to be a little bit on the conservative side.
In my opinion, it will by default only search for the fields that you give it,
and only return those properties that you're searching for.
So for example, you just want to search in the name fields,
then you can specify those properties here,
but those will also be the only fields you'll get back in the contact,
so you won't get email and phone numbers, and so on and so forth.
So in this case, I'm interested in all of that additional data,
so I'm going to go ahead and use star, so it'll search the fields and get all the fields back.
The other thing that PhoneGap tends to play very conservatively here,
is we look at the options, say filter--the filter value is the actual string
that we're searching for in the contacts.
But then here in the multiple, I'm going to specify true.
The default is actually false.
What does multiple mean?
Well, multiple means I'm only going to get multiple matches back,
so if I search for Hoyt, and in this case, I have all my family in my contacts,
I'm going to get all the Hoyts back.
The default though by PhoneGap is only to get 1.
So it finds that first match and that's it, and that makes sense.
You don't want to overwhelm the proxy and the communication.
You don't want to overwhelm building out the user interface
for what might be mini, mini contacts on that device.
So that's how PhoneGap is going to be conservative on the inside.
It's just give you what you ask for back and only return 1 record,
and that's going to keep it real compact.
Just so you know, if you actually look at the console dump,
it's actually a JSON object that's going back and forth,
so it's really easy to actually start pressing and dealing with that data.
Here, once we've got our field set up and our options set up,
we're going to say navigator--there's that magic PhoneGap object again--
.contacts.find.
We're going to pass it to fields we want to look for,
and in this case, the function for success is going to take the values
off of the contact object that comes back,
and put those into the UI.
If it's an error, it will display an error, and then of course, we want to pass it to options.
Just really quickly here, you'll notice that the contacts is actually an array.
So the contact objects we get back is an array.
In this case, I'm just going to pull the first one off.
I certainly could have looped through the multiples and created a list
or some other display for them,
but it is an array.
I also notice the things like emails where we said we could have more than 1 email
and same thing for phone numbers where you can have more than 1 phone number.
Both of those are also arrays that you're going to want to get the value.
If you're ever in question as to what those properties are in the content object
that comes back,
the PhoneGap documentation is actually pretty good in this respect,
but I've also found it very, very helpful to just dump out the contacts information itself
and look at it as a JSON object and be able to pick off parts and pieces
I'm interested in as well.
So there's our code for creating and finding a contact.
Let's go ahead and run that.
I've got my simulator here set up, so we're going to go ahead and run it in the simulator.
We'll go ahead and put in me, Kevin. And Hoyt.
And khoyt@--it's trying to recommend that I use a capital K. I don't want to--
@adobe.com. Here we go.
I also want to point out here that the keyboard here that you see on iOS
actually has the @ symbol in the center, smaller space button, it's got a dot button
versus if we go back up to the last name here, you'll actually notice a big, giant space bar
just like you'd find on your keyboard at home.
So the different input types you get from the emerging standards give you
different keyboards on the mobile device.
Now I'll actually come over to the mobile number.
You get a totally different keyboard, and this is pretty cool.
This is actually just like the dial pad that you would normally get
if you're going to call somebody.
So in this case, let's say I'm--I don't know--369-258-1470,
and you notice also that the keyboard here has previous and next and done,
and so now we've gone ahead and created--we've captured the basic contact information.
We'll go ahead and create,
and if it's created and successful,
remember we're going to clear the fields.
The fields are, indeed, now cleared, so we know that contact exists.
Proof is in the pudding, as they say.
So let's go over to our contacts application--Wa la! Here it is! Kevin Hoyt.
Click on that record. We can see Kevin Hoyt.
We can see the nickname field, the mobile number has been captured,
the home email address is there, and now if we jump back into our demo application
here and look for say, Hoyt in the last name, go ahead and click find.
We'll go out, hit the contacts database on the device, come back with the records
that we're interested in.
In this case, it will show just one record and populate out the rest of the fields.
So now we can actually create contacts and find contacts in the database
of the device.
This opens the door for some really neat possibilities, like for example,
I might choose to take this mobile phone number and put a little phone icon next to it
to call, so if in the context of your application you want to call somebody,
you can do that, email them, and so on and so forth,
which is a pretty cool API.
I really like getting into that native database--native systems a little closer,
so PhoneGap, of course, is great for that.
HTML, JavaScript, CSS web standards are great for that.
That's how to use the contacts API with PhoneGap.
More API coverage to come.
So come on back. Until then, I'll be waiting.
[Adobe Developer Connection]
