FilePicker

FilePicker

The FilePicker application renders contents of the server-side public directory This app allows for navigating and uploading files to the public path

Constructor

new FilePicker(optionsopt)

Parameters:
Name Type Attributes Default Description
options FilePickerOptions <optional>
 {}

Options that configure the behavior of the FilePicker

Extends

Members

(static) defaultOptions

(static) uploadURL

Return the upload URL to which the FilePicker should post uploaded files

_dragDrop :Array.<DragDrop>

Overrides:

DragDrop workflow handlers which are active for this Application

Type:

_element :jQuery

Overrides:

An internal reference to the HTML element this application renders

Type:
  • jQuery

_minimized :boolean

Overrides:

Track whether the Application is currently minimized

Type:
  • boolean

(protected) _priorState :number

Overrides:
See:
  • {Application.RENDER_STATES}

The prior render state of this Application. This allows for rendering logic to understand if the application is being rendered for the first time.

Type:
  • number

_scrollPositions :Object|null

Overrides:

Track the most recent scroll positions for any vertically scrolling containers

Type:
  • Object | null

_searchFilters :Array.<SearchFilter>

Overrides:

SearchFilter handlers which are active for this Application

Type:

(protected) _state :number

Overrides:
See:
  • {Application.RENDER_STATES}

The current render state of the Application

Type:
  • number

_tabs :Array.<Tabs>

Overrides:

Tab navigation handlers which are active for this Application

Type:

activeSource :string

Track the active source tab which is being browsed

Type:
  • string

appId :number

Overrides:

The application ID is a unique incrementing integer which is used to identify every application window drawn by the VTT

Type:
  • number

button :HTMLElement

A button which controls the display of the picker UI

Type:
  • HTMLElement

callback :function

A callback function to trigger once a file has been selected

Type:
  • function

canUpload

Return a flag for whether the current user is able to upload file content

DISPLAY_MODES :Array.<string>

Enumerate the allowed FilePicker display modes

Type:

displayMode :string

The display mode of the FilePicker UI

Type:
  • string

element :jQuery|HTMLElement

Overrides:

Return the active application element, if it currently exists in the DOM

Type:
  • jQuery | HTMLElement

extensions :Array.<string>

The current set of file extensions which are being filtered upon

Type:

field :HTMLElement

The target HTML element this file picker is bound to

Type:
  • HTMLElement

id :string

Overrides:

Return the CSS application ID which uniquely references this UI element

Type:
  • string

LAST_BROWSED_DIRECTORY :string

Record the last-browsed directory path so that re-opening a different FilePicker instance uses the same target

Type:
  • string

LAST_DISPLAY_MODE :string

Record the last-configured display mode so that re-opening a different FilePicker instance uses the same mode.

Type:
  • string

LAST_TILE_SIZE :number|null

Record the last-configured tile size which can automatically be applied to new FilePicker instances

Type:
  • number | null

options :Object

Overrides:

The options provided to this application upon initialization

Type:
  • Object

popOut :boolean

Overrides:

Control the rendering style of the application. If popOut is true, the application is rendered in its own wrapper window, otherwise only the inner app content is rendered

Type:
  • boolean

position :Object

Overrides:

Track the current position and dimensions of the Application UI

Type:
  • Object

RENDER_STATES :number

Overrides:

The sequence of rendering states that track the Application life-cycle.

Type:
  • number

rendered :boolean

Overrides:

Return a flag for whether the Application instance is currently rendered

Type:
  • boolean

request :string

The full requested path given by the user

Type:
  • string

results :Object

The latest set of results browsed from the server

Type:
  • Object

S3_BUCKETS :Array|null

Cache the names of S3 buckets which can be used

Type:

source

Return the source object for the currently active source

sources :Object

The file sources which are available for browsing

Type:
  • Object

target

Return the target directory for the currently active source

template :string

Overrides:

The path to the HTML template file which should be used to render the inner content of the app

Type:
  • string

title :string

Overrides:

An Application window should define its own title definition logic which may be dynamic depending on its data

Type:
  • string

type :string

The general file type which controls the set of extensions which will be accepted

Type:
  • string

Methods

(async, static) browse(source, target, options) → {Promise}

Browse files for a certain directory location

Parameters:
Name Type Description
source string

The source location in which to browse. See FilePicker#sources for details
target string

The target within the source location
options object

Optional arguments

Properties
Name Type Attributes Description
bucket string <optional>

A bucket within which to search if using the S3 source
extensions Array.<string> <optional>

An Array of file extensions to filter on
wildcard boolean <optional>

The requested dir represents a wildcard path
Returns:

A Promise which resolves to the directories and files contained in the location

Type
Promise

(async, static) configurePath(source, target, options) → {Promise.<Object>}

Configure metadata settings regarding a certain file system path

Parameters:
Name Type Description
source string

The source location in which to browse. See FilePicker#sources for details
target string

The target within the source location
options Object

Optional arguments which modify the request
Returns:
Type
Promise.<Object>

(async, static) createDirectory(source, target, options) → {Promise.<Object>}

Create a subdirectory within a given source. The requested subdirectory path must not already exist.

Parameters:
Name Type Description
source string

The source location in which to browse. See FilePicker#sources for details
target string

The target within the source location
options Object

Optional arguments which modify the request
Returns:
Type
Promise.<Object>

(static) fromButton(button)

Bind the file picker to a new target field. Assumes the user will provide a HTMLButtonElement which has the data-target and data-type attributes The data-target attribute should provide the name of the input field which should receive the selected file The data-type attribute is a string in ["image", "audio"] which sets the file extensions which will be accepted

Parameters:
Name Type Description
button HTMLButtonElement

The button element

(static) matchS3URL(url) → {RegExpMatchArray|null}

Test a URL to see if it matches a well known s3 key pattern

Parameters:
Name Type Description
url string

An input URL to test
Returns:

A regular expression match

Type
RegExpMatchArray | null

(static) parseS3URL(key) → {Object}

Parse a s3 key to learn the bucket and the key prefix used for the request

Parameters:
Name Type Description
key string

A fully qualified key name or prefix path
Returns:
Type
Object

(async, static) upload(source, path, file, bodyopt, optionsopt) → {Promise.<Object>}

Dispatch a POST request to the server containing a directory path and a file to upload

Parameters:
Name Type Attributes Default Description
source string

The data source to which the file should be uploaded
path string

The destination path
file File

The File object to upload
body object <optional>
 {}

Additional file upload options sent in the POST body
options object <optional>

Additional options to configure how the method behaves

Properties
Name Type Attributes Default Description
notify boolean <optional>
 true

Display a UI notification when the upload is processed
Returns:

The response object

Type
Promise.<Object>

(protected) _activateCoreListeners(html)

Overrides:

Activate required listeners which must be enabled on every Application. These are internal interactions which should not be overridden by downstream subclasses.

Parameters:
Name Type Description
html jQuery

_inferCurrentDirectory(target) → {Array.<string>}

Given a current file path, determine the directory it belongs to

Parameters:
Name Type Description
target string

The currently requested target path
Returns:

An array of the inferred source and target directory path

Type
Array.<string>

_onSubmit()

(async, protected) _render(force, options) → {Promise.<void>}

Overrides:

An asynchronous inner function which handles the rendering of the Application

Parameters:
Name Type Default Description
force boolean false

Render and display the application even if it is not currently displayed.
options Object

New Application options which update the current values of the Application#options object
Returns:

A Promise that resolves to the Application once rendering is complete

Type
Promise.<void>

activateListeners(html)

Overrides:

After rendering, activate event listeners which provide interactivity for the Application. This is where user-defined Application subclasses should attach their event-handling logic.

Parameters:
Name Type Description
html jQuery

bringToTop()

Overrides:

Bring the application to the top of the rendering stack

(async) browse(targetopt, optionsopt)

Browse to a specific location for this FilePicker instance

Parameters:
Name Type Attributes Description
target string <optional>

The target within the currently active source location.
options Object <optional>

Browsing options

(async) close() → {Promise.<void>}

Overrides:

Close the application and un-register references to it within UI mappings This function returns a Promise which resolves once the window closing animation concludes

Returns:

A Promise which resolves once the application is closed

Type
Promise.<void>

(async) getData() → {Object|Promise}

Overrides:

An application should define the data object used to render its template. This function may either return an Object directly, or a Promise which resolves to an Object If undefined, the default implementation will return an empty object allowing only for rendering of static HTML

Returns:
Type
Object | Promise

(async) maximize() → {Promise.<void>}

Overrides:

Maximize the pop-out window, expanding it to its original size Take no action for applications which are not of the pop-out variety or are already maximized

Returns:

A Promise which resolves once the maximization action has completed

Type
Promise.<void>

(async) minimize() → {Promise.<void>}

Overrides:

Minimize the pop-out window, collapsing it to a small tab Take no action for applications which are not of the pop-out variety or apps which are already minimized

Returns:

A Promise which resolves once the minimization action has completed

Type
Promise.<void>

render()

Overrides:

Additional actions performed when the file-picker UI is rendered

setPosition(left, top, width, height, scale) → {Object}

Overrides:

Set the application position and store it's new location.

Parameters:
Name Type Description
left number | null

The left offset position in pixels
top number | null

The top offset position in pixels
width number | null

The application width in pixels
height number | string | null

The application height in pixels
scale number | null

The application scale as a numeric factor where 1.0 is default
Returns:

The updated position object for the application containing the new values

Type
Object