@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

Changing the language's translations or 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:

Emitted

file-added

Emitted when a file has been added to the selected files for uploading.

params:

• file: The file object whom thumbnail is generated.

example

filerobot.on('file-added', (newFile) => {
  console.log('The new file object which is added:', newFile)
})

file-removed

Emitted when a file has been removed from the selected files for uploading.

params:

• file: The file object removed.
• deleteionReason: The reason for deleting the file or from where the deletion has done might be provided or not.

example

filerobot.on('file-removed', (removedFile, reason) => {
  console.log(`The file ${removedFile.name} is removed because ${reason}, file's object:`, removedFile)
})

upload

Emitted on creating a new upload process.

params:

• object: An object contains both the uploading process ID and the the files IDs for files to be uploaded, ex. { id: uploadID, fileIDs: fileIDs }.

example

filerobot.on('upload', (uploadProcess) => {
  console.log('Upload started: ', uploadProcess.uploadID)
  console.log('Contains the following file IDs', uploadProcess.fileIDs)
})

restriction-failed

Emitted when the restriction checking is failed and there is a file doesn't meet the restrictions.

params:

• file: The file object that has failed the check.
• error: The error faced/fired during the check.

example

filerobot.on('restriction-failed', (file, error) => {
  console.log('Couldnt process the following file object', file)
  console.log('As the following error fired:', error)
})

upload-progress

Emitted when there is a progress of some file uploading in the upload process.

params:

• file: The file object that has some progress in its uploading.
• progress: An object contains the progress of the file being uploaded, ex. { filerobot: plugin's instance, bytesUploaded: 1500, bytesTotal: 3500 }.

example

filerobot.on('upload-progress', (file, progress) => {
  console.log('The following file object progressed', file)
  console.log('The progress object is as following', progress)
})

upload-success

Emitted when a file is successfully uploaded.

params:

• file: The file object that has uploaded.
• uploadResponse: The upload request response received.

example

filerobot.on('upload-success', (file, response) => {
  console.log(`The ${file.name} with the object ${file} is uploaded and the whole respones`, response)
})

upload-error

Emitted when a file faced some error/issue while uploading.

params:

• file: The file object which fired the error.
• error: The error faced while uploading.

example

filerobot.on('upload-error', (file, error) => {
  console.log('File faced that error while uploading', file, error)
})

upload-retry

Emitted on some file uploading is retried.

params:

• fileID: The ID of the file which its upload process is retried.

example

filerobot.on('upload-retry', (fileID) => {
  console.log('The following file ID is being re-uploaded:', fileID)
})

progress

Emitted on having a progress of an upload process's total progress.

params:

• totalProgress: The total progress value of the current uploading process.

example

filerobot.on('progress', (totalProgress) => {
  console.log('The uploading total progress for now: ', totalProgress)
})

cancel-all

Emitted when the whole upload process is canceled (all files uploading are canceld).

params: No params returned.

example

filerobot.on('cancel-all', () => {
  console.log('The upload is canceled')
})

complete

Emitted when the whole upload process done and completed.

params:

• completionObject: An object contains the results of the completed upload process, ex. { failed: failedFiles, uploadID: ..., successful: uploadedFiles }.

example

filerobot.on('complete', ({ failed, uploadID, successful }) => {
  console.log(`The upload ${uploadID} is completed with following results success then failed files`, successful, failed)
})

error

Emitted when the whole upload process faced an error.

params:

• error: The error shown of the uploading process.
• uploadID: The ID of the errored uploading process.

example

filerobot.on('error', (error, uploadID) => {
  console.log(`The upload with ID ${uploadID} faced this error while uploading`, error)
})

reset-progress

Emitted when the upload's progress is reset to 0.

params: No params returned.

example

filerobot.on('reset-progress', () => {
  console.log('The progress is reset')
})

info-visible

Emitted on showing an info message to the user.

params: No params returned.

example

filerobot.on('info-visible', () => {
  console.log('inFo message shown.')
})

info-hidden

Emitted on hiding an info message that were shown to the user.

params: No params returned.

example

filerobot.on('info-hidden', () => {
  console.log('The progress is hidden.')
})