Element: <oj-file-picker>

Oracle® JavaScript Extension Toolkit (JET)
8.0.0
F18189-01

Signature:

class ojFilePicker

QuickNav

Slots

Attributes

Events

Methods

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.



Version:
  • 8.0.0
Since:
  • 4.0.0
Module:
  • ojfilepicker

Module usage

See JET Module Loading for an overview of module usage within JET.

Typescript Import Format
//To typecheck the element APIs, import as below.
import {ojFilePicker} from "ojs/ojfilepicker";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojfilepicker";

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.


JET FilePicker

Description:

By default the file picker shows a clickable dropzone for selecting files for upload. However, it can be replaced with any clickable element like a button. After the files are selected, the FilePicker fires a "select" event with the selected files. Application has to specify the listener in order to do the actual upload. The types of files accepted are controlled by the accept attribute. Additional custom validation can be done through the ojBeforeSelect event.


<oj-file-picker on-oj-select='[[listener]]' accept='["image/*", "video/*"]'>
</oj-file-picker>

Touch End User Information

Target Gesture Action
Clickable element Tap Launch the browser's file picker.

Keyboard End User Information

Target Key Action
Clickable element Enter Launch the browser's file picker.

Styling

The following CSS classes can be applied by the page author as needed.

Class Description
oj-filepicker-custom Apply to a custom file picker if the entire dropzone is replaced with another clickable element like button or menu item. Note that the oj-filepicker-custom class doesn't have to be specified in order to change the dropzone text.
oj-filepicker-dropzone When using custom trigger slot content, the oj-filepicker-dropzone class can be applied to an element where drag and drop feedback should be displayed. If not specified, feedback will be displayed over the entire slot content. Note that this class only controls the visual rendering of drag and drop feedback; the entire slot content region will react to drag and drop interactions.
oj-filepicker-text When using custom trigger slot content, the oj-filepicker-text class can be used to apply the same text styling that is used by the default trigger slot content.

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.

Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

trigger

The trigger slot is set on the custom content of the file picker.

Attributes

accept :Array.<string>|null

An array of strings of allowed MIME types or file extensions that can be uploaded; this is unlike the accept attribute of the html <input> element that accepts a simple comma-delimited string. If not specified, accept all file types.

Note: If accept is specified, files with empty string type will be rejected if no match found in the "accept" value.

Default Value:
  • null
Names
Item Name
Property accept
Property change event acceptChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-accept-changed

disabled :boolean

Disables the filepicker if set to true.
Default Value:
  • false
Names
Item Name
Property disabled
Property change event disabledChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-disabled-changed

select-on :"auto"|"click"|"drop"|"clickAndDrop"

The type of event to select the files.
Supported Values:
Value Description
"auto" either click or drag and drop to select the files
"click" click to select the files
"clickAndDrop" either click or drag and drop to select the files
"drop" drag and drop the files
Default Value:
  • "auto"
Names
Item Name
Property selectOn
Property change event selectOnChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-select-on-changed

selection-mode :"multiple"|"single"

Whether to allow single or multiple file selection.
Supported Values:
Value Description
"multiple" multiple file selection
"single" single file selection
Default Value:
  • "multiple"
Names
Item Name
Property selectionMode
Property change event selectionModeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selection-mode-changed

Events

ojBeforeSelect

Triggered before files are selected to allow for custom validation
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
files FileList The selected files
accept (acceptPromise:Promise<void>) => void To perform custom validation, the application should call the accept function and pass in a Promise. The Promise should be resolved to accept the current selection, otherwise it should be rejected with an Array<oj.ojMessage.Message> describing the reasons for rejection.

ojInvalidSelect

Triggered when invalid files are selected. This event provides the application with a list of messages that should be displayed to give the user feedback about the problems with their selection. This feedback can be safely cleared when a subsequent ojBeforeSelect, ojInvalidSelect, or ojSelect event is received. Additionally the event.detail.until property may be populated with a Promise to provide short-term feedback during a user interaction (typically drag and drop); the feedback should be cleared upon resolution of this Promise.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
messages Array.<oj.ojMessage.Message> Messages that should be displayed to the user (e.g. in an oj-messages component) describing invalid files.
until Promise.<void> | null This property may be populated with a Promise to provide short-term feedback during a user interaction (typically drag and drop); the feedback should be cleared upon the resolution of this Promise.

ojSelect

Triggered after the files are selected
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
files FileList The files that were just selected.

Methods

getProperty(property) : {any}

Retrieves a value for a property or a single subproperty for complex properties.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void