File interface

A JavaScript object implementing the File interface represents a file stored and managed by the platform’s file store.

Construction

Use O.file().

Interface

property digest

The digest of the file, as a hex encoded String.

property fileSize

The size of the file, in bytes, as a number.

property mimeType

The MIME type of the file, as set by the browser when the file was originally uploaded. Note that some MIME types are standardised as browsers tend to be a bit inconsistent.

property filename

The filename of the file, as set by the browser when the file was originally uploaded.

Note that if a file is uploaded again, it’s still only stored once, and the original filename isn’t changed. Users can use a different filename by using a FileIdentifier.

property basename

The filename of the file, without the file extension.

property createdAt

The Date when the file was originally uploaded for the first time.

function identifier()

Create a new FileIdentifier which refers to this file, with a random trackingId.

function secret

The file’s secret, as a String. You must always check the secret with the checkSecret() function.

function checkSecret(secret)

Compare the given secret with the file’s secret using a timing-attack resistant comparison algorithm. If the secret does not match, an exception is thrown.

function readAsString(charsetName)

Read the contents of the file, interpreted as a string in the given character set, eg "UTF-8".

Use this function with care, checking the fileSize property before calling it, as it is very easy to accidently run out of memory.

property properties

A JavaScript Object, as a dictionary, containing additional properties of the file. These may not be available either because the file has not been processed yet, processing encountered an error, or the properties are not applicable to that file type.

numberOfPages: Number of pages in the file.

dimensions: Physical dimensions of the document represented by the file, with keys width, height and units.

thumbnail: The size of the thumbnail, if available, with keys width, height and mimeType.

function url(options)

Return a URL which can be used to download this file. See below for the optional options argument.

function toHTML(options)

Return some HTML which can be included in a web page. See below for the optional options argument.

Options

Property Description Default
transform Transform to be applied to the file null
asFullURL Whether to include the hostname in the URL false
authenticationSignature Sign the URL to bypass the usual file download authentication. Note that this signature is only valid for the current user session. false
linkToDownload When generating HTML, include a link to download the file. false
forceDownload Set the Content-Disposition to attachment to force the browser to download the file, rather than displaying it. false