Working with files

Forge modules will often want to consume or produce files (or both). To make this easy Forge has a ForgeFile object which can be passed efficiently between modules and between native and JavaScript code.

JavaScript

ForgeFile objects can be represented as simple JavaScript objects. These objects must contain a uri which references an actual file that either Forge or a loaded module will be able to resolve at a later point. They should also contain a name and a mimeType if sensible values for these are known. Some file objects will contain additional properties such as width and height which may be used when processing the file.

The file module has a number of methods which accept file objects.

For information on testing with files see Testing your module.

Android

Receiving from JavaScript

When receiving a file from JavaScript it will be of type JsonObject, this can be passed into the ForgeFile constructor to access various helper functions for the file. For example:

ForgeFile file = new ForgeFile(ForgeApp.getActivity(), task.params.get("file"));
byte[] fileData = null;
try {
    fileData = file.data();
} catch (IOException e) {
    // handle properly
}

Further details on the ForgeFile class in Android can be found in the API docs: ForgeFile.

Returning to JavaScript

To return a file to JavaScript (which can then be used with other modules, such as forge.request.ajax) a JsonObject with the appropriate properties must be constructed and returned. For example:

JsonObject file = new JsonObject();
file.addProperty("uri", "file:///data/path/to/file");
task.success(file);

iOS

Receiving from JavaScript

When receiving a file from JavaScript it will be of type NSDictionary, this can be passed into the ForgeFile constructor to access various helper fuctions for the file. For example:

ForgeFile* file = [[ForgeFile alloc] initWithFile:[task.params objectForKey:@"file"]];
NSString* fileURL = [file url];

Further details on the ForgeFile class in iOS can be found in the API docs: ForgeFile.

Returning to JavaScript

To return a file to JavaScript (which can then be used with other modules, such as forge.request.ajax) an NSDictionary with the appropriate properties must be constructed and returned. For example:

NSDictionary* file = @{@"uri": @"/path/to/file"};
[task success:file];