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)

Properties

request: string

The full requested path given by the user

sources: object

The file sources which are available for browsing

activeSource: string

Track the active source tab which is being browsed

callback: Function

A callback function to trigger once a file has been selected

results: object

The latest set of results browsed from the server

type: string

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

field: HTMLElement

The target HTML element this file picker is bound to

button: HTMLElement

A button which controls the display of the picker UI

displayMode: string

The display mode of the FilePicker UI

extensions: string[]

The current set of file extensions which are being filtered upon

options: object

The options provided to this application upon initialization

_element: jQuery

An internal reference to the HTML element this application renders

position: object

Track the current position and dimensions of the Application UI

_dragDrop: DragDrop[]

DragDrop workflow handlers which are active for this Application

_tabs: Tabs[]

Tab navigation handlers which are active for this Application

_searchFilters: SearchFilter[]

SearchFilter handlers which are active for this Application

_minimized: boolean

Track whether the Application is currently minimized

_scrollPositions: object

Track the most recent scroll positions for any vertically scrolling containers

appId: number

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

_state: number

The current render state of the Application

See

_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

FILE_TYPES: string[] = ...

The allowed values for the type of this FilePicker instance.

LAST_BROWSED_DIRECTORY: string = ""

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

LAST_TILE_SIZE: number = null

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

LAST_DISPLAY_MODE: string = "list"

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

DISPLAY_MODES: string[] = ...

Enumerate the allowed FilePicker display modes

S3_BUCKETS: any[] = null

Cache the names of S3 buckets which can be used

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

  • get title(): string
  • Returns string

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

    Returns object

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

    Returns string

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

    Returns boolean

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

    Returns string

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

    Returns jQuery

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

    Returns string

  • 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

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

    Returns boolean

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

    Returns boolean

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

    Returns string

Methods

  • 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

  • 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;
      }>

    • 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;
        }

      • 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 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

      • 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

      • Parameters

        • event: any
        • tabs: any
        • active: any

        Returns void

      • Parameters

        • event: any

        Returns Promise<any>

      • Parameters

        • event: any
        • query: any
        • rgx: any
        • html: any

        Returns void

      • Parameters

        • ev: any

        Returns any

        Inherit Doc

      • 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

      • Bring the application to the top of the rendering stack

        Returns 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

      • 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

      • 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

      • Protected

        Handle changes to the tile size.

        Parameters

        • event: Event

          The triggering event.

        Returns 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

      • 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

      • 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

      • 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

      • Protected

        Render the outer application wrapper

        Returns Promise<jQuery>

        A promise resolving to the constructed jQuery object

      • 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

      • 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

      • Protected

        Callback actions which occur when a dragged element is over a drop target.

        Parameters

        • event: DragEvent

          The originating DragEvent

        Returns void

      • Protected

        Wait for any images present in the Application to load.

        Returns Promise<void>

        A Promise that resolves when all images have loaded.

      • Handle a click event to change the display mode of the File Picker

        Parameters

        • event: MouseEvent

          The triggering click event

        Returns 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

      • Handle user submission of the address bar to request an explicit target

        Parameters

        • event: KeyboardEvent

          The originating keydown event

        Returns Promise<any>

      • Handle user interaction with the favorites

        Parameters

        • event: PointerEvent

          The originating click event

        Returns Promise<void>

      • Handle requests from the IntersectionObserver to lazily load an image file

        Parameters

        • Rest ...args: any[]

        Returns any

      • Handle file or folder selection within the file picker

        Parameters

        • event: Event

          The originating click event

        Returns Promise<any>

      • Handle backwards navigation of the folder structure.

        Parameters

        • event: PointerEvent

          The triggering click event

        Returns 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>

      • Handle changes to the bucket selector

        Parameters

        • event: Event

          The S3 bucket select change event

        Returns Promise<any>

      • Handle file upload

        Parameters

        • ev: Event

          The file upload event

        Returns Promise<any>

      • 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>

      • 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>

      • 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

      • 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

      • 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>

      • 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>

      • 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

      • 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

      • 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

      • Get the valid file extensions for a given named file picker type

        Parameters

        • type: string

        Returns string[]

      • 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