The Cordova framework provides two APIs for working with the device camera. One is the Camera API, which provides developers with direct access to the native camera APIs, and the other is the Media Capture API described in the next section. The difference between the two options is that the Camera API exposes only the ability to take pictures with the camera, while the Media Capture API provides an interface to the camera that includes photos as well as videos plus the ability to record audio files. In this section, I show you how to use the Camera API to capture pictures from a Cordova application; refer to the section “Capturing Media Files” for information on the other options. To enable an application to take photos using the Camera API, you must first add the Camera plugin to your project by opening a terminal window and issuing the following CLI command from the Cordova project folder:
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
From a programming standpoint, getting a Cordova application to take a picture is pretty simple; all you have to do is have the program call the Camera API using the following code:
navigator.camera.getPicture(onCameraSuccess, onCameraError);
To show how this works, I created a simple camera application that makes that call to getPicture then displays the data returned from the camera. You can see a screenshot of the application in Figure 12.11.
FFiigguurree 1122..1111 Camera Demo Application
As soon as you click the Take Photo button, the device’s native camera application opens, as shown in Figure 12.12. Manipulate the camera and image any way you want, then take the picture; in this example, you would click the camera aperture image on the right. What you will see here will vary depending on the mobile device platform the on which the application is running.
ptg11524036
FFiigguurree 1122..1122 Device Camera Application: Confirming Photo
Notice in Figure 12.12 that there isn’t a way to cancel taking the photo. Even if you decide not to capture a photo, you will have to snap one here; then you can cancel it in the next step.
Depending on the mobile device, you may be prompted to approve the photo, as shown in Figure 12.13. In this example, you can tap the checkmark to select the photo and return to the Cordova application; tap the X in the bottom right to cancel, returning the photo information to the Cordova application; or click the camera icon on the lower left to discard this photo and take another one. No, I’m not sure why the photo is rotated in the screen shot.
ptg11524036 When you accept a photo by tapping the checkmark icon, the device camera application will close and
return information about the selected photo to the Cordova application, as shown in Figure 12.14. In this case, since I didn’t tell getPicture anything about how to take the picture or what to do with it, the API used its default settings and simply returned a file URI pointing to the image file. At this point, the Cordova application can access the file using the URI it received from the API and render the image on the screen, upload it to a server, or do anything else it wants.
FFiigguurree 1122..1144 Camera Demo Application: Photo Results
If you choose to cancel the photo you’ve taken, the Camera API will return an error message, “Camera Cancelled,” to the Cordova application.
Now that’s not all there is to the Camera API—I was just showing you the API’s default behavior. You can also call getPicture and pass in an options object, which tells the API what to do and how to do it. Here’s an alternative way to call getPicture:
navigator.camera.getPicture(onCameraSuccess, onCameraError, cameraOptions);
The cameraOptions shown in the example is a JavaScript object, which can look like the following example from the Cordova documentation:
var options = { quality : 75, destinationType : Camera.DestinationType.DATA_URL, sourceType : Camera.PictureSourceType.CAMERA, allowEdit : true, encodingType: Camera.EncodingType.JPEG, targetWidth: 100, targetHeight: 100, popoverOptions: CameraPopoverOptions, saveToPhotoAlbum: false };
ptg11524036
W
Waarrnniinngg
Different platforms ignore some of these properties, so be sure to check the quirks section in the Cordova documentation before using them in your applications.
A developer will use some or all of these properties to control the picture capture process using the Camera API. Each of the possible options is described in Table 12.4.
Table 12.4 CCaammeerraa OOppttiioonnss
PPrrooppeerrttyy DDeessccrriippttiioonn
allowEdit
Boolean value: Specifies whether the photo can be edited by the user before being returned to the Cordova application. Not all mobile device platforms support this option, nor will many users expect it depending on your application.
cameraDirection
Numeric value: Directs the API on which camera (front or back) to use to take the photo. Use
navigator.camera.Direction.FRONT for front-facing camera (screen side) and, wait for it,
navigator.camera.Direction.BACK to use the camera on the back of the device.
correctOrientation Boolean value: Instructs the API to rotate the image to correct for the orientation of the device when the picture is taken.
destinationType
Numeric value: Specifies how the API will return the captured image. Options are Camera.DestinationType.FILE_URI, which is the default option and illustrated in the earlier example; Camera.DestinationType.DATA_URL, which returns the image as a base64-encoded string; and
Camera.DestinationType.NATIVE_URI, which returns a native URI for the image file.
Be careful using DATA_URL because JavaScript simply isn’t capable of dealing with the image as an encoded string. Your app may crash if a high-resolution image is returned as a string to your program.
encodingType
Numeric value: Specifies the output format for the photo. Specify Camera.EncodingType.JPEG to have the API return a JPEG image or Camera.EncodingType.PNG to have the API return a PNG file.
mediaType
Numeric value: When SourceType is set to PHOTOLIBRARY or SAVEDPHOTOALBUM, this property specifies what type of files can be selected by the application user. Use
Camera.MediaType.PICTURE to allow selection of photos only, Camera.MediaType.VIDEO to allow video files to be selected, and Camera.MediaType.ALLMEDIA to allow any supported media file to be selected.
When VIDEO is selected, the API will only return a File URI; otherwise, the API will return the image information in the format specified by the destinationType property.