file by Trigger.io

Currently displaying version

file: File and Camera access

The forge.file namespace allows storage of files on the local system as well as capturing images with the camera or selecting them from the users saved photos.

  • 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 forge.request.ajax(). For example if myFile1 and myFile2 were images returned by forge.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.

Config options

usage_description
This key lets you describe the reason your app accesses the user's camera and photo library. When the system prompts the user to allow access, this string is displayed as part of the alert.

API

forge.file.getImage([params], success, error)

iOS, Android

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.

Parameters:
params
object an optional object of 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 modules-file-permissions.

The optional parameters can contain any combination of the following:

  • width (number): 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 (number): 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.

forge.file.getVideo([params], success, error)

iOS, Android

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.

Parameters:
params
object an optional object of 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 modules-file-permissions.

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".
  • videoDuration: If the user records a new video then the video duration will be limited to the given length in seconds.

Returned files will be accessible to the app as long as they exist on the device.

forge.file.getLocal(path, success, error)

iOS, Android

Returns a file object for a file included in the src folder of your app.

Parameters:
path
string path to the file, e.g. "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

forge.file.cacheURL(url, success, error)

iOS, Android

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.

Parameters:
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

Cached files may be removed at any time by the operating system, and it is highly recommended you use the forge.file.isFile method to check a cached file is still available before using it.

forge.file.saveURL(url, success, error)

iOS, Android

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 forge.file.cacheURL.

Parameters:
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

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 forge.file.cacheURL is more appropriate.

forge.file.isFile(file, success, error)

iOS, Android

Returns true or false based on whether a given object is a file object and points to an existing file on the current device.

Parameters:
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

forge.file.URL(file, success, error)

iOS, Android

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.

Parameters:
file
file the file object to load data from
success
function(url) callback to be invoked when no errors occur (argument is the file URL)
error
function(content) called with details of any error which may occur

forge.file.info(file, success, error)

iOS, Android

Returns information about the given file. Supported attributes: size, date

Parameters:
file
file the file object to get information for
success
function(object) callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.file.base64(file, success, error)

iOS, Android

Returns the base64 value for a file's content.

Parameters:
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

forge.file.string(file, success, error)

iOS, Android

Returns the string value for a file's content.

Parameters:
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

forge.file.remove(file, success, error)

iOS, Android

Delete a file from the local filesystem, will work for cached files but not images stored in the users photo gallery.

Parameters:
file
file the file object to delete
success
function(string) callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.file.clearCache(success, error)

iOS, Android

Deletes all files currently saved in the local cache.

Parameters:
success
function(string) 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.