@filerobot/explorer

The file Explorer and media gallery plugin of the Filerobot Media Asset Widget.

Usage

NPM

npm install --save @filerobot/explorer

YARN

yarn add @filerobot/explorer

then

import Explorer from '@filerobot/explorer'
...
...
...
filerobot.use(Explorer, propertiesObject)

CDN

If installed via a CDN link, the plugin is inside the Filerobot global object as Filerobot.Explorer

const Explorer = window.Filerobot.Explorer
...
...
...
filerobot.use(Explorer, propertiesObject)

Plugin styles

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

or via the minified versions

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

The plugin's css file should be imported after the Core's css file for having the styles shown correctly.

Properties

The Explorer supports multiple properties to customize the plugin according to your needs. Required attributes are marked with (Required).

config

Type: object Required.

Default:

{
  config: {
    companyName: 'scaleflex',
    foldersLimit: 200,
    filesLimit: 50,
    rootFolderPath: '/',
    tagging: {...} // check tagging section
  }
}

The config objects contains the main configuration for the plugin to interact with your Filerobot project:

companyName

Type: string.

Default: scaleflex

Your company name, used when sharing assets.

foldersLimit

Type: number.

Default: 200

Number of folders to be retrieved with folders initial request.

filesLimit

Type: number.

Default: 50

Number of files to be retrieved with files initial request.

rootFolderPath

Type: string.

Default: /

Override the root folder path.

tagging

Type: object.

Default:

  tagging: {
    enabled: false,
    autoTagging: false,
    suggestedTagsOnly: false,
    language: 'en',
    confidence: 60,
    limit: 10,
    provider: 'google',
    suggestionList: []
  }

The options available for tagging

Property	Type	Default	Description
enabled	boolean	false	Enable/disable tags
autoTagging	boolean	false	Enable/disable auto-tagging
suggestedTagsOnly	boolean	false	Enable/disable suggested tags only. When it's TRUE, users can only select tags from a pre-defined list. Notice that when suggestedTagsOnly is TRUE, autoTagging will be disabled.
language	string	en	AutoTagging config that we add in POST process/autoTag request data.meta
confidence	number	60	AutoTagging config that we add in POST process/autoTag request data.meta
limit	number	10	AutoTagging config that we add in POST process/autoTag request data.meta
provider	string	[]	AutoTagging config that we add in POST process/autoTag request data.meta
suggestionList	object[]	1	Tags suggestions list that is shown under tags field. By default we show primary tags, but when user start typing we filter full suggestionList. Object format:

    {
      sid: string, // Short id like: '#tg1885f'
      names: {
        en: string,
        fr: string
      },
      primary: boolean // If true, tag will be shown in Suggestions list below tags field
    }

inline

Type: boolean.

Default: false

If set to true, the plugin will be displayed as inline element in the element referred by the target property. Otherwise, it will pop up in a modal upon trigger, see below.

floaty

Type: boolean.

Default: false

configures the plugin to be floaty and stay in a fixed position as you scroll the media library.

Setting the floaty attribute to true override width and height to 100% and it has an impact on some styles and behavior, eg. bigger spacings for some elements.

trigger

Type: string.

Default: null

The selector used for triggering the display of the plugin modal, if passed to querySelectorAll function. Available options:

• HTML tag, eg. body
• CSS selector, eg. #filerobot-trigger-button or .filerobot-trigger-button

Multiple triggers are supported as click events.

Required if inline: false

target

Type: string Required.

Default: body

The selector used for displaying the plugin, if passed to querySelector function. Options:

• HTML tag, eg. body
• CSS selector, eg. #filerobot-container or .filerobot-container

width

Type: number| string.

Default: 768

Width of the plugin as a number if specified in pixels or a percentage, eg. '50%'

height

Type: number| string.

Default: 538

Height of the plugin as a number if specified in px or a percentage eg. '35%'

thumbnailWidth

Type: number.

Default: 280

Pixel width of the asset thumbnails displayed in the gallery. Apect ratio of images is kept in case of image assets.

thumbnailHeight

Type: number.

Default: 170

Pixel height of the asset thumbnails displayed in the gallery. Aspect ratio of images is kept in case of image assets.

noItemsBrowser

Type: boolean.

Default: false

Hides the Explorer view displaying files/folders and only allows the user to upload a single or multiple assets. In summary, if set to true it puts the upload page as default homepage and removes the gallery.

views

Type: array.

Default: ['ASSETS', 'COLLECTIONS', 'LABELS', 'FAVORITES', 'FOLDERS', 'PRODUCTS']

List of available views.

NOTE some views can be hidden if you don't have permission provided in securityTemplateId.

defaultView

Type: string.

Default: ['FOLDERS']

View which will be opened by default.

layoutType

Type: boolean.

Default: grid

Specifies the default layout in the view:

Value	Description
grid	shows folders/assets as cards in a grid
list	shows the folders/assets as rows in a table

you can switch between layouts from the layout selector button in the right side in header bar.

waitForThumbnailsBeforeUpload

Type: boolean.

Default: false

If set to true, delays the start of the upload process until the asset thumbnails are generated and displayed in the plugin.

showBar

Type: boolean.

Default: true

If set to false, hides the top bar with Upload button, searchBar, create folder button and view button.

showProgressDetails

Type: boolean.

Default: true

If set to false, hides the upload progress bar.

hideUploadButton

Type: boolean.

Default: false

If set to true, hides the Upload button at the top of the plugin.

hideSearch

Type: boolean.

Default: false

Hides Search field at the top of the plugin.

hideCancelButton

Type: boolean.

Default: false

Hides the Cancel button that is used to cancel an upload.

note

Type: string.

Default: null

A custom note displayed in the upload screen.

closeModalOnClickOutside

Type: boolean.

Default: false

Plugin modal will be closed when clicking outside of the modal.

Only relevant if inline: false

closeAfterFinish

Type: boolean.

Default: false

Modal will close after upload is finished.

closeAfterExport

Type: boolean.

Default: false

Modal will close after export.

closeUploadPanelAfterFinish: boolean

Type: boolean.

Default: false

The upload panel will be closed automatically and explorer would be shown.

Only relevant if inline: false

onClickDoneButton

Type: function.

Default: () => {}

A callback function that would be triggered when the user clicks on done button that is shown in the uploads panel after the uploads finish

disableStatusBar

Type: boolean.

Default: false

Disables the status-bar plugin which shows the upload/download progress.

disableProgressPanel

Type: boolean.

Default: false

Disables the progress-panel plugin which shows progress/status of uploads, downloads, transformations activities inside a panel.

disableInformer

Type: boolean.

Default: false

Disables the informer plugin used to show warnings and errors.

disableThumbnailGenerator

Type: boolean.

Default: false

Disables the thumbnail-generator plugin that generates image thumbnails.

disablePageScrollWhenModalOpen

Type: boolean.

Default: true

If set to true, disables scrolling for the document while the plugin modal is open.

Only relevant if inline: false

disableDownloadButton

PREVIOUSLY: disableExportButton & disableTopBarMainButton

Type: boolean.

Default: false

Hides the download button shown in the action bar when selecting files.

hideExportOptionsMenu

Type: boolean.

Default: false

Hides the export options menu at the action bar.

preventDownloadDefaultBehavior

PREVIOUSLY: preventExportDefaultBehavior

Type: boolean.

Default: false

Prevent default behavior of download/export.

hideDownloadButtonIcon

PREVIOUSLY: hideExportButtonIcon

Type: boolean.

Default: false

Hides the download/export button icon.

hideHeaderBar

Type: boolean.

Default: false

Hides the header bar, header bar contains breadcrumbs and other action buttons.

hideExportCropPanel

PREVIOUSLY: disableExportCropPanel

Type: boolean.

Default: false

The crop button in the export options modal will be hidden.

forceDownload

Type: boolean.

Default: false

Adds download=1 param to the CDN download link

defaultCollectionUuid

Type: string.

Default: null

Navigate to the collection view and open the provided collection.

Only relevant if Collections view is provided in views

defaultLabelSid

Type: string.

Default: null

Navigate to the labels view and open the provided label.

Only relevant if Labels view is provided in views

defaultFilters

Type: object.

Default: null

Apply the provided filters on initial load.

defaultSearchQuery

Type: string.

Default: ''

Apply the provided search query on initial load.

imageEditorMode

Type: string.

Default: 'default'

Possible values: 'default' | 'cloudimage'

Set imageEditorMode for the image editor plugin.

defaultItemToFocus

Type: object.

Default: null

Navigate to the provided item and focus on mount

hideModalAfterExport

Type: boolean.

Default: false

Hides the modal after finish download/export.

closeAfterImageEdit

Type: boolean.

Default: false

Hides the modal after finish editing image.

onRequestCloseModal

Type: () => undefined.

Default: closeModal function

Specified a custom function to be executed when trying to close the modal. Default closing modal behavior is overridden

Only relevant if inline: false

animateOpenClose

Type: boolean.

Default: true

Disable the modal's opening and closing.

Only relevant if inline: false

locale

Type: object.

Default: locales from filerobot's backend then default locale file with all labels is under lib/defaultLocale.js.

You can override some labels by specifying a translation object here, such as:

{
  strings: {
    baseFolderTitle: 'Root' // overrides the default Home value to Root
  }
}

browserBackButtonCloseModal

Type: boolean.

Default: false

The browser Back button will close the modal, otherwise it will trigger the standard back browser behavior.

Only relevant if inline: false

enableFoldersStatsApiRequest

Type: boolean.

Default: false

When enabled it will send extra folders/stats API request with the folders request to get folders count.

isUploadBarAddMoreButtonHidden

Type: boolean.

Default: false

The 'Add More' button in upload module is hidden preventing users to upload more item.

currentUserInfo

Type: object.

Default:

{
  email: '',
  name: ''
  photo_uri : '',
  uuid : ''
}

The info of current user using Filerobot Media Asset Widget mainly used in comments tab of file window and recognizing the user, it consists of:

Property	Type	Default	Description
name	string required	''	user name
email	string	''	user email
photo_uri	string required	''	user avatar link
uuid	string required	''	user id

showFoldersTree

Type: boolean.

Default: false

Shows/hides on initial load the folder tree as a sidebar at the left of the plugin to navigate folders. The user can shows/hides the folder tree from the tree icon in the breadcrumbs.

Only relevant if folders view is provided in views

showProductsTree

Type: boolean.

Default: false

Shows/hides on initial load the product tree as a sidebar at the left of the plugin to navigate products. The user can shows/hides the product tree from the tree icon in the breadcrumbs.

Only relevant if products view is provided in views

showCollectionsTree

Type: boolean.

Default: false

Shows/hides the collection tree as a sidebar at the left of the plugin to navigate collections. The user can shows/hides the collection tree from the tree icon in the breadcrumbs.

Only relevant if collection view is provided in views

showLabelsTree

Type: boolean.

Default: false

Shows/hides the label tree as a sidebar at the left of the plugin to navigate labels. The user can shows/hides the label tree from the tree icon in the breadcrumbs.

showDetailsView

Type: boolean.

Default: false

Shows/hides the asset details view as a sidebar at the right of the plugin to view various details about selected assets. The user can shows/hides the details view from the info icon in the right side of the breadcrumbs.

hideDetailsViewIcon

Type: boolean.

Default: false

Hides the details viw icon on the right sidebar.

contextMenuSubTabs

Type: object.

Default:

{
  fileMore: ['REMOVE_BACKGROUND','TRANSCODE_VIDEO'],
  fileShare: ['PUBLISH', 'MANAGE_ACCESS', 'GET_LINK', 'VIA_SHAREBOX', 'EMBED']
}

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):

Property	Type	Default	Description
fileMore	strings[]	['REMOVE_BACKGROUND', 'TRANSCODE_VIDEO']	sub items for more Actions option inside assets's context menu
fileShare	strings[]	['PUBLISH', 'MANAGE_ACCESS', 'GET_LINK', 'VIA_SHAREBOX', 'EMBED']	sub items for share option inside assets's context menu

videoTranscoding

Type: object.

Default:

{
  resolution: 'auto',
  protocol: 'HLS'
}

Video transcoding options for post-upload video transcoding:

Property	Type	Default	Description
resolution	string required	auto	target resolutions for video transcoding
protocol	string required	HLS	which protocol to use while transcoding

cropPresets

Type: object.

Default: {}

Defines additional crop types & presets besides the freehand one and their presets and its shape as follows

{
  'Social media': [
    /**
     * label: possible to be a string or string in form of i18n key provided through locale object
     * value: value follows this format (width:height:autoResize) or one of the following stringy values (original/ellipse) which defines the width & height of the crop preset autoResize which is a boolean value if `true` then resizing inputs will be disabled and auto resize will be applied automatically otherwise they're enabled, ratio of crop will be determined from width / height.
     */
    { label: 'Facebook profile', value: '400:400:true' },
    { label: 'linkedInCover', value: '1128:191:false' }
  ],
  custom: [
    { label: 'logoSize', value: '320:100' }
  ],
  ellipse: {
    label: 'ellipse', value: 'ellipse'
  },
  original: {
    label: 'original', value: 'original'
  }
}

NOTE

The object's keys will be used the label for crop type (it is possible to be label string or i18n key string that is provided through locale object)

showRemoveBackgroundOption

Type: boolean.

Default: false

Remove background option will appear in context menu.

disableMultipleSelect

Type: boolean.

Default: false

Multiple files/folders selections will be disabled and only 1 file/folder possible to be selected.

dismissUrlPathQueryUpdate

Type: boolean.

Default: false

The url query fmaw_path won't be added/updated to the current url.

showFilerobotCopyright

Type: boolean.

Default: true

Hides filerobot copyright at the bottom of the plugin.

noImgOperationsAndDownload

Type: boolean.

Default: false

If set to true, hides some options in asset contextual menu:

• Download
• Edit image

disableFoldersContextMenu

Type: boolean.

Default: false

If set to true, will disable and hide the contextual menu of folders.

disableFolderSelection

Type: boolean.

Default: false

If set to true, will disable the selection of folders.

viewerMode

Type: boolean.

Default: false

If set to true, will hide and prevent the actions of editing.

explorerWrapperClassName

Type: string.

Default: null

ClassName(s) to add to the explorer wrapper.

disableListLayout

Type: boolean.

Default: false

If set to true, will hide the button and prevent the possiblity to switch from grid view to list view.

hideFileOptions

Type: boolean.

Default: false

If set to true, will hide the options appear at the top of the file item.

hideFolderOptions

Type: boolean.

Default: false

If set to true, will hide the options appear at the top of the folder item.

replaceDownloadButtonWithExport

Type: boolean.

Default: false

If set to true, will replace the default download button with export button.

queryParamPrefix

Type: string.

Default: fmaw_

Override the query params

showDragDropPanel

Type: boolean.

Default: false

Changes the design for the addFiles panel in uploads.

showSort

Type: boolean.

Default: true

shows/hides sort button in Explorer.

isDownloadUsageRightsEnabled

Type: boolean.

Default: false

Enables/disables the download of usage rights file with assets.