@filerobot/core

@filerobot/core

The main module required for using Filerobot widget and it gives the possibility to use the filerobot's plugins.

Usage

From NPM

The plugin is on NPM as @filerobot/core

npm install --save @filerobot/core

then

import Filerobot from '@filerobot/core'
...
...
...
const filerobot = Filerobot(optionsObject)

From CDN

The plugin from CDN is found inside Filerobot global object Filerobot.Core

const FilerobotCore = window.Filerobot.Core
...
...
...
const filerobot = FilerobotCore(optionsObject)

Module's styles

import '@filerobot/core/dist/style.css'

or if you prefer the minified version

import '@filerobot/core/dist/style.min.css'

The Core's styles must be imported before the filerobot's plugins' styles.

Options

There are different options available for the plugin since it is considered as our main plugin, as a brief the following options are available and for their explanation you would find it below:

{
  id: 'filerobot',
  autoProceed: false,
  allowMultipleUploads: true,
  debug: false,
  logger: justErrorsLogger,
  restrictions: {
    maxFileSize: null,
    maxNumberOfFiles: null,
    minNumberOfFiles: null,
    allowedFileTypes: null
  },
  onBeforeFileAdded: (currentFile, files) => currentFile,
  onBeforeUpload: (files) => files,
  <!-- store: DefaultStore() -->
}

id: string (optional)

default: 'filerobot'

The unique indentifier used for identifying the widget's instance and possible to have multiple instances through the different ids.

autoProceed: boolean (optional)

default: false

Defines if to start uploading the files automatically once added without the need to wait to click over upload button, if true the files uploading would start automatically on adding otherwise it would wait the user's press on upload button.

allowMultipleUploads: boolean (optional)

default: true

Whether to accept multiple uploads at the same time or to upload only 1 file.

debug: boolean (optional)

default: false

Turns on the debug mode by exposing the widget's core to global window object & turns on the logger.

logger: object (optional)

default: errors only logger

errorsLogger = {
  debug: (...args) => {},
  warn: (...args) => {},
  error: (...args) => console.error(`[Filerobot] [${getTimeStamp()}]`, ...args)
}

If you need to provide some custom logger for debugging, showing warnings or errors, the default logger logs the errors only.

restrictions: object (optional)

default:

{
  maxFileSize: null,
  maxNumberOfFiles: null,
  minNumberOfFiles: null,
  allowedFileTypes: null
}

Declares the restricions or limits for uploading if any of the limits met the file won't be uploaded:

• maxFileSize (number | null - optional): Defines the maximum one file size in bytes.
• maxNumberOfFiles (number | null - optional): Defines a maxmimum number for files are being uploaded at the same time.
• minNumberOfFiles (number | null - optional): Declares a minimum number of files to start uploading with.
• allowedFileTypes (array | null - optional): Defines which files types are allowed to upload it accepts different forms of file types ex. ['image/*', 'image/jpeg', '.jpg'].

onBeforeFileAdded: (currentFile, files) => ... (optional)

default: (currentFile, files) => currentFile

Gives the possibility to do some checks before adding the file to the state's object,

• if the function returned true the file would be added to the state.
• if returned modified file object the returned object would be added to the state.
• if returned false the file won't be added to the state.

onBeforeUpload: (files) => ... (optional)

default: onBeforeUpload: (files) => files

Gives the possibility to do some checks before starting the upload process

• if the function returned true the upload would start.
• if returned files object the returned object would be processed.
• if returned false the uploading process won't start.

locale: object (optional)

default: default locales

Customizing some of the translations or the language's strings and replace the default locale.

Methods

filerobot.getID()

Gets the filerobot widget instance ID.

filerobot.use(plugin, pluignOptions)

Adds a filerobot's plugin to the filerobot widget's instance with possibility to pass the pluign's options.

example,

import Filerobot from '@filerobot/core'
import FileExplorer from '@filerobot/file-explorer'

const filerobot = Filerobot()
filerobot.use(FileExplorer, {...})

filerobot.getPlugin(pluginId)

Returns the pluign instance with the provided id for accessing its methods & state.

filerobot.removePluign(pluginInstance)

Removes a current installed pluign by passing the pluign's instance that possible to be retrieved from getPluign method.

filerobot.setOptions(options)

Changes the options of the widget so if you have specified some option at the instance of the widget and wants to change it after that, you could use this function to do that, also it is available to be called from getPlugin method to be utilized in changing some option of installed plugin.

example

import Filerobot from '@filerobot/core'

const filerobot = Filerobot()
filerobot.setOptions({
  autoProceed: true
})

another example of being used from getPlugin

import Filerobot from '@filerobot/core'

const filerobot = Filerobot()
filerobot.use(FileExplorer, { id: 'File-explorer' })
filerobot.getPlugin('File-explorer')
  .setOptions({
    animateOpenClose: false
  })

filerobot.addFile(fileObject)

Adds a file into the widget's state and returns the temp generated id for that file.

Note: restrictions are checked & onBeforeFileAdded is called before adding the file.

filerobot.getFile(fileID)

Gets the file object using its ID.

filerobot.removeFile(fileID)

Removes a file from the widget's state through its ID.

filerobot.getFiles()

Returns all the files object of the widget.

filerobot.upload()

An async function that starts uploading the files process, returns a promise resolved with an object result: { successful, failed } that contains:

• successful: An array of the files objects that are uploaded successfully.
• failed: An array of the files objects that faced some errors while uploading.

filerobot.retryAll()

Retries all the failed uploads to start re-uploading.

filerobot.retryUpload(fileID)

Retries a failed upload by the file ID.

filerobot.cancelAll()

Cancels all the uploads by removing all of theme and resetting the progress.

filerobot.setState(object)

updates the internal state of the widget (not very useful for you).

filerobot.getState()

Returns the internal state of the widget.

filerobot.setFileState(fileID, state)

Adds a state into the file's object that's inside the files object of the internal widget's state.

filerobot.reset()

Returns everything to the initial state of the widget ex. stops all the files uploading, reset their progress and removes all of them.

filerobot.close()

Removes all the installed plugins & closes the current widget's instance.

filerobot.on('event', handler)

Adds/Subscribe a handler/callback function to be called on emitting/firing the specified filerobot event, full list of available events.

filerobot.once('event', handler)

Same as filerobot.on but the handler is removed after being called once.

filerobot.off('event', handler)

Un-subscribe/Removes the specified handler for filerobot's event.

filerobot.info(message, type, timeout)

Shows an informer with the specified message to the user:

• message (string | object - required): Defines the message to be shown to the user, either a string ex. Some message or { message: 'Some headline message', details: 'Detailed message would be shown on hovering the informer' }.
• type (string - optional): choses the type of the informer whether info, warning or success default is info.
• timeout (number - optional): The duration which the message would still be shown for in milliseconds, default 3000ms = 3s.

filerobot.log(message, type)

Logs a message in the logger:

• message (string - required): the message would be logged/added/shown in the logger.
• type (string - optional): the type of that logged message whether debug/info, warning or error, default is debug.

Events

The widget emits different events that you could subscribe to or add your handler to be called with the provided arguments passed while emitting/firing the event, the events are listed below with examples show the parameters for handler:

files-added

TBD

file-added

TBD

file-removed

TBD

upload

TBD

restriction-failed

TBD

upload-progress

TBD

upload-success

TBD

upload-error

TBD

upload-retry

TBD

progress

TBD

cancel-all

TBD

complete

TBD

error

TBD

reset-progress

TBD

info-visible

TBD

info-hidden

TBD