file: File and Camera access¶
The file API allows storage of files on the local system as well as capturing images with the camera or selecting them from the users saved photos.
Notes¶
- File objects are simple Javascript objects which contain at least a uri. They can be serialised using JSON.stringify and safely stored in Forge preferences.
- The uri parameter can be used directly on some platforms. This is not recommended - instead use the provided helper function forge.file.URL.
- Image orientation is automatically handled where possible: if a camera photo contains rotation information it will be correctly rotated before it is displayed or uploaded.
- Files can be uploaded by including them as an array in request.ajax(). For example if myFile1 and myFile2 were images returned by file.getImage():
forge.request.ajax({
url: "http://example.com/file_upload",
files: [myFile1, myFile2]
});
Note
For more information about how to cache remote files in your app, see Caching files.
API¶
getImage¶
Platforms: Mobile
Returns a file object for a image selected by the user from their photo gallery or (if possible on the device) taken using their camera.
The optional parameters can contain any combination of the following:
- width: The maximum height of the image when used, if the returned image is larger than this it will be automatically resized before display. The stored image will not be resized.
- height: As width but sets a maximum height, both height and width can be set.
- source: By default the user will be prompted to use the camera or select an image from the photo gallery, if you want to limit this choice you can set this to "camera" or "gallery".
- saveLocation: By default camera photos will be saved to the device photo album, with this setting they can be forced to be saved within your application by using "file".
Returned files will be accessible to the app as long as they exist on the device.
- file.getImage([params], success, error)¶
Arguments: - params (object) -- object optional parameters.
- success (function(file)) -- callback to be invoked when no errors occur (argument is the returned file)
- error (function(content)) -- called with details of any error which may occur
Important
On iOS devices, the first time your app reads from the gallery, the user will be prompted to allow the app to access your location. This is because the EXIF data in images stored there could be used to infer a user's geolocation. For more information, see Permissions.
getVideo¶
Platforms: Mobile
Returns a file object for a video selected by the user from their photo gallery or (if possible on the device) taken using their camera.
The optional parameters can contain any combination of the following:
- source: By default the user will be prompted to use the camera or select a video from the photo gallery, if you want to limit this choice you can set this to "camera" or "gallery".
Returned files will be accessible to the app as long as they exist on the device.
- file.getVideo([params], success, error)¶
Arguments: - params (object) -- object optional parameters.
- success (function(file)) -- callback to be invoked when no errors occur (argument is the returned file)
- error (function(content)) -- called with details of any error which may occur
Important
On iOS devices, the first time your app reads from the gallery, the user will be prompted to allow the app to access your location. This is because the EXIF data in files stored there could be used to infer a user's geolocation. For more information, see Permissions.
getLocal¶
Platforms: Mobile
Returns a file object for a file included in the src folder of your app
- file.getLocal(path, success, error)¶
Arguments: - path (string) -- Path to the file, i.e. "images/home.png".
- success (function(file)) -- callback to be invoked when no errors occur (argument is the returned file)
- error (function(content)) -- called with details of any error which may occur
cacheURL¶
Platforms: Mobile
Downloads a file at a specified URL and returns a file object which can be used for later access. Useful for caching remote resources such as images which can then be accessed directly from the local filesystem at a later date.
Cached files may be removed at any time by the operating system, and it is highly recommended you use the isFile method to check a cached file is still available before using it.
- file.cacheURL(url, success, error)¶
Arguments: - url (string) -- URL of file to cache.
- success (function(file)) -- callback to be invoked when no errors occur (argument is the returned file)
- error (function(content)) -- called with details of any error which may occur
saveURL¶
Platforms: Mobile
Downloads a file at a specified URL and returns a file object which can be used for later access. Saves the file in a permanant location rather than in a cache location as with cacheURL.
Important
Files downloaded via this method will not be removed if you do not remove them, if the file is only going to be used temporarily then cacheURL is more appropriate.
- file.saveURL(url, success, error)¶
Arguments: - url (string) -- URL of file to save.
- success (function(file)) -- callback to be invoked when no errors occur (argument is the returned file)
- error (function(content)) -- called with details of any error which may occur
isFile¶
Platforms: Mobile
Returns true or false based on whether a given object is a file object and points to an existing file on the current device.
- file.isFile(file, success, error)¶
Arguments: - file (file) -- the file object to check
- success (function(isFile)) -- callback to be invoked when no errors occur (argument is a boolean value).
- error (function(content)) -- called with details of any error which may occur
URL¶
Platforms: Mobile
Returns a URL which can be used to display an image. Height and width will be limited by the values given when originally selecting the image.
- file.URL(file, success, error)¶
Arguments: - file (file) -- the file object to load data from
- success (function(url)) -- callback to be invoked when no errors occur, first argument is the image URL
- error (function(content)) -- called with details of any error which may occur
base64¶
Platforms: Mobile
Returns the base64 value for a files content.
- file.base64(file, success, error)¶
Arguments: - file (file) -- the file object to load data from
- success (function(base64String)) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
string¶
Platforms: Mobile
Returns the string value for a files content.
- file.string(file, success, error)¶
Arguments: - file (file) -- the file object to load data from
- success (function(string)) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
remove¶
Platforms: Mobile
Delete a file from the local filesystem, will work for cached files but not images stored in the users photo gallery.
- file.remove(file, success, error)¶
Arguments: - file (file) -- the file object to delete
- success (function()) -- callback to be invoked when no errors occur
- error (function(content)) -- called with details of any error which may occur
Permissions¶
On Android this module will add the WRITE_EXTERNAL_STORAGE permission to your app, users will be prompted to accept this when they install your app.
On iOS, accessing files in the device's gallery causes the user to be prompted to give your app access to their location. This is because files in the gallery may contain EXIF data, including geolocation and timestamps.
To avoid the user being shown this prompt, you could save your image into a file rather than the gallery, using the saveLocation parameter. This is not yet supported when capturing videos.
If a user chooses not to share their location with your app, the error callback of the method trying to read files from the gallery will be invoked.