@scaleflex/widget-explorer

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

Usage

NPM

npm install --save @scaleflex/widget-explorer

YARN

yarn add @scaleflex/widget-explorer

then

import Explorer from '@scaleflex/widget-explorer'
...
...
...
scaleflexWidget.use(Explorer, propertiesObject)

CDN

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

const Explorer = window.ScaleflexWidget.Explorer
...
...
...
scaleflexWidget.use(Explorer, propertiesObject)

Plugin styles

import "@scaleflex/widget-core/dist/style.css";
import "@scaleflex/widget-explorer/dist/style.css";

or via the minified versions

import "@scaleflex/widget-core/dist/style.min.css";
import "@scaleflex/widget-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.

Explorer modes

Uploader mode (default mode)

The mode used for uploading files using your chosen/configured uploading provider to your token and chosen path.

how to?

Just initialize the widget normally and keep ExploreViewComponent property in Explorer plugin with a null/empty value.

// ScaleflexWidget.Core initializations
scaleflexWidget.use(Explorer, {
  // ...otherParams,
  ExploreViewComponent: null
})
scaleflexWidget.use(XHRUpload, {
  uploadToFolderPath: '/test'
})

Browser/Light-DAM mode

The mode used for browsing files/folders using the Explorer's main view and do some light-weight/quick functionalities like reading & writing files metadata in addition to uploading files.

how to?

Initialize the plugin with providing the component @scaleflex/widget-explorer/lib/components/ExploreView to the ExploreViewComponent property.

import ExploreView from '@scaleflex/widget-explorer/lib/components/ExploreView'
// ...scaleflexWidget and other plugins initializations

scaleflexWidget.use(Explorer, {
  // ...otherParams,
  ExploreViewComponent: ExploreView
})

Assets picker mode

Enabling the ability to browse the files/folders and preview them with and their metadata. Select files from the current token and do your own custom functionality after selecting the files.

how to?

1. Initialize the plugin and provide the component @scaleflex/widget-explorer/lib/components/ExploreView to the ExploreViewComponent property.
2. provide useAssetsPicker property with a true value.

import ExploreView from '@scaleflex/widget-explorer/lib/components/ExploreView'
// ...scaleflexWidget and other plugins initializations

scaleflexWidget.use(Explorer, {
  // ...otherParams,
  ExploreViewComponent: ExploreView,
  useAssetsPicker: true,
  hideDownloadButtonIcon: true
})

Note: please check the plugin's properties in-case you want to customize anything else related to any of the mentioned 3 modes above (some of the properties might work only for specific mode).

Properties

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

locale

Type: object.

Default: locales from scaleflexWidget'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
  }
}

config

Type: object

Default:

{
  config: {
    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 Scaleflex project:

foldersLimit

Type: number.

Default: 200

Number of folders to be retrieved with folders initial request.

maxCountOfSelectedFiles

Type: number.

Default: undefined

Maximum number of files that can be selected.

filesLimit

Type: number.

Default: 50

Number of files to be retrieved with files initial request.

rootFolderPath

Type: string.

Default: /

Overrides the root folder path when there is no list scope linked with the securityTemplateId or at least 2 folders or more in the list scope otherwise it has no effect.

Note: If the securityTemplateId has 2 folders at least, then the provided folder path must be one of these folders or one of their sub-folders.

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

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

defaultSearchSort

Type: object.

Default:

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

Customize the default selected sort option for search shown in the main view, applied for all the files shown regardless of the opened view.

The options available sorting

| Property | Type | Default | Description | | ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | text.by | string | name | Defines the default search sort by param, should be one of ['relevance', 'name', 'created_at', 'modified_at', 'size', 'type'] | | text.order | string | asc | Defines the default search sort order param, should be one of ['asc', 'desc'] |

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.

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. #scaleflex-widget-trigger-button or .scaleflex-widget-trigger-button

Multiple triggers are supported as click events.

Required if inline: false

target

Type: string.

Default: ``

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

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

Required if inline: false

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 uploads panel. 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 uploads panel. Aspect ratio of images is kept in case of image assets.

ExploreViewComponent

Type: ReactComponent.

Default: null

Expected value: @scaleflex/widget-explorer/lib/components/ExploreView

The view component that is responsible about showing the objects (folders/files...etc.) with the possibility to browse them and enable other functionalities.

mutedFilesUuids

Type: array.

Default: []

List of file UUIDs with the state "muted". These files cannot be selected or have any actions performed on them.

views

Type: array.

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

List of available views.

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

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

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

showImportFromDamButton

Type: boolean.

Default: false

If set to true, shows the Import from DAM button in the uploads panel to upload from DAM.

Note: this property requires ExploreViewComponent to be provided to be able to browse the objects.

disableUpload

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

closeAfterUploadStart

Type: boolean.

Default: false

Modal will close after upload is started.

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, if returned true then the default upload functionality won't be triggered.

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

Type: boolean.

Default: false

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

preventDownloadDefaultBehavior

Type: boolean.

Default: false

Prevent default behavior of download/export.

hideDownloadVariationsOption

Type: boolean.

Default: false

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

hideDownloadButtonIcon

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

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

imageEditorMode

Type: string.

Default: 'default'

Possible values: 'default' | 'cloudimage'

Set imageEditorMode for the image editor plugin.

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

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

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.

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.

hideDetailsViewButton

Type: boolean.

Default: false

Hides the asset details view button from the info icon in the right side of the breadcrumbs.

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)

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.

showScaleflexCopyright

Type: boolean.

Default: false

Hides Scaleflex 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.

assetsPickerModelTitle

Type: string.

Default: explorerTopSectionImportFileTitle

changing it's value changes the asset picker's model title

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.

hideDetailsSidebarButton

Type: boolean.

Default: false

If set to true, hide toggle details sidebar 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:

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

findAssetLocationEnabled

Type: boolean.

Default: true

Providing false, will hide Open asset location option in the context menu and file window.

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.

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:

| Property | Type | Default | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | date | object | { key: 'created', value: undefined, operator: ':' } | the date filter that combines both the option/type and range with the operator | | 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 | | licenseExpiry | number[] | string[] | string|string | undefined | The asset license expiry date, possible to be a value of the constant values or custom/specific dates |

Note: you could apply the filter value directly as in the following example, or you could add another customer filter operator by providing operator property. Ex. { date: { key: 'created', value: ['2022-02-04'], operator: '>' } } // means return the files created after that date.

Available filter operators are one of the following: ['>', '<', '<=', '>=', '!=', '=', ':', '~', '~~', '~~~', '~^', '~=']

{
  date: {
    key: 'created', // Either a string 'created'/'updated',
    // `value` 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 .
    value: ['2024-10-11'],
    // `operator` one of ['>', '<', '<=', '>=', '!=', '=', ':', '~', '~~', '~~~', '~^', '~=']
    operator: '>',
  },

  // Not used if `date` is used.
  // `dateOption`: Either a string 'CREATED'/'UPDATED' or integer 0/1.
  dateOption: 0,

  // Not used if `date` is used.
  // `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, condition, value, extraCondition, extraValue }, key and value are required for all metadata types, condition is for changing the operator used while assigning the metadata key to the value in the request, extraCondition is used when u have another condition shows up for the same metadata key/field ex. used 'CONTAINS_NOT' condition for multi select metadata field the extraCondition is 'NOT' only for now, the `value` either the api_key or the internal unique value, the conditions are ['IS', 'IS_NOT', 'CONTAINS', 'CONTAINS_NOT'], all conditions must be upper case, also for 'IS' condition 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', condition: 'IS', value: 'yellow' },
    { key: 'file', condition: 'CONTAINS_NOT', value: 'png', extraCondition: 'NOT', extraValue: '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'],

  // possible values: 'empty' | 'non-empty' | 'specific' (Specific date) | 'range' (Range of 2 dates) | ['', -1] (Before today) | [0] (today) | [1, ''] (After today) | [0, 2] (Within 7 days) | [0, 3] (Within 30 days)
  licenseExpiry: { value: [1, ''], operator: ':' }
}

 // filter with operator syntax example
 {
  [property]: {
    value: '...', // required, depends on the filter its type is provided
    operator: ':' // optional, if needed otherwise the default one is used ':'
    key: '...', // optional, if needed.
   }
 }

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.

Note: Operators are allowed to be provided for all the above filters but some of them are not supported on BE.

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:

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

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 the provided filters will always get applied with no possibility to remove from the UI, but the user still has the option to extend with more filters from the UI unless the provided filter accepts 1 value only.

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

forceMetadataInAdvancedMode

Type: boolean.

Default: false

If true it will open the metadata filter popup in advanced mode by default regardless of the user saved state. Otherwise it will fallback to the user's saved state if enabled, any filter with a condition property, or the filters are forced. If no case of the mentioned then it becomes in basic mode.

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

enableAIDescription

Type: boolean.

Default: false

Enables the generate description by AI in the description input of file window.

hideVariationsTab

Type: boolean.

Default: false

If true force hides the variations tab in file window panel.

hideMetadataTab

Type: boolean.

Default: false

If true force hides the metadata tab in file window panel.

hideFileSpecsMetadataFields

Type: boolean.

Default: false

Hides the metadata specs fields for the file on opening in the file window or details/info sidebar for the file (such as, labels, colors, logo and brand...etc.).

variationsHideManualSubTab

Type: boolean.

Default: false

If true force hides the manual sub-tab of variations tab in file window.

variationsShowAddPresetButton

Type: boolean.

Default: false

If true shows the add preset button inside the automatic tab if the user allowed to add.

hideTopBarAddFolderButton

Type: boolean.

Default: false

If true hides the add folder button on the topright.

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/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/labels/files/items (files + folders).

example

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

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