fs by Trigger.io

Currently displaying version

fs: Filesystem Access

The forge.fs namespace provides an API for filesystem access and platform user interfaces for filesystem operations.

  • File objects are represented as JavaScript Strings containing an URI reference. There are no guarantees that a given URI will remain valid over time and, as should, they should not be stored. If you need to persist the location of a file see TODO Bookmarks and TODO Caching.

  • It's not recommended to embed a given File's URI directly within HTML as a given platform's web view may not support access to the resource. Rather use the provided helper function forge.fs.embed to obtain a reference that can be safely embedded.

Config options

ios.itunes_file_sharing_enabled
Specifies whether the app shares files through iTunes. If this key is true, the app shares files. If it is not present or false, the app does not share files.
ios.supports_document_browser
If this key is set to true, the user can set the document browser's default save location in Settings. Additionally, the local file provider grants access to all the documents in the app's Documents directory. These documents appear in the Files app, and in a Document Browser. Users can open and edit these document in place.

API

forge.fs.browser

iOS, Android

Opens a browser interface that allows the user to select a file on the device and returns an array of selected uris.

Parameters:
options
multiple:bool
success
function([string]) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.copy

iOS, Android

Copies the file, directory or other resource pointed to by uri.

Parameters:
source
ForgeFile | URL
destination
ForgeFile | URL
success
function(bool) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.delete

iOS, Android

Deletes the file, directory or other resource pointed to by uri.

Parameters:
uri
ForgeFile | URL
success
function(bool) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.embed

iOS, Android

Takes an arbitrary uri and returns an uri which is accessible to the web view & javascript.

Parameters:
uri
ForgeFile | URL
success
function(string) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.exists

iOS, Android

Test whether or not the given uri exists by checking with the file system. Then call the callback argument with either true or false.

Parameters:
uri
ForgeFile | URL
success
function(bool) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.isFile

iOS, Android

Test whether or not the given uri is a file.

Parameters:
uri
ForgeFile | URL
success
function(bool) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.isDirectory

iOS, Android

Test whether or not the given uri is a directory.

Parameters:
uri
ForgeFile | URL
success
function(bool) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.list

iOS, Android

Reads and returns the contents of a directory pointed to by uri as an array of uri's.

Parameters:
uri
ForgeFile | URL
success
function([string]) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.makeDirectory

iOS, Android

Creates a directory at the path pointed to by uri.

Parameters:
uri
ForgeFile | URL
success
function([string]) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.read

iOS, Android

Reads and returns the entire contents of a file.

Parameters:
uri
ForgeFile | URL
options
TODO
success
function(string) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.temporaryFile

iOS, Android

Creates a unique temporary file.

Parameters:
prefix
string
suffix
string
success
function(string) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.temporaryDirectory

iOS, Android

Creates a unique temporary direcory.

Parameters:
prefix
string
suffix
string
success
function(string) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

forge.fs.uri

iOS, Android

Returns the URI which represents the path to a device location.

Parameters:
location
forge.fs.location
path
string (optional)
success
function([string]) callback to be invoked when no errors occur
error
function(error) called with details of any error which may occur

Valid device locations are:

  • forge.fs.location.private A writeable path which is not shared with any other apps on the device.
  • forge.fs.location.public A writeable path which is shared with other apps on the device.
  • forge.fs.location.temp A writeable path for temporary files.

forge.fs.write

iOS, Android

Reads and returns the entire contents of a file.

Parameters:
uri
ForgeFile | URL
data
string | <Buffer> | <Uint8Array>
options
TODO
success
function(string) callback to be invoked when no errors occur
error
function(error) 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.