Click on any phrase to play the video from that point.
[metallic humming]
[ADOBE DEVELOPER CONNECTION]
Hi. My name is Raymond Camden, and I am a Developer Evangelist for Adobe.
Today I'll be talking about the File API under PhoneGap.
It's important to note that the File API
is actually an implementation of the HTML5 File API.
When I first read the PhoneGap docs, I felt a bit lost
as to actually how to use this.
Well, keeping in mind that this is actually a different spec,
it's actually HTML5, you can find more documentation outside of the PhoneGap site.
I really, really recommend the HTML5 Rocks File API guide.
It was really instrumental in helping me understand the API as a whole,
both for desktop browsers as well as within PhoneGap as well.
Everything you learn on that guide you can apply just as easily within PhoneGap.
As you can imagine, a File API provides the support for working with file systems.
So you'll have all the kind of basic things that you expect.
You can look at a directory and you can list its contents.
You can look at files, you can create, you can write to,
you can delete, you can move, etc.
Basically, anything that you would expect to be able to do on a server side application
like with ColdFusion, you can also do with PhoneGap as well.
So what I've done is built a very simple demo
that shows just a few of these APIs.
Let's take a look at it.
What I have here is some basic HTML
that's going to allow me to test various different functions.
You can see that I have one for creating or appending to the test file,
reading from the file, getting metadata about the file,
erasing it, and just doing a real basic directory list. All right?
My application begins with one important thing:
a deviceready event handler.
You don't want to do anything device specific until PhoneGap basically says,
"Hey, I'm ready to go."
So almost every single PhoneGap application
will have something like you see on line 123 here.
Once I've done that, the first thing I need to do is actually ask for the file system.
There's 2 types of file systems: persistent and temporary.
Obviously, you would use the one that makes sense for your use case.
Most times you'll probably want the persistent file system.
Once I have requested that, we can look at the callback handler for that.
What I get sent back is a file system object.
I'm going to cache that and use it throughout the rest of my application.
It's essentially like a handler to the disk drive on my device.
Once that works, once it actually succeeds--and I want to make sure it does--
I then add event handlers for all those buttons.
And again, all those are doing is testing various parts of our File API.
Let's look at the first one, the doDirectoryListing.
What I can do is use the root property of our file system object.
This will point to a directory.
And I can create a reader from that.
This reader exists just to list directory entries.
So on that object I can call read entries.
It takes 2 attributes: the success handler and the error handler.
In our success handler and our function gotFiles,
I am passed an array of either file entries or directory entries.
These are both simple objects that look very, very similar.
They have a name, they have a fullPath, they also have a flag isFile and isDirectory
so we can see what type of entry it is.
You can see in this handler here all I've done is simply gone over that loop
and written out the screen.
If we take a quick look at that, I'm going to click that Show Directory Contents,
and you can see it appended what's in my directory now.
Let's look at actually creating a file.
That callback function was doAppendFile.
The way that I can create a file is by simply asking for the file.
You'll see in my handler here I've said create equals true.
That's basically telling the API that it's okay if it's not there.
If it's not there, just make it for me anyway.
Once I have that, I again have a callback to handle actually getting that file access.
And then once I do that, I can begin writing with it.
Now, if you're not getting it yet, everything in this File API works with callbacks.
So we had a call to get the file. That fired a callback.
We'll then have an API call to actually write to it,
and that's going to have a callback as well.
You can see here on lines 60 to 67 I am creating a writer on that file entry,
and that's going to actually handle appending to my file.
Note that to handle an append we have a seek operation
which allows you to go to anywhere in the file.
In this case, I'm going to the entire length so I can write to the end.
And all I'm doing is writing some simple text.
You can also actually write binary data as well.
Once that's done, it will append to the web app.
And if we take a look at that,
I've done the create, and now if I want to read it,
I could see there is my line.
Let's look at that code.
Again, for the reader I'm going to get the file again.
And in this case, I'm running a readFile callback,
and that's going to work with a FileReader API.
That API allows me to either read as text or read as binary.
And again, I have a callback, and in this case called onloadend.
That will be passed the actual result of that file read,
and because it's plain text, I can just append that right onto the page.
Let's look at one more example, the metadata.
This also is going to fire a callback.
So I request my file again
and I say getMetadata and point it to this callback right here.
Currently, the only supported data in there is the modification time.
That will tell you when the file was last changed.
If we go back to our app, we can get that and see it was last modified a few minutes ago.
As our last example, we can also delete a file.
Once again, I am asking for the file handle,
and once I get it, I can then call the remove function on it.
That also takes a callback.
In this case, all I'm doing is logging that the file was removed.
So if I run that button, it will kill the file.
And if I do the directory list again, it will show that the file is gone.
So that is a quick look at most of the File API. There is more in there.
I encourage you to check the docs out at PhoneGap and also html5rocks.com.
[docs.phonegap.com - html5rocks.com]
I am Raymond Camden. Thank you very much.
[ADOBE DEVELOPER CONNECTION]
[metallic humming]
