npm package: @filerobot/file-explorer
Description: Filerobot explorer for the files uploaded on filerobot, handling them & upload new files.
Latest version: 0.0.0-beta.42

# `@filerobot/file-explorer`

## Usage

### From NPM
The plugin is on NPM as `@filerobot/file-explorer`
```
npm install --save @filerobot/file-explorer
```

then

```
import FileExplorer from '@filerobot/file-explorer'
...
...
...
filerobot.use(FileExplorer, optionsObject)
```

### From CDN

The plugin from CDN is found inside `Filerobot` global object `Filerobot.FileExplorer`

```
const FileExplorer = window.Filerobot.FileExplorer
...
...
...
filerobot.use(FileExplorer, optionsObject)
```

### Plugin's styles

```
import '@filerobot/core/dist/style.css'
import '@filerobot/file-explorer/dist/style.css'
```

or if you prefer the minified version

```
import '@filerobot/core/dist/style.min.css'
import '@filerobot/file-explorer/dist/style.min.css'
```

> The plugin's css file should be imported after the [Core's css file](../core/#modules-styles) for having the styles shown correctly.


## 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: 'FileExplorer',
  target: '#filerobot-container',
  trigger: '#filerobot-trigger-button',
  inline: false,
  width: 750,
  height: 500,
  floaty: false,
  showBar: true,
  thumbnailWidth: 280,
  waitForThumbnailsBeforeUpload: false,
  showProgressDetails: true,
  hideUploadButton: false,
  hideRetryButton: false,
  hideCancelButton: false,
  note: null,
  closeModalOnClickOutside: false,
  closeAfterFinish: false,
  disableStatusBar: false,
  disableInformer: false,
  disableThumbnailGenerator: false,
  disablePageScrollWhenModalOpen: true,
  animateOpenClose: true,
  onRequestCloseModal: () => this.closeModal(),
  locale: default,
  browserBackButtonCloseModal: false,
  theme: 'light',
  noImgOperationsAndDownload: false,
  disableSelectionActions: false,
  topRightMenuComponentItem: undefined,
  disableExportButton: false,
  tagsInsideGeneral: false,
  viewType: 'grid',
  showFolderTree: false,
  showDetailsView: false,
  contextMenuSubTabs: {
    fileMore: ['META', 'TAGS', 'EMBED', 'VISIBILITY', 'VERSIONING', 'VARIANTS'],
    fileShare: ['SHARE_ASSETS', 'GET_LINK']
  },
  config: {
    container: 'demo',
    apiEndpoint: 'api',
    adminEndpoint: 'admin',
    sassKey: sassKey,
    foldersLimit: 200,
    filesLimit: 50,
    folderPath: '/',
    tagging: {
      language: 'en',
      confidence: 60,
      key: '',
      limit: 10,
      provider: 'google',
      suggestionList: [
        'Alligator',
        'Bask',
        'Crocodilian',
        'Death Roll'
      ]
    }
  },
  noItemsBrowser: false,
  resetAfterClose: false
}
```
#### `config: object` *(required)*

*default:* `null`

The config which contains different options for the backend requests and files/folders handling:

  - **container** (*string* - required): Your filerobot container's token which will receive all the requests and handling.
  - **apiEndpoint** (*string* - optional): The base API's endpoint will be used for handling the different base APIs, default is `api` to become `https://`***`api`***`.filerobot.com/api/`.
  - **adminEndpoint** (*string* - optional): The endpoint for handling the different requests communicating with admin's backend, default is `admin` to become `https://`***`admin`***`.filerobot.com/api/`.
  - **sassKey** (*string* - required): The authorization key for your filerobot account that would allow the plugin to do the different functionalities available.
  - **foldersLimit** (*number* - optional ): the number of folders to be retrieved in the 1 request, default is 200,
  - **filesLimit** (*number* - optional ): the number of files to be retrieved in the 1 request, default is 50,
  - **folderPath** (*string* - optional): the folder path to be used as the root folder and opened as the first folder, default is '/'
  - **tagging** (*object* - required): the options that would utizlied for tags functionality with the following properties
    - **language** (*string* - optional): the language used for saving & generating tags, default is 'en'.
    - **confidence** (*number* - optional): the confidence score from which the auto generated tags would be chosen default is 60.
    - **limit** (*number* - optional): the count of tags should be generated, default is 10.
    - **provider** (*string* - optional): the provider utilized in generating the tags, default is'google'.
    - **suggestionList** (*array of strings* - optional): different tags strings act as suggestions list for the tags functionlaity to be shown while writing some tag and there are some matches between the being written tag & any of the suggestions.

#### `id: string` *(optional)*

*default*: `'FileExplorer'`

An unique identifier for the plugin to be indentified between the other plugins through it.

#### `target: string` *(required)*

*default:* `'body'`

The selector that would be used for rendering the whole plugin, it is passed to `querySelector` function so it is possible to provide it with an HTML tag ex. `body` or some CSS selector ex. `#filerobot-container` or `.filerobot-container`.

#### `trigger: string` *(required if `inline: false`)*

*default:* `null`

The selector that would be used for triggering the whole plugin's rendering it is passed to `querySelectorAll` function so it is possible to provide it with an HTML tag ex. `body` or some CSS selector ex. `#filerobot-trigger-button` or `.filerobot-trigger-button` and also you could have multiple triggers as `click event` would attached to all of them.

#### `inline: boolean` *(required)*

*default:* `false`

Defines the way to open the plugin, if `true` it would open in the element referred to in [`target`](#target-string-required) property if `false` it would open as a modal.

#### `width: number/string` *(required)*

*default:* `700(px)`

Defines the width of the plugin, it should be number if you need it specified in `px` ex. `700` or a percentage string ex. `50%`.

#### `height: number/string` *(required)*

*default:* `500(px)`

Defines the height of the plugin, it should be number if you need it specified in `px` ex. `500` or a percentage string ex. `35%`.

#### `floaty: boolean` *(optional)*

*default:* `false`

Defines the mode of the plugin whether it is floaty in the current document (the items would be floaty in the document as you are opening the plugin from the document itself ex. scrolling would be from the page's body or plugin's container scroll bar...etc.) that is if the value is `true` otherwise `false` would be treated as a normal mode the plugin is embedded in the page and have its own container that would be scrolled...etc.

> ***Note:*** using this would change some behavior/styles in the whole plugin ex. bigger spacings for some elemnts, having close button instead of back for slided wrappers/modals ...etc. so make sure that you need to use it.

#### `showBar: boolean` *(optional)*

*default:* `true`

Whether to choose from showing or hiding the plugin's top bar which contains the search & upload button, if `true` it would be shown `false` would be hidden.

#### `thumbnailWidth: number` *(optional)*

*default:* `280`

Defining the width of the thumbnails that would be generated for some of the files being uploaded should be a number refers to `px` unit ex. `280` which is `280px`.

#### `waitForThumbnailsBeforeUpload: boolean` *(optional)*

*default:* `false`

Delays the start of uploading process till the thumbnails for files selected to be uploaded are generated.

#### `showProgressDetails: boolean` *(optional)*

*default:* `true`

Choose if you need to keep the progress details of uploading process shown or not example of these details are (uploaded files count of total, ETA for the process, total size).

#### `hideUploadButton: boolean` *(optional)*

*default:* `false`

Gives the chance to hide the upload files button from the whole pluign.

#### `hideRetryButton: boolean` *(optional)*

*default:* `false`

Gives the chance to hide the retry button which retries the uploading process.

#### `hideCancelButton: boolean` *(optional)*

*default:* `false`

Gives the same chance for hiding the cancel button while uploading some file(s).

#### `note: string` *(optional)*

*default:* `null`

Some text that is being added & shown in the add files panel (which lets you show which pluign to use to upload from) at the bottom for giving the user some note to consider.

#### `closeModalOnClickOutside: boolean` *(optional)*

*default:* `false`

It's clear that it adds the possibility to close the pluign's modal on clicking outside of the modal.

#### `closeAfterFinish: boolean` *(optional)*

*default:* `false`

Close the modal after finish uploading if `true`.

> ***Note:*** Doesn't work with `inline: true` as it is related to closing the modal only.

#### `disableStatusBar: boolean` *(optional)*

*default:* `false`

Disables the [`status-bar`](../status-bar/#filerobotstatus-bar) plugin which shows the progress of uploading/downloading if `true`.

#### `disableInformer: boolean` *(optional)*

*default:* `false`

Disables the [`informer`](../informer/#filerobotinformer) plugin if `true` that shows some info, warnings & errors to the user which seems very helpful for the user to know.

#### `disableThumbnailGenerator: boolean` *(optional)*

*default:* `false`

Disables the [`thumbnail-generator`](../thumbnail-generator/#Filerobothumbnail-generator) plugin that generates thumbnails for some of the images.

#### `disablePageScrollWhenModalOpen: boolean` *(optional)*

*default:* `true`

Defines if to give the user the possibility to scroll the document while the plugin's modal is shown or not, if `true` the scroll will be disabled for the document while the modal is shown if `false` the scroll will be possible and enabled normally for the document.

#### `onRequestCloseModal: () => undefined` *(optional)*

*default:* `closeModal` function

Adding some custom function to be triggered when trying to close the modal.

> ***Note:*** The default behavior which is closing the modal would be overriden.

#### `animateOpenClose: boolean` *(optional)*

*default:* `true`

Animates the modal's opening & closing, if `true` it would be animated, if `false` it won't.

#### `locale: object` *(optional)*

*default:* [default locales](../dashboard/src/index.js#L52) & [default locales ext.](src/index.js#L12)

Customizing some of the translations or the language's strings and replace the default locale.

#### `theme: string` *(optional)*

*default:* `'light'`

Changing the theme mode (light/dark/auto),
- **light**: uses the light theme
- **dark**: uses the dark theme
- **auto**: respecting the user's default mode and depending on it choosing between dark/light

#### `browserBackButtonCloseModal: boolean` *(optional)*

*default:* `false`

Makes the go back button of the browser closes the plugin's modal, works only in case you are having `inline: true` and showing the plugin in modal.

#### `noImgOperationsAndDownload: boolean` *(optional)*

*default:* `false`

For hiding image's operations and download items in context menu (ex. download, edit image...etc.).

#### `disableSelectionActions: boolean` *(optional)*

*default:* `false`

For disabling the actions buttons at the top bar that shown on selecting some item.

#### `disableExportButton: boolean` *(optional)*

*default:* `false`

Hiding the export button at the top left and showing selected label with the count of selected items.

#### `topRightMenuComponentItem: React.Component` *(optional)*

*default:* `undefined`

A react component that would be added at the top right menu of the top bar for appending/expanding some functionality.

#### `tagsInsideGeneral: boolean` *(optional)*

*default:* `false`

if true the **tags** tab would be moved to **General** tab and **General** tab would be renamed to **General & Tags**.

#### `viewType: string` *(optional)*

*default:* `'grid'`

Defines the view type for the items in the plugin (also it is possible to be changed from the pluign's top right options), its values are:
  - **grid**: shows the items as cards in a grid.
  - **list**: shows the items as horizontal rows in a list (act like table).
  - **tiles**: same as **list** but with more comfortable spaces between the data and default shown columns are fewer.

#### `showFolderTree: boolean` *(optional)*

*default:* `false`

Whether to show the folders tree navigation on the left side or not, if `true` it would be shown by default if `false` it won't be shown by default (it is possible to be changed from the pluign's top right options).

#### `showDetailsView: boolean` *(optional)*

*default:* `false`

Whether to show the details view side navigation on the right which is responsible for showing a brief data or information about the current open folder or selected folder(s)/file(s) (it is possible to be changed from the pluign's top right options).

#### `contextMenuSubTabs: object` *(optional)*

*default:*
```
{
  fileMore: ['META', 'TAGS', 'EMBED', 'VISIBILITY', 'VERSIONING', 'VARIANTS'],
  fileShare: ['SHARE_ASSETS', 'GET_LINK']
}
```

If you need to customize the sub tabs that are opened from the parent tabs of the context menu (the menu shown on clicking right click on the file/folder):
  - **fileMore** (*array of strings*): the sub tabs for *more details* parent tab inside **file**'s context menu, those are all the sub tabs available for that parent tab `['META', 'TAGS', 'EMBED', 'VISIBILITY', 'VERSIONING', 'VARIANTS']`.
  - **fileShare** (*array of strings*): the sub tabs for *share* parent tab inside **file**'s context menu, those are all the sub tabs available for that parent tab `['SHARE_ASSETS', 'GET_LINK']`.

#### `noItemsBrowser: boolean` *(optional)*

*default:* `false`

If `true`, hides the items browser that shows files/folders, topbar and makes the add files panel (which gives the user chance to choose to upload a file from which plugin) as the primary panel.

#### `resetAfterClose: boolean` *(optional)*

*default:* `false`

If `true`, resets and removes the current uploading state & files after closing the plugin's modal in case `inline:false`.