Element: <oj-file-picker>

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 4.0.0
Module:
  • ojfilepicker

Note: This component is in maintenance mode. Suggested alternative: <oj-c-file-picker>. For help updating an existing application, see the migration section.

QuickNav

Slots

Attributes

Events

Methods

Other Topics


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>

Migration

Read about current Core Pack limitations to decide when to migrate.
Please make note of the following:

To migrate from oj-file-picker to oj-c-file-picker, you need to revise the import statement and references to oj-file-picker in your app. Please note the changes between the two components below.
Role attribute

If aria-label is set on the component, the role attribute will be set internally. The application should no longer populate the role attribute.

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.


Usage

Signature:

interface FilePickerElement

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

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

For additional information visit:

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.


Styling Classes

.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.
Deprecated:
Since Description
9.0.0 oj-filepicker-custom class has been deprecated. Class is no longer needed.
.oj-filepicker-dropzone
Apply to the dropzone of the file picker.
Deprecated:
Since Description
9.0.0 oj-filepicker-dropzone class has been deprecated. Class is no longer needed.
.oj-filepicker-text
Apply to the dropzone text of the file picker.
Deprecated:
Since Description
9.0.0 oj-filepicker-text class has been deprecated. Class is no longer needed.

CSS Variables

See JET CSS Variables for additional details.
Name Type Description
--oj-file-picker-border-color <color> File picker border color
--oj-file-picker-border-width <length> File picker border width
--oj-file-picker-border-radius <length> | <percentage> File picker border radius

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 used to replace the default content of the file picker. File picker will add click and drag and drop listeners to the slot content. The application is responsible for setting the tabindex attribute for keyboard accessibility.

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. Due to browser/OS differences, you may have to specify multiple values for the same value type. For example, for a CSV file, you might need to specify 'text/csv', '.csv', 'application/vnd.ms-excel', 'text/comma-separated-values' and others depending on your target browser/OS.

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

capture :"user"|"environment"|"implementation"|"none"

Specifies the preferred facing mode for the device's media capture mechanism; This is most often used to provide direct camera access on mobile devices. Note that the accept attribute must be specified and have an associated capture control type (e.g.["image/*"]) for the capture attribute to take effect. Support may vary by browser.
Supported Values:
Value Description
user Specifies user-facing as the preferred mode
environment Specifies environment-facing as the preferred mode
implementation Specifies an implementation-specific default as the preferred facing mode
none No capture mechanism is used
Default Value:
  • 'none'
Names
Item Name
Property capture
Property change event captureChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-capture-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

primary-text :string | (() => string)

The primary text for the default file picker. It is either a string or a formatting function that returns the string to be displayed.
Names
Item Name
Property primaryText
Property change event primaryTextChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-primary-text-changed

secondary-text :string | ((fileOptions:{ selectionMode: "multiple"|"single" }) => string)

The secondary text for the default file picker. It is either a string or a formatting function that returns the string to be displayed. The formatting function takes in a property object that contains the selection mode of the filepicker.
Names
Item Name
Property secondaryText
Property change event secondaryTextChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-secondary-text-changed

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

The type of event to select the files.
Deprecated:
Since Description
13.1.0 Main use case was to turn off drag and drop for button filepicker. The current recommendation for that use case is to use ojfilepickerutils with an oj-button.
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. To reject the selected files, the application can either call event.preventDefault() or pass a rejected Promise to the accept detail property. The latter approach is recommended because this allows the application to send a message stating why the files were rejected.
Properties:

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

Name Type Description
accept (acceptPromise:Promise<void>) => void This method can be called with an application-created Promise to cancel this event asynchronously. The Promise should be resolved or rejected to accept or cancel the event, respectively.
files FileList The selected files

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