@filerobot/explorer v3.41.2

@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: '/',
    defaultSort: {
      by: '',
      order: ''
    },
    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.

defaultSort

Type: object.

Default: { by: 'name', order: 'asc' }

Customize the default selected sort option for both files & folders shown in the main view (not applicable for folders tree or objects' trees) applied for all the files shown regardless of the opened view.

The options available sorting

Note: its value is considered only on plugin's install/mount.

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

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

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 Deprecated - use view instead

Type: string.

Default: 'FOLDERS'

View which will be opened by default.

view

Type: string.

Default: 'FOLDERS'

View which will be currently opened.

viewItem

Type: string.

Default: null

Open the provided view's item/object for ex. (folders view => folder path, labels view => label sid or uuid, collections view => collection uuid, products view => product ref...etc.)

Note: No auto redirect to the view, you have to provide the proper view from view prop.

viewSubItem

Type: string.

Default: null

A sub item that should be opened inside the provided view & viewItem, mostly used for opening a collection virtual folder that's found inside some collection.

Note: No auto redirect to the view, you have to provide the proper view from view prop.

layoutType

Type: boolean.

Default: grid

Specifies the default layout in the view:

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.

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.

note

Type: string.

Default: null

A custom note displayed in the upload screen for drag&drop.

hint

Type: string.

Default: null

A custom hint displayed in the upload screen at the bottom.

closeModalOnClickOutside

Type: boolean.

Default: false

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

Only relevant if inline: false

preventModalOverlayClickOnUpload

Type: boolean.

Default: false

Plugin modal still opened when click outside of it, if there's selected files to be uploaded

Only relevant if closeModalOnClickOutside: true

closeAfterFinish

Type: boolean.

Default: false

Modal will close after upload is finished.

Only relevant if inline: false

onClickUploadButton

Type: function.

Default: () => {}

A callback function that would be triggered when the user clicks on upload button that is shown in the uploads 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.

preventDownloadDefaultBehavior

PREVIOUSLY: preventExportDefaultBehavior

Type: boolean.

Default: false

Prevent default behavior of download/export.

hideDownloadTransformationOption

Type: boolean.

Default: false

Hide transformation in download options in context menu and action bar.

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 Deprecated - use view & viewItem instead

Type: string.

Default: null

Navigate to the collection view and open the provided collection.

Only relevant if Collections view is provided in views

defaultLabelSid Deprecated - use view & viewItem instead

Type: string.

Default: null

Navigate to the labels view and open the provided label.

Only relevant if Labels view is provided in views

defaultFilters Deprecated - use filters instead

Type: object.

Default: null

Apply the provided filters on initial load.

defaultSearchQuery Deprecated - use search.query instead

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.

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.

contextMenuSubTabs

Type: object.

Default:

{
  fileMore: ['REMOVE_BACKGROUND', 'LOCATE_FILE'],
  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):

videoTranscoding

Type: object.

Default:

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

Video transcoding options for post-upload video 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: true

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

Hides filerobot copyright at the bottom of the plugin.

useAssetsPicker

Type: boolean.

Default: false

If set to true, actions like deleting, editing, or downloading assets will not be allowed, explore and insert actions allowed.

disableFolderSelection

Type: boolean.

Default: false

If set to true, disable the possiblity to select folder(s).

hideFolderOptions

Type: boolean.

Default: false

If set to true, hide the folder item top options.

hideFileOptions

Type: boolean.

Default: false

If set to true, hide the file item top options.

hideDetailsTab

Type: boolean.

Default: false

If set to true, hide toggle details tab button.

hideActionBarSelectionButtons

Type: boolean.

Default: false

If set to true, hide the selection buttons in the action bar.

disableDnDActions

Type: boolean.

Default: false

If set to true, disable the drag and drop actions to move assets/folders or upload

noImgOperationsAndDownload

Type: boolean.

Default: false

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

• Download (context menu)
• Transformation (action bar)
• Edit image (context menu and action bar)

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.

useLoginMode

Type: boolean.

Default: false

Enables/disables the login mode which gives the user the possibility to login by his credentials (email & password) through a form shown to the user while using the widget, respecting the provided container in the core class of the widget.

Note: Don't provide security template key nor sass key if you need to use enable this feature by providing its value to true.

prefilledLoginModeEmail

Type: string.

Default: null

The property used to add a default email address in the email address field of the login mode form, if not provided the email address will be empty. In both cases, the user will be able to change/add his email address and this property is used by having useLoginMode enabled.

hideAddingComment

Type: boolean.

Default: false

Removes the add comment textarea from the comments tab.

restrictedSearchContext

Type: boolean.

Default: false

Providing true, will disable the possibility of selecting other search contexts and always force the user to use the current opened view's context.

facetedSearchEnabled

Type: boolean.

Default: false

Faceted search allows users to filter files using metadata filters. When this feature is enabled:

• The filters bar will be hidden.
• Only metadata filters with select, select-one, and boolean fields will be displayed.

Note: Faceted search is only active in the assets view.

facetedSearchSidebarExpanded

Type: boolean.

Default: true

expands faceted search sidebar by default.

Note: if facetedSearchEnabled is false, this property will be ignored.

activeFacetedSearchMetadataFields

Type: array.

Default: []

Array of metadata fields keys to be shown on faceted search.

Note: only exist filters will be shown.

activeFacetedSearchFilters

Type: array.

Default: []

Array of filters keys to be shown on faceted search.

filters

Type: object.

Default: {}

Filters to be applied to the views that accept filters, and will be locked if disableFiltersAndSearch or forceFilters is true, consists of the following:

{
  // `dateOption`: Either a string 'CREATED'/'UPDATED' or integer 0/1.
  dateOption: 0,

  // `dateRange` Either a string 'LAST_DAY'/'LAST_7_DAYS'/'LAST_30_DAYS'/'LAST_90_DAYS'/'LAST_180_DAYS' or integer 1/2/3/4/5 -- constants are preferred -- or for custom range provide an array [from, to] each date in the form yyyy-mm-dd .
  dateRange: 'LAST_7_DAYS',

   // `mimeTypes`: An Array of strings, acceptable values any/all of the following ['IMAGE', 'VIDEO', 'AUDIO', 'DOCUMENT', 'ARCHIVE'] or ['image', 'video', 'audio', 'application', 'application/zip, application/x-zip-compressed, application/vnd.rar, application/x-rar-compressed'] -- constants are preferred --.
  mimeTypes: ['IMAGE', 'VIDEO'],

  // `fileTypes`: An Array of strings, acceptable values are provided from BE filters API value property found in file type objects, ex. ['img|x-icon', 'img|jpeg'].
  fileTypes: ['img|png', 'img|jpeg'],

  // `size`: An Array of integers (only 2), values provided are considered as MB. [minMB, maxMB].
  size: [0, 10],

  // `tags`: An Array of strings, values are tag sids coming from BE but without (#).
  tags: ['tge3c9d', 'tgdeaa9'],

  // `imageOrientations`: An Array of strings, any/all of the following values are valid ['PORTRAIT', 'PANORAMA', 'SQUARE', 'LANDSCAPE'] or ['portrait', 'panorama', 'square', 'landscape'] -- constants are preferred --.
  imageOrientations: ['PORTRAIT', 'SQUARE'],

  // `imageResolutions`: An Array of strings, any/all of the following values are possible ['SMALL', 'MEDIUM', 'LARGE'] or ['small', 'medium', 'large'] -- constants are preferred --.
  imageResolutions: ['MEDIUM', 'LARGE'],

  // `imageFaces`: An Array of strings, any/all of the following values are possible ['NO_FACES', 'ONE_FACE', 'TWO_FACES', 'ANY'] or ['0', '1', '2', '*'] -- constants(capitalized) are preferred -- (* => means group/multiple of faces).
  imageFaces: ['1', '*'],

  // `imageMainColors`: An Array of strings, represents the color stringy value it must be any/all of the following only no other colors ['PURPLE', 'RED', 'ORANGE', 'PINK', 'GRASS_GREEN', 'YELLOW', 'AZURE', 'CHARTREUSE', 'TEAL'] or ['purple', 'red', 'orange', 'pink', 'grass_green', 'yellow', 'azure', 'chartreuse', 'teal'] -- constants(capitalized) are preferred --.
  imageMainColors: ['TEAL', 'YELLOW'],

  // `imageDominantColors`: An Array of strings, represents the color stringy value it must be any/all of the following only no other colors ['PURPLE', 'RED', 'ORANGE', 'PINK', 'GRASS_GREEN', 'YELLOW', 'AZURE', 'CHARTREUSE', 'TEAL'] or ['purple', 'red', 'orange', 'pink', 'grass_green', 'yellow', 'azure', 'chartreuse', 'teal'] -- constants(capitalized) are preferred --.
  imageDominantColors: ['pink', 'red'],

  // `metadata`: An Array of objects contains { key, operator, value, condition }, key and value are required for all metadata types, operator is required for single and multiple select metadatas only, condition is required in case operator is 'HAS' to add extra condition (another operator and value) to have metadata working properly, the value either the api_key or the internal unique value, the operators are [IS, NOT, HAS], condition operators are ['AND', 'OR', 'NOT'], all operators must be upper case, also for 'IS' operator we support empty and non empty options to filter all empty/non empty metadata
  metadata: [
    { key: 'cities', value: ['@itm_v1_08bbe7e5_4@', '@itm_v1_905066ed_9@'] },
    { key: 'brand', value: 'adidas' },
    { key: 'color', operator: 'IS', value: 'yellow' },
    { key: 'file', operator: 'HAS', value: 'png', condition: {operator: 'OR', value: 'jpg'} },
  ],

  // `labels`: An Array of strings, currently accepts 1 label only and the value should be label sid **with** (#).
  labels: ['#lbbp8dnyu'],

  // `folders`: An Array of strings, currently accepts 1 folder path only.
  folders: ['/hello-world']
}

Note: Constant values are better to be used as they are less prone for changes.

Note: To lock any of the above properties by using disabledFiltersAndSearch or forceFilters then you have to provide a value for the property to be locked.

search

Type: object.

Default: {}

Search object to be considered in the views have searching enabled and will be locked if disableFiltersAndSearch is true, consists of the following:

{
  // `query`: A string search query shown in the search input.
  query: '',

  // `tags`: An array of strings **contains** (#). The search input's tags used as advanced search on writing inside the input starting with (#) symbol and spaced tags are surrounded with double quote "" .
  tags: ['#Cairo', '"#Las Vegas"'],

  // `filters`: An Array of array consists of 2 strings, the 1st string refers to the filter's key and 2nd refers to the filter's value. The search input's filters used as advanced search on writing inside the input starting with (@) symbol.
  filters: [["key", "value"], ["filename", "Test file"]]
}

Note: To lock any of the above properties by using disabledFiltersAndSearch then you have to provide a value for the property to be locked at least empty value would be fine.

disableFiltersAndSearch

Type: boolean.

Default: false

If true then the only provided filters & search objects will be used as filters & search and disable both the filters & search input in UI dis-allowing the user to change/un-select any of them at all keeping the selected/provided filters not disabled but no changes possible for them.

Note: if search query is empty it won't be disabled if you need to disable it with no text provide an empty string ''.

Note: Enabling this option will dismiss applying the filters & search from the url queries.

forceFilters

If true then only the applied filters will be selected with the possibility to deselect them reaching 1 filter at least and the user won't be able to select other not-provided filters , false means no restrictions for filter selections.

Note: Enabling this option will deactivate the metadata filters. Metadata will be limited to the selected ones, and users will be compelled to choose at least one metadata option at all times.

Note: Enabling this option will dismiss applying the filters from the url queries.

disableFileResolutionFallback

Type: boolean.

Default: false

If true it will disable fallback request to load resolution info if not found in file details in grid/list layout.

hideLeftSideBar

Type: boolean.

Default: false

Hide the folders tree sidebar and its toggle icon.

defaultFieldKeyOfBulkEditPanel

Type: string.

Default: 'tags' fallbacks to 'title'

Assigns the default field of the bulk edit panel to be opened on showing the bulk edit panel as the focused/default field, it should be one of the general field keys (tags/title/description) or any field key -- lowered case -- of the shown file custom metadata fields (depends on the token).

Events

The explorer plugin 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:

objects-removed

Emitted when objects (folders/labels/collections/files) have been removed from the user's side.

params:

• removedObjectsUuids: An array of removed objects' uuids (for labels the sids will be the value).
• removedObjectsType: folders/collections/labels/files/items (files + folders).

example

filerobot.on("objects-removed", (removedObjectsUuids = [], objectsType) => {
  console.log(
    "Objects with the following Uuids have been removed:",
    removedObjectsUuids,
    objectsType
  );
});

folders-moved

Emitted when folder(s) are moved from path to another.

params:

• movedFoldersUuids: An array of folders uuids that are moved.
• newPath: A string of the new path which the folders moved to.

example

filerobot.on('objects-removed', (movedFoldersUuids = [], newPath) => {
  console.log(`Following folders uuids ${movedFoldersUuids.join(,)} are moved to this new path (${newPath}).`)
})