The file Explorer and media gallery plugin of the Filerobot Media Asset Widget.
npm install --save @filerobot/explorer
yarn add @filerobot/explorer
then
import Explorer from '@filerobot/explorer'
...
...
...
filerobot.use(Explorer, propertiesObject)
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)
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.
The Explorer supports multiple properties to customize the plugin according to your needs. Required attributes are marked with (Required).
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:
Type: string
.
Default: scaleflex
Your company name, used when sharing assets.
Type: number
.
Default: 200
Number of folders to be retrieved with folders initial request.
Type: number
.
Default: 50
Number of files to be retrieved with files initial request.
Type: string
.
Default: /
Override the root folder path.
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
Property | Type | Default | Description |
---|---|---|---|
by |
string |
name |
Defines the default sort by param, should be one of ['name', 'created_at', 'modified_at', 'size', 'type'] |
order |
string |
asc |
Defines the default sort order param, should be one of ['asc', 'desc'] |
Note: its value is considered only on plugin's install/mount.
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
}
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.
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
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
Type: number
| string
.
Default: 768
Width of the plugin as a number if specified in pixels or a percentage, eg. '50%'
Type: number
| string
.
Default: 538
Height of the plugin as a number if specified in px
or a percentage eg. '35%'
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.
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.
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.
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.
Type: string
.
Default: 'FOLDERS'
View which will be currently opened.
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
.
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
.
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.
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.
Type: boolean
.
Default: true
If set to false
, hides the top bar with Upload button, searchBar, create folder button and view button.
Type: boolean
.
Default: false
If set to true
, hides the Upload button at the top of the plugin.
Type: boolean
.
Default: false
Hides Search field at the top of the plugin.
Type: string
.
Default: null
A custom note displayed in the upload screen for drag&drop.
Type: string
.
Default: null
A custom hint displayed in the upload screen at the bottom.
Type: boolean
.
Default: false
Plugin modal will be closed when clicking outside of the modal.
Only relevant if inline: false
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
Type: boolean
.
Default: false
Modal will close after upload is finished.
Only relevant if inline: false
Type: function
.
Default: () => {}
A callback function that would be triggered when the user clicks on upload button that is shown in the uploads panel
Type: boolean
.
Default: false
Disables the informer plugin used to show warnings and errors.
Type: boolean
.
Default: false
Disables the thumbnail-generator plugin that generates image thumbnails.
Type: boolean
.
Default: true
If set to true
, disables scrolling for the document while the plugin modal is open.
Only relevant if inline: false
PREVIOUSLY: disableExportButton
& disableTopBarMainButton
Type: boolean
.
Default: false
Hides the download button shown in the action bar when selecting files.
PREVIOUSLY: preventExportDefaultBehavior
Type: boolean
.
Default: false
Prevent default behavior of download/export.
Type: boolean
.
Default: false
Hide transformation in download options in context menu and action bar.
PREVIOUSLY: hideExportButtonIcon
Type: boolean
.
Default: false
Hides the download/export button icon.
Type: boolean
.
Default: false
Hides the header bar, header bar contains breadcrumbs and other action buttons.
PREVIOUSLY: disableExportCropPanel
Type: boolean
.
Default: false
The crop button in the export options modal will be hidden.
Type: boolean
.
Default: false
Adds download=1
param to the CDN download link
Type: string
.
Default: null
Navigate to the collection view and open the provided collection.
Only relevant if Collections view is provided in views
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.
Type: string
.
Default: 'default'
Possible values: 'default' | 'cloudimage'
Set imageEditorMode for the image editor plugin.
Type: object
.
Default: null
Navigate to the provided item and focus on mount
Type: boolean
.
Default: false
Hides the modal after finish download/export.
Type: boolean
.
Default: false
Hides the modal after finish editing image.
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
Type: boolean
.
Default: true
Disable the modal's opening and closing.
Only relevant if inline: false
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
}
}
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
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.
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
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
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
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.
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.
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):
Property | Type | Default | Description |
---|---|---|---|
fileMore |
strings[] |
['LOCATE_FILE', 'REMOVE_BACKGROUND'] |
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 |
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 |
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)
Type: boolean
.
Default: true
Remove background option will appear in context menu.
Type: boolean
.
Default: false
Multiple files/folders selections will be disabled and only 1 file/folder possible to be selected.
Type: boolean
.
Default: false
The url query fmaw_path
won't be added/updated to the current url.
Type: boolean
.
Default: false
Hides filerobot copyright at the bottom of the plugin.
Type: boolean
.
Default: false
If set to true
, actions like deleting, editing, or downloading assets will not be allowed, explore and insert actions allowed.
Type: boolean
.
Default: false
If set to true
, disable the possiblity to select folder(s).
Type: boolean
.
Default: false
If set to true
, hide the folder item top options.
Type: boolean
.
Default: false
If set to true
, hide the file item top options.
Type: boolean
.
Default: false
If set to true
, hide toggle details tab button.
Type: boolean
.
Default: false
If set to true
, hide the selection buttons in the action bar.
Type: boolean
.
Default: false
If set to true
, disable the drag and drop actions to move assets/folders or upload
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)
Type: string
.
Default: fmaw_
Override the query params
Type: boolean
.
Default: false
Changes the design for the addFiles panel in uploads.
Type: boolean
.
Default: true
shows/hides sort button in Explorer.
Type: boolean
.
Default: false
Enables/disables the download of usage rights file with assets.
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
.
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.
Type: boolean
.
Default: false
Removes the add comment textarea from the comments tab.
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.
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.
Type: boolean
.
Default: true
expands faceted search sidebar by default.
Note: if facetedSearchEnabled
is false, this property will be ignored.
Type: array
.
Default: []
Array of metadata fields keys to be shown on faceted search.
Note: only exist filters will be shown.
Type: array
.
Default: []
Array of filters keys to be shown on faceted search.
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:
Property | Type | Default | Description |
---|---|---|---|
dateOption |
string | integer
|
CREATED === 0 |
the date option/type to filter with |
dateRange |
integer (1, 2, 3, 4, 5) | string | string['yyyy-mm-dd', 'yyyy-mm-dd']
|
undefined |
The date range used in filtering with the date option |
mimeTypes |
string[] |
undefined |
File mimetypes (in the UI called types) |
fileTypes |
string[] |
undefined |
File types (in the UI called Format) |
size |
integers[minMB, maxMB] |
undefined |
the date option/type to filter with |
tags |
string[] |
undefined |
The tags that should be contain in the files, the values consist of tag sids without # |
imageOrientations |
string[] |
undefined |
The image orientation values |
imageResolutions |
string[] |
undefined |
The image resolution values |
imageFaces |
string[] |
undefined |
The number of faces found in an image |
imageMainColors |
string[] |
undefined |
The main colors of the image which represents significant proportion in the image |
imageDominantColors |
string[] s |
undefined |
The dominant colors of the image |
metadata |
{ key: string, operator: string|undefined ,value: string|string[], condition:{ {operator:string ,value: string|string[]}| undefined } |
undefined |
The metadata objects used in filtering |
labels |
string[] |
undefined |
The label sids without # used in filtering files contain that value (Only 1 label/value is supported currently) -- doesn't work in labels view |
folders |
string[] |
undefined |
The path of the folders to be used while filtering (Only 1 folder/value is supported currently) -- doesn't work in folders view |
{
// `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
orforceFilters
then you have to provide a value for the property to be locked.
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:
Property | Type | Default | Description |
---|---|---|---|
query |
string |
undefined |
The search query string shown in the search input and used in searching, if using with disabledFiltersAndSearch then the property must contain a stringy value to lock the search or at least empty text ''
|
tags |
string[] |
undefined |
The search tags found in the search input as advanced search prefxed with symbol (#) -- different from tags of filters -- |
filters |
string[][] |
undefined |
The advanced search filters found also in search input by prefixing with the symbol (@) the value consists of array of 2 strings array the first string represents the key, second string represents the value and whole array represents an item -- different from filters --. |
{
// `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.
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.
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.
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.
Type: boolean
.
Default: false
Hide the folders tree sidebar and its toggle icon.
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).
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:
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
);
});
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}).`)
})