In this chapter, you will learn how to upload and download files using the HTTPClient object.
A common need in a mobile application is to upload a file (like an image) to a remote server. You might also need download a file and store it locally on the device. For example, you might download starting SQL data for your app's database the first time the user runs your app. Luckily, both are easily accomplished with Titanium.
Assuming you have a server-side service which accepts file uploads, you should find upload fairly straightforward. Titanium handles the setting of headers and marshaling POST parameters for you, so you simply need to pass a Titanium blob object to
send(). A blob is returned by many different Titanium APIs, including
Titanium.Filesystem.File.read. Below, you will find an example of how you might select a photo from the device photo gallery, and upload that blob to a web service:
Note: this file upload process is only valid if using Mobile Backend Services services file update. The event.media doesn't contain file contents but rather just the information about the file, location, size, dimensions, and so on.To upload the file, you will need to use
Ti.Filesystem to get a handle on the file and access to the file itself. For example:
Monitoring upload progress
xhr.onsendstream event, you can monitor upload progress and update a progress bar. This event is called at regular intervals as the data is being transmitted. When the event is fired, the
progress property of the event object will contain a value from 0.0-1.0 with the progress. That's exactly the type of value you'll need for a
Occasionally, you will also need to download and store a file from a remote server. In concert with the
Ti.Filesystem module, you can fetch and save a file. Below is a cross-platform example for fetching a remote image and saving it to the
On iOS, a simple property of the HTTPClient object lets you save a file to the local file system. Below is an iOS-only example of how to fetch a file from a server and store it in the
applicationDataDirectory, the primary location for any read/write Filesystem IO in a Titanium application:
File storage locations
When downloading files, keep in mind the locations on the device you can access files. The following locations are potentially accessible:
- Ti.Filesystem.applicationDataDirectory: A read/write directory accessible by your app. Place your application-specific files in this directory. The contents of this directory persist until you remove the files or until the user uninstalls the application.
- Ti.Filesystem.resourcesDirectory: A read-only directory where your application resources are located; this directory corresponds to the project/Resources directory in Studio. The contents of this directory persist until the user uninstalls the application.
- Ti.Filesystem.tempDirectory: A read-write directory where your application can place temporary files. The contents of this directory persist until your application fully closes, at which time the operating system could delete your files.
- Ti.Filesystem.externalCacheDirectory: A read-write directory where your application can cache data on external storage (SD card), if such a location exists. Check first with
Ti.Filesystem.isExternalStoragePresent()(which returns a Boolean). Only available on Android.
- Ti.Filesystem.externalStorageDirectory: A read-write directory on the external storage device (SD card) accessible by your app, if such a location exists. Check first with
Ti.Filesystem.isExternalStoragePresent()(which returns a Boolean).
Monitoring download progress
As with uploads, you can use an HTTPClient callback to monitor download progress. In this case, it's the
xhr.ondatastream callback. You'd use it like this (assuming you have a progress bar named
ind as with the upload progress example):
In this activity, you will download a large image file, uploading a progress bar as the file is downloaded. You'll save the file to the local file system, then display the image in an ImageView.
- Create a new Titanium Mobile project. You can keep the two-tab code or replace it.
- To the window, add a progress indicator centered in the window, 10 pixels from the top, with a width of 200 and height of 50. Set the minimum value to 0, max to 1, and current value to 0. Show the indicator.
- Add an ImageView to the window that will display the downloaded photo.
- Add an HTTPClient that will:
- Download http://farm4.static.flickr.com/3244/3115485060_076a345932_o.jpg (from Flickr).
- Save the file to the
applicationDataDirectoryin a file named cool_photo.jpg.
- Update the progress bar as the file is downloaded
- Fire an event once the photo is downloaded and saved. Pass the native path as a payload of that event.
- Add an app-level event listener to receive the native path of the downloaded photo. Hide the progress bar and set the ImageView's image property equal to that native path to show the image.
- Build and test the image in the simulator/emulator.
References and further reading
- Finished code
- Filesystem Access and Storage chapter
- This blog post contains another technique for caching downloaded images
In this chapter, you learned how to upload and download files using the HTTPClient object.