Class FilePicker

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

Param: options

Options that configure the behavior of the FilePicker

Hierarchy (view full)

Application
- FilePicker

Index

Accessors

title source target canUpload id element template popOut rendered closing favorites defaultOptions uploadURL

Properties

request

request: string

The full requested path given by the user

sources

sources: object

The file sources which are available for browsing

activeSource

activeSource: string

Track the active source tab which is being browsed

callback

callback: Function

A callback function to trigger once a file has been selected

results

results: object

The latest set of results browsed from the server

type

type: string

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

field

field: HTMLElement

The target HTML element this file picker is bound to

button

button: HTMLElement

A button which controls the display of the picker UI

displayMode

displayMode: string

The display mode of the FilePicker UI

extensions

extensions: string[]

The current set of file extensions which are being filtered upon

options

options: object

The options provided to this application upon initialization

_element

_element: jQuery

An internal reference to the HTML element this application renders

position

position: object

Track the current position and dimensions of the Application UI

_dragDrop

_dragDrop: DragDrop[]

DragDrop workflow handlers which are active for this Application

_tabs

_tabs: Tabs[]

Tab navigation handlers which are active for this Application

_searchFilters

_searchFilters: SearchFilter[]

SearchFilter handlers which are active for this Application

_minimized

_minimized: boolean

Track whether the Application is currently minimized

_scrollPositions

_scrollPositions: object

Track the most recent scroll positions for any vertically scrolling containers

appId

appId: number

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

`Protected` _state

_state: number

The current render state of the Application

See

`Protected` _priorState

_priorState: number

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

See

`Static` FILE_TYPES

FILE_TYPES: string[] = ...

The allowed values for the type of this FilePicker instance.

`Static` LAST_BROWSED_DIRECTORY

LAST_BROWSED_DIRECTORY: string = ""

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

`Static` LAST_TILE_SIZE

LAST_TILE_SIZE: number = null

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

`Static` LAST_DISPLAY_MODE

LAST_DISPLAY_MODE: string = "list"

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

`Static` DISPLAY_MODES

DISPLAY_MODES: string[] = ...

Enumerate the allowed FilePicker display modes

`Static` S3_BUCKETS

S3_BUCKETS: any[] = null

Cache the names of S3 buckets which can be used

`Static` RENDER_STATES

RENDER_STATES: Readonly<{
    ERROR: -3;
    CLOSING: -2;
    CLOSED: -1;
    NONE: 0;
    RENDERING: 1;
    RENDERED: 2;
}> = ...

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

Type declaration

ERROR: -3
CLOSING: -2
CLOSED: -1
NONE: 0
RENDERING: 1
RENDERED: 2

Accessors

title

get title(): string
Returns string
Overrides Application.title

source

get source(): object
Return the source object for the currently active source

Returns object

target

get target(): string
Return the target directory for the currently active source

Returns string

canUpload

get canUpload(): boolean
Return a flag for whether the current user is able to upload file content

Returns boolean

id

get id(): string
Return the CSS application ID which uniquely references this UI element

Returns string
Inherited from Application.id

element

get element(): jQuery
Return the active application element, if it currently exists in the DOM

Returns jQuery
Inherited from Application.element

template

get template(): string
The path to the HTML template file which should be used to render the inner content of the app

Returns string
Inherited from Application.template

popOut

get popOut(): boolean
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

Returns boolean
Inherited from Application.popOut

rendered

get rendered(): boolean
Return a flag for whether the Application instance is currently rendered

Returns boolean
Inherited from Application.rendered

closing

get closing(): boolean
Whether the Application is currently closing.

Returns boolean
Inherited from Application.closing

`Static` favorites

get favorites(): Record<string, FavoriteFolder>
Get favorite folders for quick access

Returns Record<string, FavoriteFolder>

`Static` defaultOptions

get defaultOptions(): ApplicationOptions
Returns ApplicationOptions
Overrides Application.defaultOptions

`Static` uploadURL

get uploadURL(): string
Return the upload URL to which the FilePicker should post uploaded files

Returns string

Methods

_inferCurrentDirectory

_inferCurrentDirectory(target): string[]
Given a current file path, determine the directory it belongs to
Parameters
- target: string
  The currently requested target path
Returns string[]
An array of the inferred source and target directory path

getData

getData(options?): Promise<{
    bucket: any;
    buckets: any;
    canGoBack: boolean;
    canUpload: boolean;
    canSelect: boolean;
    cssClass: string;
    dirs: any;
    displayMode: string;
    extensions: string[];
    files: any;
    isS3: boolean;
    noResults: boolean;
    selected: string;
    source: object;
    sources: object;
    target: string;
    tileSize: any;
    user: User;
    submitText: string;
    favorites: any;
}>
Parameters
- options: {} = {}
Returns Promise<{
    bucket: any;
    buckets: any;
    canGoBack: boolean;
    canUpload: boolean;
    canSelect: boolean;
    cssClass: string;
    dirs: any;
    displayMode: string;
    extensions: string[];
    files: any;
    isS3: boolean;
    noResults: boolean;
    selected: string;
    source: object;
    sources: object;
    target: string;
    tileSize: any;
    user: User;
    submitText: string;
    favorites: any;
}>
Overrides Application.getData

setPosition

setPosition(pos?): void | {
    left: number;
    top: number;
    width: number;
    height: number;
    scale: number;
}
Set the application position and store its new location. Returns the updated position object for the application containing the new values.
Parameters
- pos: {} = {}
  Positional data
Returns void | {
    left: number;
    top: number;
    width: number;
    height: number;
    scale: number;
}
Overrides Application.setPosition

browse

browse(target?, options?): Promise<any>
Browse to a specific location for this FilePicker instance
Parameters
- Optional target: string
  The target within the currently active source location.
- Optional options: object = {}
  Browsing options
Returns Promise<any>

render

render(force, options): any
Render the Application by evaluating it's HTML template against the object of data provided by the getData method If the Application is rendered as a pop-out window, wrap the contained HTML in an outer frame with window controls
Parameters
- force: any
  Add the rendered application to the DOM if it is not already present. If false, the Application will only be re-rendered if it is already present.
- options: any
  Additional rendering options which are applied to customize the way that the Application is rendered in the DOM.
Returns any
The rendered Application instance

Overrides Application.render

activateListeners

activateListeners(html): void
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
- html: any
Returns void
Overrides Application.activateListeners

_onChangeTab

_onChangeTab(event, tabs, active): void
Parameters
- event: any
- tabs: any
- active: any
Returns void
Overrides Application._onChangeTab

_canDragStart

_canDragStart(selector): boolean
Parameters
- selector: any
Returns boolean
Overrides Application._canDragStart

_canDragDrop

_canDragDrop(selector): boolean
Parameters
- selector: any
Returns boolean
Overrides Application._canDragDrop

_onDragStart

_onDragStart(event): void
Parameters
- event: any
Returns void
Overrides Application._onDragStart

_onDrop

_onDrop(event): Promise<any>
Parameters
- event: any
Returns Promise<any>
Overrides Application._onDrop

_onSearchFilter

_onSearchFilter(event, query, rgx, html): void
Parameters
- event: any
- query: any
- rgx: any
- html: any
Returns void
Overrides Application._onSearchFilter

_onSubmit

_onSubmit(ev): any
Parameters
- ev: any
Returns any
Inherit Doc

activateTab

activateTab(tabName, options?): void
Change the currently active tab
Parameters
- tabName: string
  The target tab name to switch to
- options: {
  group: string;
  triggerCallback: boolean;
  } = {}
  Options which configure changing the tab
  - group: string
    A specific named tab group, useful if multiple sets of tabs are present
  - triggerCallback: boolean
    Whether to trigger tab-change callback functions
Returns void
Inherited from Application.activateTab

bringToTop

bringToTop(): void
Bring the application to the top of the rendering stack

Returns void
Inherited from Application.bringToTop

close

close(options?): Promise<void>
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
Parameters
- Optional options: object = {}
  Options which affect how the Application is closed
Returns Promise<void>
A Promise which resolves once the application is closed

Fires
closeApplication

Inherited from Application.close

minimize

minimize(): Promise<void>
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 Promise<void>
A Promise which resolves once the minimization action has completed

Inherited from Application.minimize

maximize

maximize(): Promise<void>
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 Promise<void>
A Promise which resolves once the maximization action has completed

Inherited from Application.maximize

`Protected` _onChangeTileSize

_onChangeTileSize(event): void
Protected
Handle changes to the tile size.
Parameters
- event: Event
  The triggering event.
Returns void

`Protected` _render

_render(force?, options?): Promise<void>
Protected
An asynchronous inner function which handles the rendering of the Application
Parameters
- force: boolean = false
  Render and display the application even if it is not currently displayed.
- options: object = {}
  Additional options which update the current values of the Application#options object
Returns Promise<void>
A Promise that resolves to the Application once rendering is complete

Fires
renderApplication

Inherited from Application._render

`Protected` _callHooks

_callHooks(hookName, ...hookArgs): void
Protected Internal
Call all hooks for all applications in the inheritance chain.
Parameters
- hookName: string | ((className) => string)
  The hook being triggered, which formatted with the Application class name
- Rest ...hookArgs: any[]
  The arguments passed to the hook calls
Returns void
Inherited from Application._callHooks

`Protected` _saveScrollPositions

_saveScrollPositions(html): void
Protected
Persist the scroll positions of containers within the app before re-rendering the content
Parameters
- html: jQuery
  The HTML object being traversed
Returns void
Inherited from Application._saveScrollPositions

`Protected` _restoreScrollPositions

_restoreScrollPositions(html): void
Protected
Restore the scroll positions of containers within the app after re-rendering the content
Parameters
- html: jQuery
  The HTML object being traversed
Returns void
Inherited from Application._restoreScrollPositions

`Protected` _renderOuter

_renderOuter(): Promise<jQuery>
Protected
Render the outer application wrapper

Returns Promise<jQuery>
A promise resolving to the constructed jQuery object

Inherited from Application._renderOuter

`Protected` _getHeaderButtons

_getHeaderButtons(): ApplicationHeaderButton[]
Protected
Specify the set of config buttons which should appear in the Application header. Buttons should be returned as an Array of objects. The header buttons which are added to the application can be modified by the getApplicationHeaderButtons hook.

Returns ApplicationHeaderButton[]
Fires
getApplicationHeaderButtons

Inherited from Application._getHeaderButtons

`Protected` _activateCoreListeners

_activateCoreListeners(html): void
Protected
Activate required listeners which must be enabled on every Application. These are internal interactions which should not be overridden by downstream subclasses.
Parameters
- html: jQuery
Returns void
Inherited from Application._activateCoreListeners

`Protected` _onDragOver

_onDragOver(event): void
Protected
Callback actions which occur when a dragged element is over a drop target.
Parameters
- event: DragEvent
  The originating DragEvent
Returns void
Inherited from Application._onDragOver

`Protected` _waitForImages

_waitForImages(): Promise<void>
Protected
Wait for any images present in the Application to load.

Returns Promise<void>
A Promise that resolves when all images have loaded.

Inherited from Application._waitForImages

`Private` #onChangeDisplayMode

#onChangeDisplayMode(event): void
Handle a click event to change the display mode of the File Picker
Parameters
- event: MouseEvent
  The triggering click event
Returns void

`Private` #validateExtension

#validateExtension(name): void
Validate that the extension of the uploaded file is permitted for this file-picker instance. This is an initial client-side test, the MIME type will be further checked by the server.
Parameters
- name: string
  The file name attempted for upload
Returns void

`Private` #onRequestTarget

#onRequestTarget(event): Promise<any>
Handle user submission of the address bar to request an explicit target
Parameters
- event: KeyboardEvent
  The originating keydown event
Returns Promise<any>

`Private` #onClickFavorite

#onClickFavorite(event): Promise<void>
Handle user interaction with the favorites
Parameters
- event: PointerEvent
  The originating click event
Returns Promise<void>

`Private` #onLazyLoadImages

#onLazyLoadImages(...args): any
Handle requests from the IntersectionObserver to lazily load an image file
Parameters
- Rest ...args: any[]
Returns any

`Private` #onPick

#onPick(event): Promise<any>
Handle file or folder selection within the file picker
Parameters
- event: Event
  The originating click event
Returns Promise<any>

`Private` #onClickDirectoryControl

#onClickDirectoryControl(event): any
Handle backwards navigation of the folder structure.
Parameters
- event: PointerEvent
  The triggering click event
Returns any

`Private` #createDirectoryDialog

#createDirectoryDialog(source): Promise<any>
Present the user with a dialog to create a subdirectory within their currently browsed file storage location.
Parameters
- source: object
  The data source being browsed
Returns Promise<any>

`Private` #onChangeBucket

#onChangeBucket(event): Promise<any>
Handle changes to the bucket selector
Parameters
- event: Event
  The S3 bucket select change event
Returns Promise<any>

`Private` #onUpload

#onUpload(ev): Promise<any>
Handle file upload
Parameters
- ev: Event
  The file upload event
Returns Promise<any>

`Static` setFavorite

setFavorite(source, path): Promise<void>
Add the given path for the source to the favorites
Parameters
- source: string
  The source of the folder (e.g. "data", "public")
- path: string
  The path to a folder
Returns Promise<void>

`Static` removeFavorite

removeFavorite(source, path): Promise<void>
Remove the given path from the favorites
Parameters
- source: string
  The source of the folder (e.g. "data", "public")
- path: string
  The path to a folder
Returns Promise<void>

`Static` matchS3URL

matchS3URL(url): RegExpMatchArray
Test a URL to see if it matches a well known s3 key pattern
Parameters
- url: string
  An input URL to test
Returns RegExpMatchArray
A regular expression match

`Static` browse

browse(source, target, options?): Promise<any>
Browse files for a certain directory location
Parameters
- source: string
  The source location in which to browse. See FilePicker#sources for details
- target: string
  The target within the source location
- options: {
      bucket: string;
      extensions: string[];
      wildcard: boolean;
  } = {}
  Optional arguments
  - bucket: string
    A bucket within which to search if using the S3 source
  - extensions: string[]
    An Array of file extensions to filter on
  - wildcard: boolean
    The requested dir represents a wildcard path
Returns Promise<any>
A Promise which resolves to the directories and files contained in the location

`Static` configurePath

configurePath(source, target, options?): Promise<object>
Configure metadata settings regarding a certain file system path
Parameters
- 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 Promise<object>

`Static` createDirectory

createDirectory(source, target, options?): Promise<object>
Create a subdirectory within a given source. The requested subdirectory path must not already exist.
Parameters
- 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 Promise<object>

`Static` upload

upload(source, path, file, body?, options?): Promise<object>
Dispatch a POST request to the server containing a directory path and a file to upload
Parameters
- source: string
  The data source to which the file should be uploaded
- path: string
  The destination path
- file: File
  The File object to upload
- Optional body: object = {}
  Additional file upload options sent in the POST body
- Optional options: {
  notify: boolean;
  } = {}
  Additional options to configure how the method behaves
  - notify: boolean
    Display a UI notification when the upload is processed
Returns Promise<object>
The response object

`Static` uploadPersistent

uploadPersistent(packageId, path, file, body?, options?): Promise<object>
A convenience function that uploads a file to a given package's persistent /storage/ directory
Parameters
- packageId: string
  The id of the package to which the file should be uploaded. Only supports Systems and Modules.
- path: string
  The relative destination path in the package's storage directory
- file: File
  The File object to upload
- Optional body: object = {}
  Additional file upload options sent in the POST body
- Optional options: {
  notify: boolean;
  } = {}
  Additional options to configure how the method behaves
  - notify: boolean
    Display a UI notification when the upload is processed
Returns Promise<object>
The response object

`Static` fromButton

fromButton(button): FilePicker
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
- button: HTMLButtonElement
  The button element
Returns FilePicker

`Static` `Private` #getExtensions

#getExtensions(type): string[]
Get the valid file extensions for a given named file picker type
Parameters
- type: string
Returns string[]

`Static` `Private` #manageFiles

#manageFiles(data, options): Promise<object>
General dispatcher method to submit file management commands to the server
Parameters
- data: object
  Request data dispatched to the server
- options: object
  Options dispatched to the server
Returns Promise<object>
The server response

Class FilePicker

Param: options

Hierarchy (view full)

Index

Properties

Accessors

Methods

Properties

request

sources

activeSource

callback

results

type

field

button

displayMode

extensions

options

_element

position

_dragDrop

_tabs

_searchFilters

_minimized

_scrollPositions

appId

Protected _state

See

Protected _priorState

See

Static FILE_TYPES

Static LAST_BROWSED_DIRECTORY

Static LAST_TILE_SIZE

Static LAST_DISPLAY_MODE

Static DISPLAY_MODES

Static S3_BUCKETS

Static RENDER_STATES

Type declaration

ERROR: -3

CLOSING: -2

CLOSED: -1

NONE: 0

RENDERING: 1

RENDERED: 2

Accessors

title

Returns string

source

Returns object

target

Returns string

canUpload

Returns boolean

id

Returns string

element

Returns jQuery

template

Returns string

popOut

Returns boolean

rendered

Returns boolean

closing

Returns boolean

Static favorites

Returns Record<string, FavoriteFolder>

Static defaultOptions

Returns ApplicationOptions

Static uploadURL

Returns string

Methods

_inferCurrentDirectory

Parameters

Returns string[]

getData

Parameters

setPosition

Parameters

`Protected` _state

`Protected` _priorState

`Static` FILE_TYPES

`Static` LAST_BROWSED_DIRECTORY

`Static` LAST_TILE_SIZE

`Static` LAST_DISPLAY_MODE

`Static` DISPLAY_MODES

`Static` S3_BUCKETS

`Static` RENDER_STATES

`Static` favorites

`Static` defaultOptions

`Static` uploadURL

Returns void | {
left: number;
top: number;
width: number;
height: number;
scale: number;
}

`Protected` _onChangeTileSize

`Protected` _render

`Protected` _callHooks

`Protected` _saveScrollPositions

`Protected` _restoreScrollPositions

`Protected` _renderOuter

`Protected` _getHeaderButtons

`Protected` _activateCoreListeners