Creating and uploading images is a common feature, and Sencha Web Application Manager makes it easy to include this functionality in apps. The process is straightforward:
- Acquire an image
- using a camera or an existing image
- by downloading from the Web
- Store the image locally
- Upload the image to a Web service
Sencha Web Application Client provides APIs to facilitate all of these steps.
Using the Camera
Many different types of applications benefit from access to a device’s or system’s on-board camera. Sencha Web Application Client includes a promise-based camera API that makes it easy to acquire images and get them into your app. It consists of one basic method, Ext.space.Camera.capture(), which is configured by an options object controlling its behavior. The default behavior is to return the acquired image data as a parameter to the promise handler:
var promise = Ext.space.Camera.capture({
width: 1920, // pixels
height: 1080, // pixels
quality: 80 // percent
});
promise.then(function(imageData) {
// got it
});Image Encoding
Unless otherwise requested, the image data will be returned directly in JPG format (you can specify this explicitly with encoding: "jpg"). If for whatever reason you need a lossless image, Sencha Web Application Client supports encoding: "png" as an option as well.
Image Sources
Sencha Web Application Client lets you easily choose the source for acquired images. The default source for images is the camera itself (source: "camera"), to allow the user to take new photos and use them immediately. However, sometimes users want to choose from existing photos; for such cases, Sencha Web Application Client supports source: "library" or source: "album" to launch a native image picker interface, select an image, and provide it to your application.
Downloading Images From the Web
When an image already exists on the Web somewhere, use Sencha Web Applicaiton Client’s Download API to fetch it. All you need is the image’s URL:
var download = Ext.space.Downloads.download({ url: theImageUrl });This download() method returns Ext.space.files.Download object instances which act like promises and let you provide handler functions for various life cycle events. The simplest usage is to simply attach a handler with the normal then() method:
download.then(function(fileObj, downloadObj) {
// inspect the completed download object, or do something
// with the saved Ext.space.files.File
// for example, if you need to retrieve the stored file's contents:
fileObj.getContents(function(imageData) {
// process the imageData, presumably
});
});Storing Images to the Filesystem
Depending on the application’s requirements, it may be necessary to manipulate the acquired image data in some way before storing it. Other times, all that is required is to save images immediately. In the case of downloaded images, Sencha Web Application Client will save them to the filesystem automatically, so applications that need to process them will want to load them with .getContents() as above, then save the new contents after processing; if no processing is required, then all that needs to happen is to let the download complete.
For images acquired via the Camera API, the process of saving images to the filesystem depends on how the .capture() method is invoked.
Processing Image Data and Manually Saving Images
When an application needs to process an image before storing it, the best thing to do is to use Sencha Web Application Client’s default behavior and retrieve the image data as a JavaScript variable, then process it, then save it to the filesystem.
var promise = Ext.space.Camera.capture({
width: 1920, // pixels
height: 1080, // pixels
quality: 80, // percent
encoding: "jpg" // format
});
promise.then(function(data) {
var collection = Ext.space.SecureFiles.get("userpics");
var processedData = processImage(data); // or whatever you need to do
var fileOptions = {
name: "newImage.jpg",
type: "image/jpeg"
};
collection.set(fileOptions, processedData).then(function(file) {
// do anything necessary with the saved Ext.space.files.File
});
});Saving Acquired Images Directly
Often, however, an application doesn’t need to manipulate an image in any way once acquired, and all it needs to do is write it as a file for use later. Rather than force you to go through all the steps yourself as above, Sencha Web Application Client will do it directly if you pass destination: "file" (as opposed to destination: "data"). In this case, the promise handler will receive an Ext.space.files.File object representing the saved file. If desired, you can also specify the collection into which the file will be saved. For example:
var promise = Ext.space.Camera.capture({
width: 1920, // pixels
height: 1080, // pixels
quality: 80, // percent
encoding: "jpg", // format
destination: "file", // to save to the filesystem
collection: "userpics" // name of the destination collection
});
promise.then(function(file) {
// got a Ext.space.files.File object
});Uploading Images to a Web Server
For some applications, simply manipulating and/or storing images to the system is not enough; sometimes requirements dictate that an application upload a file to a Web service somewhere. Sencha Web Application Client provides an Upload API that facilitates this.
The first step is to get the image onto the filesystem, using any of the methods described above. Then, call the file’s .upload() method to POST it to a URL. For example, using a new photo:
var promise = Ext.space.Camera.capture({
width: 1920, // pixels
height: 1080, // pixels
quality: 80, // percent
encoding: "jpg", // format
destination: "file", // to save to the filesystem
collection: "userpics" // name of the destination collection
});
promise.then(function(file) {
// got a file, now upload it to an HTTP form handler:
var uploadPromise = file.upload({
url: "http://example.com/some/path/upload",
fileFieldName: "uploadFile"
// params: { /* optional extra POST data */ },
// headers: { /* optional request headers */ }
});
uploadPromise.then(function(response) {
// inspect the response, if desired:
// response.statusCode, .headers, .body
});
});The .upload() method’s returned promise resolves when the file is finished uploading. If your application needs to keep the file, there’s no need to do anything further; however, for files you no longer need, you can easily remove them with the .remove() method on the file object itself.
Conclusion
There are many use cases for applications needing to acquire and process images. Combining Sencha Web Application Client’s Camera, SecureFiles, Downloads, and Uploads APIs puts unparalleled rich functionality within the reach of Web applications in a simple consistent way.