@scaleflex/widget-core 4.0.5 → 4.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +660 -552
  3. package/lib/index.js +4 -4
  4. package/package.json +3 -3
package/README.md CHANGED
@@ -4,9 +4,6 @@
4
4
  > This is the successor of [Filerobot Media Asset Widget (FMAW) - V3](https://www.npmjs.com/package/@filerobot/core).
5
5
 
6
6
 
7
- > This package contains both the main/global readme for the whole widget and the readme for [@scaleflex/widget-core](#scaleflexwidget-core) plugin itself.
8
-
9
-
10
7
  [![Plugins][plugins-image]](#plugins)
11
8
  [![Website][filerobot-image]][sfx-url]
12
9
  [![Version][filerobot-version]][version-url]
@@ -31,691 +28,647 @@ Various plugins like for example the [**Scaleflex Image Editor**](https://www.np
31
28
  <details>
32
29
  <summary>Table of contents</summary>
33
30
 
34
- - [Scaleflex Media Asset Widget (SMAW)](#scaleflexwidget-media-asset-widget-fmaw)
35
- - [Main features:](#main-features)
36
- - [Installation](#installation)
37
- - [Quickstart](#quickstart)
38
- - [Demo](#demo)
39
- - [React](#react)
40
- - [Vanilla (plain) JS](#vanilla-plain-js)
41
- - [Modules](#modules)
42
- - [Plugins](#plugins)
43
- - [UI Elements](#ui-elements)
44
- - [Upload connectors](#upload-connectors)
45
- - [Destinations](#destinations)
46
- - [Miscellaneous](#miscellaneous)
47
- - [Widget modes](#modes)
48
- - [@scaleflex/widget-core](#scaleflexwidget-core)
31
+
32
+ - [Scaleflex Media Asset Widget (SMAW)](#scaleflex-media-asset-widget-smaw)
33
+ - [What is the SMAW?](#what-is-the-smaw)
34
+ - [Installation (minimal drag and drop upload zone)](#installation-minimal-drag-and-drop-upload-zone)
35
+ - [ReactJS (over package manager)](#reactjs-over-package-manager)
36
+ - [Vanilla JS (over CDN link, containing all plugins)](#vanilla-js-over-cdn-link-containing-all-plugins)
37
+ - [Widget modes and use cases](#widget-modes-and-use-cases)
38
+ - [Core package and plugins](#core-package-and-plugins)
39
+ - [Quick Start](#quick-start)
40
+ - [Uploader mode (as modal to upload files in the Scaleflex DAM)](#uploader-mode-as-modal-to-upload-files-in-the-scaleflex-dam)
41
+ - [Enabling upload connectors for import from external storage sources](#enabling-upload-connectors-for-import-from-external-storage-sources)
42
+ - [Adding the progress panel](#adding-the-progress-panel)
43
+ - [Customizing the Uploader and listening to events](#customizing-the-uploader-and-listening-to-events)
44
+ - [Asset Picker mode (for searching and selecting assets from the Scaleflex DAM)](#asset-picker-mode-for-searching-and-selecting-assets-from-the-scaleflex-dam)
45
+ - [**Inserting selected selected assets into your application**](#inserting-selected-selected-assets-into-your-application)
46
+ - [Customizing the Asset Picker experience](#customizing-the-asset-picker-experience)
47
+ - [Asset Manager mode (light DAM)](#asset-manager-mode-light-dam)
48
+ - [Documentation (Core package)](#documentation-core-package)
49
+ - [ReactJS (over package manager)](#reactjs-over-package-manager-1)
50
+ - [Installation](#installation)
49
51
  - [Usage](#usage)
50
- - [Properties](#properties)
51
- - [Events](#events)
52
+ - [Vanilla JS (over CDN link, containing all plugins)](#vanilla-js-over-cdn-link-containing-all-plugins-1)
53
+ - [Installation](#installation-1)
54
+ - [Usage](#usage-1)
55
+ - [Parameters](#parameters)
56
+ - [General parameters relevant for all modes](#general-parameters-relevant-for-all-modes)
57
+ - [Uploader-related properties](#uploader-related-properties)
58
+ - [Events and Callbacks](#events-and-callbacks)
59
+ - [Plugin APIs (advanced use)](#plugin-apis-advanced-use)
52
60
  - [License](#license)
53
61
  </details>
54
62
 
55
- ## Main features:
63
+ # What is the SMAW?
56
64
 
57
- - Single and multiple file upload into a Scaleflex storage container (project)
58
- - Upload via Drag & Drop or Copy & Paste
59
- - Upload from 3rd party storages such as Google Drive, Dropbox, OneDrive, Facebook, Instagram
60
- - Webcam and screen cast integration to upload realtime videos and screen recordings
61
- - File explorer and media gallery with file management capabilites (folder creation, file move, rename, ...)
62
- - Zipped download of multiple files
63
- - File versioning with history, version browsing
64
- - File and media asset sharing via accelerated CDN links
65
- - Media gallery with powerful search capabilities based on tags and customizable metadata (taxonomy)
66
- - AI-based tagging of images
67
- - Embedded Scaleflex Image Editor for inline image editing
68
- - Image annotator and comments for collaboration
69
- - Image variant generator with customizable template to generate optimal sizes for social media posts (example)
70
- - Post-upload video transcoding for delivering HLS & DASH playlists for adaptive streaming
71
- - On-the-fly image resizing via [Cloudimage](https://cloudimage.io)
65
+ The **Scaleflex Media Asset Widget (SMAW)** is a combined file uploader and media library browser. It is the user-facing gateway to your Scaleflex Digital Asset Management (DAM), allowing users to upload files into a central storage or search in the DAM library, all through a unified widget from your host application.
66
+ It can be extended and customized by a robust ecosystem of [plugins](https://scaleflexhq.atlassian.net/wiki/spaces/FIL/pages/1677557765/Scaleflex+Media+Asset+Widget+SMAW#Architecture%3A-core-packages-and-plugins).
72
67
 
73
- The widget can be integrated in a web page HTML element, as a pop-up modal on button click.
68
+ > Check out the [interactive sandbox](https://scaleflex.cloudimg.io/v7/plugins/widget/v4/demo/index.html?func=proxy) to try the different widget modes and play with its parameters.
74
69
 
75
- ## Installation
70
+ > You need a Scaleflex DAM account to use the SMAW. Get one [here](https://www.scaleflex.com/filerobot-free-trial) for free.
76
71
 
77
- The widget's architecture contains the [**Core**](#scaleflexwidget-core) module and various [**plugins**](#plugins). Each [**plugin**](#plugins) has its own dedicated documentation.
72
+ **Key features:**
78
73
 
79
- **CDN links to JS and CSS (containing all plugins)**
74
+ - **Flexible file upload:** users can upload single or multiple files into the Scaleflex DAM tenant via drag & drop, copy-paste, or file picker. The widget supports advanced sources (Device camera or screen recording) as well as third-party integrations (Google Drive, Dropbox, OneDrive, Instagram, Facebook, etc.) for uploading.
75
+ - **Media library & asset management:** provides a built-in file explorer and media gallery with folder navigation, searching by tags/metadata, asset preview, and basic file operations (rename, move, delete, etc.). Users can even download multiple files as a ZIP and view version history for assets.
76
+ - **Inline Editing & Processing:** includes optional plugins like the `@scaleflex/widget-image-editor` for editing images (crop, resize, filters, etc.) directly in the browser, as well as video processing or transformations on the fly.
77
+ - **Collaboration & Sharing:** files uploaded via the widget are immediately available in the DAM, with accelerated delivery links (CDN URLs) for sharing. Features like AI-powered tagging, commenting/annotations on images, and usage rights metadata can be enabled to enrich collaboration.
80
78
 
81
- - Add the following CSS file before the end of `</head>` in your `HTML` file
79
+ The widget is highly **configurable** and **modular** – plugins are optional for additional functionality, keeping it lightweight. It can be rendered inline in a page element, or as a pop-up modal triggered by user action, such as a button click.
82
80
 
83
- ```html
84
- <link
85
- rel="stylesheet"
86
- type="text/css"
87
- href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css"
88
- />
89
- ```
81
+ ## Installation (minimal drag and drop upload zone)
90
82
 
91
- - Add the following JS file before the end of `</body>` in your `HTML` file.
83
+ The minimal setup to display the widget as a drag and drop upload zone requires the `@scaleflex/widget-core` ([**Core**](https://www.npmjs.com/package/@scaleflex/widget-core#documentation)), `@scaleflex/widget-explorer` ([**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer)) and `@scaleflex/widget-xhr-upload` ([**Uploader**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload)) packages.
92
84
 
93
- ```html
94
- <script
95
- type="text/javascript"
96
- src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"
97
- ></script>
98
- ```
99
-
100
- > The CDN versions of the library contains all plugins whereas npm gives you flexibility to include only plugins/modules you need to have lighter lib files. For example, you can just use the [**Core**](https://www.npmjs.com/package/@scaleflex/widget-core/#scaleflexwidget-core) module and the [**XHR Upload**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload/#scaleflexwidgetxhr-upload) plugin to integrate a simple uploader to your application, without file explorer, media gallery and image editor.
101
-
102
- ## Quickstart
85
+ Below is a simple installation example in both ReactJS and Vanilla JS.
103
86
 
104
- ### Demo
87
+ ### ReactJS (over package manager)
105
88
 
106
- [See the SMAW in action here](https://cdn.scaleflex.com/plugins/widget/v4/demo/index.html).
89
+ npm
107
90
 
108
- The following implementation examples build a SMAW for uploading files, showing the [**Scaleflex Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer/#scaleflexwidgetexplorer) as a file explorer/media gallery, enabling the [**Webcam**](https://www.npmjs.com/package/@scaleflex/widget-webcam/#scaleflexwidgetwebcam) for capturing photos and videos and the [**Scaleflex Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor/#scaleflexwidgetimage-editor) for editing images inline.
109
-
110
- At minima, you will need the following 3 packages to display a basic SMAW:
91
+ ```bash
92
+ npm install --save @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
93
+ ```
111
94
 
112
- - [**Core**](#scaleflexwidget-core)
113
- - [**Scaleflex Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer/#scaleflexwidgetexplorer)
114
- - [**XHR Upload**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload/#scaleflexwidgetxhr-upload)
95
+ yarn
115
96
 
116
- You can obtain a `container` name and `securityTemplateId` from your [Scaleflex](https://www.scaleflex.com/) account in order for files to be uploaded in the specified Scaleflex storage container (also called project in Scaleflex).
97
+ ```bash
98
+ yarn add @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
99
+ ```
117
100
 
118
- ### React
101
+ Sample code to instantiate the widget:
119
102
 
120
103
  ```js
121
- import ScaleflexWidget from "@scaleflex/widget-core";
122
- import Explorer from "@scaleflex/widget-explorer";
123
- import XHRUpload from "@scaleflex/widget-xhr-upload";
124
- import ImageEditor from "@scaleflex/widget-image-editor";
125
- import Webcam from "@scaleflex/widget-webcam";
104
+ import { useEffect, useRef } from 'react';
105
+ import ScaleflexWidget from '@scaleflex/widget-core';
106
+ import Explorer from '@scaleflex/widget-explorer';
107
+ import XHRUpload from '@scaleflex/widget-xhr-upload';
126
108
 
127
- import "@scaleflex/widget-core/dist/style.min.css";
128
- import "@scaleflex/widget-explorer/dist/style.min.css";
129
- import "@scaleflex/widget-image-editor/dist/style.min.css";
130
- import "@scaleflex/widget-webcam/dist/style.min.css";
109
+ // Import base styles (Core first, then Explorer - included in the packages above)
110
+ import '@scaleflex/widget-core/dist/style.min.css';
111
+ import '@scaleflex/widget-explorer/dist/style.min.css';
131
112
 
132
- const App = () => {
133
- const scaleflexWidget = useRef(null);
113
+ function App() {
114
+ const scaleflexWidgetRef = useRef(null);
134
115
 
135
116
  useEffect(() => {
136
- const demoContainer = "scaleflex-tests-v5a";
137
- const demoSecurityTemplateId = "......";
138
-
139
- scaleflexWidget.current = ScaleflexWidget({
140
- securityTemplateId: demoSecurityTemplateId,
141
- container: demoContainer,
142
- dev: false,
143
- })
144
- .use(Explorer, { target: "#scaleflex-widget", inline: true })
145
- .use(XHRUpload)
146
- .use(ImageEditor)
147
- .use(Webcam);
148
-
149
- return () => {
150
- scaleflexWidget.current.close();
151
- };
117
+ // Initialize the core widget
118
+ scaleflexWidgetRef.current = ScaleflexWidget({
119
+ container: "YOUR_CONTAINER",
120
+ securityTemplateId: "YOUR_SECURITY_TEMPLATE_ID"
121
+ });
122
+
123
+ // Use the Explorer UI in default uploader mode, and enable XHR upload
124
+ scaleflexWidgetRef.current
125
+ .use(Explorer, { target: "#widget-container", inline: true })
126
+ .use(XHRUpload);
127
+
128
+ // Cleanup on unmount (close widget to free resources)
129
+ return () => scaleflexWidgetRef.current.close();
152
130
  }, []);
153
131
 
154
- return (
155
- <div>
156
- <h1>React Example</h1>
157
- <div id="scaleflex-widget" />
158
- </div>
159
- );
160
- };
161
-
162
- render(<App />, document.getElementById("app"));
163
- ```
164
-
165
- ### Vanilla (plain) JS
132
+ return <div id="widget-container" style={{ width: '800px', height: '600px' }}></div>;
133
+ }
166
134
 
167
- ```html
168
- <html>
169
- <head>
170
- <link
171
- rel="stylesheet"
172
- type="text/css"
173
- href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css"
174
- />
175
- </head>
176
- <body>
177
- <div id="scaleflex-widget"></div>
178
-
179
- <script src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"></script>
180
-
181
- <script type="text/javascript">
182
- const widget = window.ScaleflexWidget;
183
- const demoContainer = "scaleflex-tests-v5a";
184
- const demoSecurityTemplateId = "......";
185
-
186
- const scaleflexWidget = widget.Core({
187
- securityTemplateId: demoSecurityTemplateId,
188
- container: demoContainer,
189
- dev: false, // optional, default: false
190
- });
191
- const Explorer = widget.Explorer;
192
- const XHRUpload = widget.XHRUpload;
193
- const ImageEditor = widget.ImageEditor;
194
- const Webcam = widget.Webcam;
195
-
196
- scaleflexWidget
197
- .use(Explorer, { target: "#scaleflex-widget", inline: true })
198
- .use(XHRUpload)
199
- .use(ImageEditor)
200
- .use(Webcam);
201
- </script>
202
- </body>
203
- </html>
135
+ export default App;
204
136
  ```
205
137
 
206
- ## Modules
138
+ In the example above, the Explorer plugin is configured with `inline: true` and a DOM element `#widget-container` as its target. This widget will be rendered inline in that element (as opposed to a modal). The XHRUpload plugin is enabled with default settings to handle file uploads trough the Scaleflex DAM API.
207
139
 
208
- The Scaleflex Core module: [**Core**](#scaleflexwidget-core)
140
+ ### Vanilla JS (over CDN link, containing all plugins)
209
141
 
210
- ## Plugins
142
+ - add the following CSS file before the end of `</head>` in your `HTML` file
211
143
 
212
- ### UI Elements
213
-
214
- - [**Scaleflex Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer/#scaleflexwidgetexplorer): Scaleflex File Explorer provides different modes to achieve different capabilities like basic uploader, light DAM for managing your assets or even a file picker for your assets with customizing your functionality.
215
-
216
- Following plugins can be added to augment the Scaleflex's File Explorer capabilities:
217
-
218
- - [**Progress Panel**](https://www.npmjs.com/package/@scaleflex/widget-progress-panel/#scaleflexwidgetprogress-panel): displays upload, download, video activities and other processes status in a progress panel.
219
-
220
- - [**Informer**](https://www.npmjs.com/package/@scaleflex/widget-informer/#scaleflexwidgetinformer): displays pop-up messages/statuses related to file operations.
221
-
222
- - [**Scaleflex Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor/#scaleflexwidgetimage-editor): inline image editor with functionalities such as `filters, crop, resizing, watermark, collages, etc...`. Also used by other features of the Widget such as the variant generator and export function.
223
-
224
- - [**Pre-Upload Image Processor**](https://www.npmjs.com/package/@scaleflex/widget-preupload-processors/#scaleflexwidgetpreupload-processors): ability to resize a large image into the storage container before upload.
225
-
226
- ### Upload connectors
227
-
228
- - [**Google Drive**](https://www.npmjs.com/package/@scaleflex/widget-google-drive/#scaleflexwidgetgoogle-drive): import files from Google Drive.
229
-
230
- - [**Dropbox**](https://www.npmjs.com/package/@scaleflex/widget-dropbox/#scaleflexwidgetdropbox): import files from Dropbox.
231
-
232
- - [**Box**](https://www.npmjs.com/package/@scaleflex/widget-box/#scaleflexwidgetbox): import files from Box.
144
+ ```html
145
+ <link
146
+ rel="stylesheet"
147
+ type="text/css"
148
+ href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css"
149
+ />
150
+ ```
233
151
 
234
- - [**Instagram**](https://www.npmjs.com/package/@scaleflex/widget-instagram/#scaleflexwidgetinstagram): import images and videos from Instagram.
152
+ - add the following JS file before the end of `</body>` in your `HTML` file.
235
153
 
236
- - [**Facebook**](https://www.npmjs.com/package/@scaleflex/widget-facebook/#scaleflexwidgetfacebook): import images and videos from Facebook.
154
+ ```html
155
+ <script
156
+ type="text/javascript"
157
+ src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"
158
+ ></script>
159
+ ```
237
160
 
238
- - [**OneDrive**](https://www.npmjs.com/package/@scaleflex/widget-onedrive/#scaleflexwidgetonedrive): import files from Microsoft OneDrive.
161
+ Sample code to instantiate the widget:
239
162
 
240
- - [**Import From URL**](https://www.npmjs.com/package/@scaleflex/widget-url/#scaleflexwidgeturl): import direct URLs from anywhere on the web.
163
+ ```html
164
+ <!-- Include CSS in <head> -->
165
+ <link rel="stylesheet" href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css" />
166
+
167
+ <!-- Container element for the widget -->
168
+ <div id="widget-container"></div>
169
+
170
+ <!-- Include JS in <body> -->
171
+ <script src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"></script>
172
+ <script>
173
+ // Access global widget object
174
+ const Widget = window.ScaleflexWidget;
175
+ // Initialize core
176
+ const scaleflexWidget = Widget.Core({
177
+ container: "YOUR_CONTAINER",
178
+ securityTemplateId: "YOUR_SECURITY_TEMPLATE_ID",
179
+ // dev: false
180
+ });
181
+ // Add plugins
182
+ scaleflexWidget
183
+ .use(Widget.Explorer, { target: "#widget-container", inline: true })
184
+ .use(Widget.XHRUpload);
185
+ </script>
186
+ ```
241
187
 
242
- - [**Webcam**](https://www.npmjs.com/package/@scaleflex/widget-webcam/#scaleflexwidgetwebcam): capture photos or videos from the device's camera and upload them to the Scaleflex storage container.
188
+ This achieves the same outcome as the ReactJS example: an inline file explorer/uploader within the `#widget-container` div.
243
189
 
244
- - [**Screen Capture**](https://www.npmjs.com/package/@scaleflex/widget-screen-capture/#scaleflexwidgetscreen-capture): device screen recorder.
190
+ > In production, you might load the widget only when needed (e.g., on a button click, or in a modal). The above examples instantiate it immediately for simplicity. Also ensure you include the CSS file *before* the JS file to properly load styles.
245
191
 
246
- - [**Attach Drag & Drop zone**](https://www.npmjs.com/package/@scaleflex/widget-attach-dnd/#scaleflexwidgetattach-dnd): Plugin for attaching drag & drop zone for some specific HTML element in your page.
192
+ ## Widget modes and use cases
247
193
 
248
- - [**Pixaforge**](https://www.npmjs.com/package/@scaleflex/widget-pixaforge/#scaleflexwidgetpixaforge): Plugin for importing free images & icons from Pixaforge that contains free gallery for different categories & tags.
194
+ The SMAW supports multiple **modes** to fit different use cases:
249
195
 
250
- - [**Canva**](https://www.npmjs.com/package/@scaleflex/widget-canva/#scaleflexwidgetcanva): Create your own design & customize it then upload it through the widget on the go by integrating this plugin inside the widget.
196
+ - **Uploader**: *File upload interface (default mode).* Enables your users to upload files to your DAM. The widget shows an upload panel (with drag & drop zone) and optionally allows selecting sources (local files or connected cloud sources).
197
+ Use case: a web app where users upload media (images/videos) or documents (UGC) into a central library.
198
+ [Demo](https://scaleflex.cloudimg.io/v7/plugins/widget/v4/demo/index.html?func=proxy#uploader-section) | [Example code](https://scaleflexhq.atlassian.net/wiki/spaces/FIL/pages/1677557765/Scaleflex+Media+Asset+Widget+SMAW#Uploader-mode-(as-modal-to-upload-files-in-the-Scaleflex-DAM))
251
199
 
252
- - [**Unsplash**](https://www.npmjs.com/package/@scaleflex/widget-unsplash/#scaleflexwidgetunsplash): import files from unsplash.
200
+ - **Asset Picker**: *Media selector dialog.* Enables your users to browse existing assets in the DAM (without the ability to modify or delete them) and select one or more assets for use in the application the widget is integrated into.
201
+ Use case: content editors or e-commerce managers working in a CMD search for product assets in the DAM and insert them into an editorial page or product details page.
202
+ [Demo](https://scaleflex.cloudimg.io/v7/plugins/widget/v4/demo/index.html?func=proxy#assets-picker-section) | [Example code](https://scaleflexhq.atlassian.net/wiki/spaces/FIL/pages/1677557765/Scaleflex+Media+Asset+Widget+SMAW#Asset-Picker-mode-(for-searching-and-selecting-assets-from-the-Scaleflex-DAM))
253
203
 
254
- ### Destinations
204
+ - **Asset Manager (aka Light DAM)**: *Embedded light DAM library.* Enables a lightweight DAM experience inside your application – users can navigate folders and files, upload new files, add tags, edit metadata and move/rename/delete assets.
205
+ Use case: users of your application need DAM-like functionality to upload and tag assets, set their metadata and view advanced information before using assets.
206
+ [Example code](https://scaleflexhq.atlassian.net/wiki/spaces/FIL/pages/1677557765/Scaleflex+Media+Asset+Widget+SMAW#Asset-Manager-mode-(light-DAM))
255
207
 
256
- - [**XHR Upload**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload/#scaleflexwidgetxhr-upload): handles multipart file upload.
208
+ ## Core package and plugins
257
209
 
258
- - [**Tus**](https://www.npmjs.com/package/@scaleflex/widget-Tus/#scaleflexwidgettus): applies resumable upload (BE must support that).
210
+ The SMAW is built as a modular system of packages. To get started, you’ll need the `@scaleflex/widget-core` [**Core**](https://www.npmjs.com/package/@scaleflex/widget-core#documentation) and `@scaleflex/widget-explorer` [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) packages. From there, you can extend the widget’s capabilities with a range of optional packages that add extra functionality.
259
211
 
260
- ### Miscellaneous
212
+ - `@scaleflex/widget-core` (aka [**Core**](https://www.npmjs.com/package/@scaleflex/widget-core#documentation)) REQUIRED : this Core handles initialization, global settings, and communication with the Scaleflex DAM API. You always start by creating the core widget instance with the identifier of your *DAM container* (aka project token) and *security credentials*.
213
+ - `@scaleflex/widget-explorer` (aka [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer)) REQUIRED: the Explorer provides the main file explorer interface (thumbnails, folder tree, etc.) and implements the various [modes](https://scaleflexhq.atlassian.net/wiki/spaces/FIL/pages/1677557765/Scaleflex+Media+Asset+Widget+SMAW#%5BinlineExtension%5DModes-and-Use-Cases) mentioned above. (Uploader/Picker/Manager). Following UI plugins are automatically imported for extra functionality:
214
+ - `@scaleflex/widget-progress-panel` (aka [**Progress Panel**](https://www.npmjs.com/package/@scaleflex/widget-progress-panel)) OPTIONAL: a multi-functional progress bar to show upload/download progress
215
+ - `@scaleflex/widget-image-editor` (aka [**Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor)) OPTIONAL: a web-based image editor for basic edits (resize, crop, remove background, expand background with AI, remove objects with AI, …). This plugin is powered by the open-source [Scaleflex Image Editor](https://github.com/scaleflex/filerobot-image-editor#readme) plugin.
216
+ - `@scaleflex/widget-xhr-upload` (aka [**Uploader**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload)) OPTIONAL: the Uploader provides an UI interface (modal or drag and drop zone) to upload files in the Scaleflex DAM from your host application. It perform standard HTTPS multipart uploads agains the Scaleflex DAM API. Following optional UI plugins for extra functionality are available:
217
+ - `@scaleflex/widget-webcam` (aka [**Webcam**](https://www.npmjs.com/package/@scaleflex/widget-webcam)) OPTIONAL: enables the user to capture photos/videos with his camera and upload them into the DAM
218
+ - `@scaleflex/widget-screen-capture` (aka [**Screen Capture**](https://www.npmjs.com/package/@scaleflex/widget-screen-capture)) OPTIONAL: enables the user to screenshot or record his screen and upload the resulting image or video into the DAM
219
+ - `@scaleflex/widget-url` (aka [**Url**](https://www.npmjs.com/package/@scaleflex/widget-image-editor)): enables the user to import an asset from an external URL link
220
+ - **Upload connectors** OPTIONAL: these connectors enable users to import files from external storage providers, such as Box, Dropbox, Google Drive, OneDrive, etc. Users will need to authenticate with their accounts to the 3rd party service using oAuth:
221
+ - [Box](https://www.npmjs.com/package/@scaleflex/widget-box)
222
+ - [Dropbox](https://www.npmjs.com/package/@scaleflex/widget-dropbox)
223
+ - [Facebook](https://www.npmjs.com/package/@scaleflex/widget-facebook)
224
+ - [Google Drive](https://www.npmjs.com/package/@scaleflex/widget-google-drive)
225
+ - [Instagram](https://www.npmjs.com/package/@scaleflex/widget-instagram)
226
+ - [OneDrive](https://www.npmjs.com/package/@scaleflex/widget-onedrive)
227
+ - [Canva](https://www.npmjs.com/package/@scaleflex/widget-canva): enables the user to open the Canva editor inside your application and import a design into the widget for uploading into the DAM.
228
+ - [Unsplash](https://www.npmjs.com/package/@scaleflex/widget-unsplash): enables the user to search free images and videos in the Unsplash stock library and import them into the widget for uploading into your DAM
229
+ - `@scaleflex/widget-tus` (aka **tus Uploader**): enable resumable/chunked uploads. Recommended if users need to upload many files or very large files (> 1 Gb) into the Scaleflex DAM. This requires activation by Scaleflex on your DAM tenant, please [contact support](mailto:hello@scaleflex.com).
261
230
 
262
- - [**Thumbnail Generator**](https://www.npmjs.com/package/@scaleflex/widget-thumbnail-generator/#scaleflexwidgethumbnail-generator): thumbnail generator for different files to be used as file preview.
263
231
 
264
- ## Widget modes
232
+ # Quick Start
265
233
 
266
- Go to the [Explorer plugin modes](https://www.npmjs.com/package/@scaleflex/widget-explorer#explorermodes) as it is responsible about utilizing the different modes of the widget.
234
+ Before implementing the SMAW, ensure you have the following Scaleflex DAM credentials ([here](https://www.scaleflex.com/filerobot-free-trial) to get some for free !).
267
235
 
268
- ## `@scaleflex/widget-core`
236
+ - **Container** (aka project token)**:** a Scaleflex DAM *container* (project) name or token. This identifies the DAM tenant where assets will be uploaded or fetched. You can create a project and get the container token from the [Scaleflex Asset Hub](https://hub.scaleflex.com/) (requires a Scaleflex account).
237
+ - **Security Template ID:** ID of a Security Template defined in your DAM. This is required for authentication – the widget uses it to request a temporary access token with specific permissions to interact with the DAM. Create a Security Template [here](https://hub.scaleflex.com/settings/project/access/security-templates) (requires a Scaleflex account) and define its scope (like OAuth2 scopes). Make sure the Security Template grants the rights needed for your use case (e.g. upload rights for Uploader mode, list/view rights for Asset Picker mode, etc.).
269
238
 
270
- The core module of the Scaleflex Media Asset Widget. This module contains all common settings shared across all SMAW plugins and can be used standalone in your upload workflows to interact with Scaleflex DAM.
239
+ ## Uploader mode (as modal to upload files in the Scaleflex DAM)
271
240
 
272
- ## Usage
241
+ > Use case: a web app where users upload media (images/videos) or documents (UGC) into a central library.
273
242
 
274
- ### NPM
243
+ You can implement the SMAW in **Uploader** mode in two ways:
275
244
 
276
- ```bash
277
- npm install --save @scaleflex/widget-core
278
- ```
245
+ - **as a modal:** the widget opens when triggered (e.g., by a button), and appears as a modal
246
+ - **inline embedded in page:** the widget is always visible in a given page section, acting as an upload panel or drop zone
279
247
 
280
- ### YARN
248
+ By default (`inline: false`), the [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) plugin will display as a modal. You must provide a trigger selector in the [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) options to open the modal on user action. For example, you might have a button in your HTML:
281
249
 
282
- ```bash
283
- yarn add @scaleflex/widget-core
250
+ ```html
251
+ <!-- ... -->
252
+ <button id="open-uploader">Upload Assets</button>
253
+ <!-- ... -->
284
254
  ```
285
255
 
286
- then
256
+ Add the following code to the widget’s instantiation:
287
257
 
288
258
  ```js
289
- import ScaleflexWidget from '@scaleflex/widget-core'
290
- ...
291
- ...
292
- ...
293
- const scaleflexWidget = ScaleflexWidget(propertiesObject)
259
+ // ...
260
+ scaleflexWidget.use(Explorer, {
261
+ trigger: "#open-uploader", // CSS selector for the trigger element
262
+ target: "body" // where to attach the modal in the DOM
263
+ });
264
+ // ...
294
265
  ```
295
266
 
296
- ### CDN
297
-
298
- If installed via the [CDN link](../@scaleflex/widget-core#installation), the plugin is inside the `ScaleflexWidget` global object as `ScaleflexWidget.Core`
299
-
300
- ```js
301
- const scaleflexWidgetCore = window.ScaleflexWidget.Core
302
- ...
303
- ...
304
- ...
305
- const scaleflexWidget = scaleflexWidgetCore(propertiesObject)
306
- ```
267
+ Now, when the user clicks op the *Upload Assets* button, the widget modal will open in the middle of the page. The trigger can be any (or multiple) valid selectors. In this example the target is *body*, but usually it will be a specific DOM element in your page.
307
268
 
308
- ### Module's styles
269
+ While the modal is open, users can drag and drop files in the modal for upload or select form their device. No additional plugins (such as [Google Drive](https://www.npmjs.com/package/@scaleflex/widget-google-drive), [Box](https://www.npmjs.com/package/@scaleflex/widget-box) or [Unsplash](https://www.npmjs.com/package/@scaleflex/widget-unsplash)) are enabled in this example.
309
270
 
310
- ```js
311
- import "@scaleflex/widget-core/dist/style.css";
312
- ```
271
+ ### Enabling upload connectors for import from external storage sources
313
272
 
314
- or via the minified versions
273
+ To enable import from [Google Drive](https://www.npmjs.com/package/@scaleflex/widget-google-drive), [Box](https://www.npmjs.com/package/@scaleflex/widget-box) or [Unsplash](https://www.npmjs.com/package/@scaleflex/widget-unsplash), etc., you need to add the relevant **Upload connectors**:
315
274
 
316
275
  ```js
317
- import "@scaleflex/widget-core/dist/style.min.css";
318
- ```
319
-
320
- > The Core's styles must be imported before the scaleflexWidget's plugins' styles.
321
-
322
- ## Properties
323
-
324
- Required attributes are marked with **_(Required)_**.
325
-
326
- ### `container`
327
-
328
- <u>Type:</u> `string` **_Required_**.
329
-
330
- <u>Default:</u> `undefined`
331
-
332
- The container token (Scaleflex token) that will be used in all the widget's modes & plugins ex. (listing files/folders, uploading, renaming, deleting...etc.). Register for an account at [scaleflex.com](www.scaleflex.com) to obtain a token.
333
-
334
- ### `securityTemplateId`
335
-
336
- **PREVIOUSLY**: `securityTemplateID`
337
-
338
- <u>Type:</u> `string` **_Required_**.
339
-
340
- <u>Default:</u> `undefined`
341
-
342
- The Security Template Id is used for the the SMAW to request session-specific API access keys, also known as SASS key. [Security Templates](https://docs.filerobot.com/go/filerobot-documentation/en/dam-api/api-authentication/security-templates#85e64ad9266588659bf160f345eb46ca87ab1362) are created in the Scaleflex Asset Hub and define permissions and validity for SASS keys. They work similar to oAuth2 tokens.
343
-
344
- ### `id`
345
-
346
- <u>Type:</u> `string`.
347
-
348
- <u>Default:</u> `'scaleflexWidget'`
349
-
350
- The unique identifier used for identifying the widget's instance (# in HTML selector).
351
-
352
- ### `dev`
353
-
354
- <u>Type:</u> `boolean`.
355
-
356
- <u>Default:</u> `false`.
357
-
358
- Enables the development mode which sends all requests to development server, otherwise all the endpoints defaults to the production server.
359
-
360
- > Note: enabling development mode, will show some features that won't work (they're hidden in production mode) with u cause of the generated sass key permissions (that is generated through the security template id).
361
-
362
- ### `theme`
363
-
364
- <u>Type:</u> `object`.
365
-
366
- <u>Default:</u>
276
+ import { useEffect, useRef } from 'react';
277
+ import ScaleflexWidget from '@scaleflex/widget-core';
278
+ import Explorer from '@scaleflex/widget-explorer';
279
+ import XHRUpload from '@scaleflex/widget-xhr-upload';
280
+ import GoogleDrive from '@scaleflex/widget-google-drive';
281
+ import Box from '@scaleflex/widget-box';
282
+ import Unsplash from '@scaleflex/widget-unsplash';
283
+ // ... other imports ...
284
+
285
+ import '@scaleflex/widget-core/dist/style.min.css';
286
+ import '@scaleflex/widget-explorer/dist/style.min.css';
287
+
288
+ // ...
289
+
290
+ scaleflexWidget
291
+ .use(Explorer, {
292
+ trigger: "#open-uploader",
293
+ target: "#widget-container"
294
+ })
295
+ .use(XHRUpload)
296
+ .use(GoogleDrive)
297
+ .use(Box)
298
+ .user(Unsplash);
367
299
 
368
- ```
369
- {
370
- palette: {...},
371
- breakpoints: {...},
372
- typography: {...}
373
- shadows: {...}
374
- }
300
+ // ...
375
301
  ```
376
302
 
377
- > You can check default values for each property here:
303
+ Each connector, when added, will introduce a new option in the UI that enables users to log in to that service and pick files to import. Available **Upload connectors** are listed [here](https://scaleflexhq.atlassian.net/wiki/spaces/FIL/pages/1677557765/Scaleflex+Media+Asset+Widget+SMAW#Architecture-Overview).
378
304
 
379
- - [color palette](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/palette/entity/default-palette.ts)
380
- - [typography](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/typography/entity/default-typography.ts)
381
- - [breakpoints](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/breakpoints/entity/default-breakpoints.ts)
382
- - [shadows](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/shadows/entity/default-shadows.ts)
383
-
384
- We are using [**@scaleflex/ui**](https://github.com/scaleflex/ui/tree/master/packages/ui/src/theme) theme system to have global theme wrapping the project and you can customize it by overriding the default theme values.
305
+ > External storage sources may require additional configuration (such as API keys or client IDs for the third-party service). Refer to the specific storage source page for setup instructions.
385
306
 
386
- You can check the values you can override for each property:
307
+ ### Adding the progress panel
387
308
 
388
- - For color palette you can select the property key from this [**list**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/palette/color.ts#L1)
389
- - For typography, you can change [**font variant**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/typography/font-variant.ts) and [**font weight**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/typography/font-weight.ts)
390
- - For breakpoints [**list**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/css/breakpoint.ts)
391
- - For Shadows [**list**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/shadows/shadows.ts)
309
+ An upload without progress is not very user friendly, it is time to add the [**Progress Panel**](https://www.npmjs.com/package/@scaleflex/widget-progress-panel) plugin:
392
310
 
311
+ ```js
312
+ import GoogleDrive from '@scaleflex/widget-google-drive';
313
+ import Dropbox from '@scaleflex/widget-box';
314
+ import Dropbox from '@scaleflex/widget-unsplash';
315
+ import ProgressPanel from '@scaleflex/widget-progress-panel';
316
+ // ... other imports ...
317
+
318
+ import '@scaleflex/widget-core/dist/style.min.css';
319
+ import '@scaleflex/widget-explorer/dist/style.min.css';
320
+
321
+ scaleflexWidget
322
+ .use(Explorer, {
323
+ trigger: "#open-uploader",
324
+ target: "#widget-container"
325
+ })
326
+ .use(XHRUpload)
327
+ .use(ProgressPanel)
328
+ .use(GoogleDrive)
329
+ .use(Dropbox);
330
+
331
+ // ...
393
332
  ```
394
- theme: {
395
- palette: {
396
- "accent-primary": "#479898",
397
- "accent-primary-hover": "#479898",
398
- "accent-primary-active": "#479898",
399
- "accent-stateless": "#479898",
400
- "link-pressed": "#479898",
401
- "border-active-bottom": "#479898"
402
- },
403
- typography: {
404
- "title-h6": {
405
- fontWeight: FontWeight.Medium, // 500
406
- fontSize: '12px',
407
- lineHeight: '18px',
408
- },
409
- },
410
- breakpoints: {
411
- values: {
412
- xs: 0,
413
- md: 900,
414
- xl: 1400
415
- }
416
- },
417
- shadows: {
418
- "shadow-sm": '6px -4px 12px 0px rgba(146, 166, 188, 0.14)'
419
- }
420
- }
421
- ```
422
-
423
- > NOTE: You must import the font family from your side in 2 weights (Normal === 400, Medium === 500) to have fonts work properly and show text as expected, which means `Roboto` is not included in the plugin by default so you must import it from your side too if you have provided another font family value through theme don't forget to import it from your side too.
424
-
425
- ### `autoProceed`
426
-
427
- <u>Type:</u> `boolean`.
428
-
429
- <u>Default:</u> `false`.
430
-
431
- If set to `true`, the upload process of one or multiple assets will start automatically after drag and drop in the upload area or selection from the user's local explorer. If set to `false`, the pre-upload features will be available to the user before starting the upload via the **Upload** button.
432
-
433
- > Note: this won't open the progress-panel automatically.
434
333
 
435
- ### `allowMultipleUploads`
334
+ ### Customizing the Uploader and listening to events
436
335
 
437
- <u>Type:</u> `boolean`.
336
+ To customize the upload experience, you can use optional parameters from [Explorer](https://www.npmjs.com/package/@scaleflex/widget-core#properties) and [Uploader](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload#properties), for example:
438
337
 
439
- <u>Default:</u> `true`.
338
+ - target folder through [*uploadToFolderPath*](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload#uploadToFolderPath)
339
+ - upload limits and file format restrictions through [*restrictions*](https://www.npmjs.com/package/@scaleflex/widget-core#restrictions)
440
340
 
441
- If set to `false`, only one upload will be possible simultaneously.
341
+ When the upload is completed, you can be notified via the `upload-success` event hook. The widget fires multiple events listed [here](https://www.npmjs.com/package/@scaleflex/widget-core#events).
442
342
 
443
- ### `debug`
343
+ ## Asset Picker mode (for searching and selecting assets from the Scaleflex DAM)
444
344
 
445
- <u>Type:</u> `boolean`.
345
+ > Use case: content editors or e-commerce managers working in a CMD search for product assets in the DAM and insert them into an editorial page or product details page.
446
346
 
447
- <u>Default:</u> `false`.
347
+ The **Asset Picker** mode focuses on searching, selecting, and inserting files from your Scaleflex DAM into your host application. Typical scenarios include a user choosing one or more existing image from from the DAM and to inserting them into a blog post.
448
348
 
449
- Turns on the debug mode by exposing the plugin's debug information to the global window object and turns on the logger.
450
-
451
- ### `logger`
452
-
453
- <u>Type:</u> `object`.
454
-
455
- <u>Default:</u>
349
+ To enable **Asset Picker** mode, you need to use the [**ExploreView**](https://www.npmjs.com/package/@scaleflex/widget-explorer) component as `ExploreViewComponent: ExploreView` and set the `useAssetsPicker: true` flag in the plugin’s configuration:
456
350
 
457
351
  ```js
458
- errorsLogger = {
459
- debug: (...args) => {},
460
- warn: (...args) => {},
461
- error: (...args) => console.error(`[Scaleflex] [${getTimeStamp()}]`, ...args),
462
- };
352
+ ...
353
+ scaleflexWidget.use(Explorer, {
354
+ trigger: "#open-uploader",
355
+ target: "#widget-container"
356
+ ExploreViewComponent: ExploreView,
357
+ useAssetsPicker: true,
358
+ disableUpload: true // prevents users from uploading assets
359
+ // hideDownloadButtonIcon: true, // optionally hide download button in UI to prevent users from downloading assets
360
+ });
361
+ ...
463
362
  ```
464
363
 
465
- ### `restrictions`
364
+ In this mode, users can search for assets, browse the folder hierarchy and insert one or multiple assets into the host application. Advanced functionality such as asset details view (to view metadata or variations), metadata editing or rename/move/delete are not available in this mode.
466
365
 
467
- <u>Type:</u> `object`.
366
+ > If using the Vanilla JS, then the ExploreViewComponent is accessible via the global object as well (e.g. `window.ScaleflexWidget.Explorer.ExploreViewComponent`).
468
367
 
469
- <u>Default:</u>
368
+ ### **Inserting selected selected assets into your application**
369
+
370
+ Once the user picks one or multiple file and clicks on the *Insert* button, the widget will trigger an event to deliver those files to your application. You can listen for the `export` event to catch the file details. For example:
470
371
 
471
372
  ```js
472
- {
473
- maxFileSize: null,
474
- maxNumberOfFiles: null,
475
- minNumberOfFiles: null,
476
- allowedFileTypes: null,
477
- maxItemsSizeForCompression: null,
478
- }
373
+ ...
374
+ scaleflexWidget.on('export', (files) => {
375
+ // 'files' is an array of selected file objects
376
+ console.log("User selected assets:", files);
377
+ // You can then use file URLs or metadata from these objects as needed
378
+ });
379
+ ...
479
380
  ```
480
381
 
481
- Upload restrictions:
482
-
483
- | Property | Type | Default | Description |
484
- | ------------------------------ | ------------------- | ------- | -------------------------------------------------------------------------- |
485
- | **`maxFileSize`** | `number` \| `null` | `null` | maximum file size in bytes |
486
- | **`maxTotalFilesSize`** | `number` \| `null` | `null` | maximum files size in megabyte |
487
- | **`totalUploadedFilesSize`** | `number` \| `null` | `null` | total uploaded files size in megabyte |
488
- | **`hideRestrictionsInformer`** | `boolean` \| `null` | `null` | hide restrictions informer message |
489
- | **`maxNumberOfFiles`** | `number` \| `null` | `null` | maximum number of files to be uploaded simultaneously |
490
- | **`minNumberOfFiles`** | `number` \| `null` | `null` | minimum number of files before upload can star |
491
- | **`allowedFileTypes`** | `array` \| `null` | `null` | accepted file types or extensions, eg. `['image/*', 'image/jpeg', '.jpg']` |
492
-
493
- Folder import restrictions (for 3rd party providers/remote upload):
494
-
495
- | Property | Type | Default | Description |
496
- | -------------------------------- | ------------------ | ------------- | ------------------------------------------------------------------------ |
497
- | **`remoteMaxFolderImportCount`** | `number` \| `null` | `500` | remote upload maximum number of files to import from folders |
498
- | **`remoteMaxFolderImportSize`** | `number` \| `null` | `10737418240` | remote upload maximum total size of files to import from folders (bytes) |
499
- | **`remoteMaxFolderDepth`** | `number` \| `null` | `5` | remote upload maximum folder depth level for recursive folder imports |
500
- | **`remoteMaxFolderCount`** | `number` \| `null` | `100` | remote upload maximum number of folders that can be selected for upload |
501
-
502
- Upload restrictions can also be governed in the backend by the [Security Template](#securitytemplateid) configured.
503
-
504
- Download restrictions:
505
-
506
- | Property | Type | Default | Description |
507
- | -------------------------------- | ------------------ | ------- | ------------------------------------------- |
508
- | **`maxItemsSizeForCompression`** | `number` \| `null` | `null` | maximum items size for compression in bytes |
509
-
510
- ### `onBeforeFileAdded`
382
+ In ReactJS, you might instead provide a callback via props or context, but using the `.on('export', ...)` event listener works universally. Each file object will contain details like URL, name, size, metadata, etc., which you can then use in your application to for example insert the image into an `<img>` tag.
511
383
 
512
- <u>Type:</u> `function`.
384
+ ### Customizing the Asset Picker experience
513
385
 
514
- <u>Default:</u> `(currentFile, files) => currentFile`
386
+ You can use optional parameters from the [Explorer](https://www.npmjs.com/package/@scaleflex/widget-core#properties) plugin, for example:
515
387
 
516
- Gives the possibility to do some checks before adding the file to the state's object,
388
+ - set a limit on the amount of selectable files through [*maxCountOfSelectedFiles*](https://www.npmjs.com/package/@scaleflex/widget-explorer#maxCountOfSelectedFiles)
389
+ - prevent the user from downloading the file on his device through [*hideDownloadButtonIcon*](https://www.npmjs.com/package/@scaleflex/widget-explorer#hideDownloadButtonIcon)
517
390
 
518
- - if the function returns `true`, the file is added to the state.
519
- - if the function returns a modified `file` object the returned object would be added to the state.
520
- - if the function returns `false`, the file is not added to the state.
391
+ When the upload is completed, you can be notified via the `upload-success` event hook. The SMAW provides multiple events listed [here](https://www.npmjs.com/package/@scaleflex/widget-core#events).
521
392
 
522
- ### `onBeforeUpload`
393
+ > Like in other modes, the Asset Picker respects the permissions defined in security template – e.g., if the token is read-only, the UI will naturally prevent any file modification such as rename or delete.
523
394
 
524
- <u>Type:</u> `function`.
395
+ ## Asset Manager mode (light DAM)
525
396
 
526
- <u>Default:</u> `onBeforeUpload: (files) => files`
397
+ > Use case: users of your application need DAM-like functionality to upload and tag assets, set their metadata and view advanced information before using assets.
527
398
 
528
- Gives the possibility to do some checks before starting the upload process
399
+ The **Asset Manager** mode allows the SMAW to function as a light DAM interface embedded in your application (think *DAM as iframe in your application but without any top-level menus and settings*). It is based on the functionality of the Asset Picker but adds file details (such as versions, metadata, and variations) and enables editing. The [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) will display a directory tree and file library, letting the user browse through folders and view assets. Basic digital asset management operations are available and are based on the user’s permissions in the DAM: editing file metadata, moving files, creating folders, uploading new files into the library, etc. This is useful for applications that need to give users a way to manage their media library without leaving the host application.
529
400
 
530
- - if the function returned `true` the upload would start.
531
- - if returned `files` object the returned object would be processed.
532
- - if returned `false` the uploading process won't start.
401
+ To enable **Asset Manager** mode, you need to use the [**ExploreView**](https://www.npmjs.com/package/@scaleflex/widget-explorer) component as `ExploreViewComponent: ExploreView` and set the `useAssetsPicker: false` flag in the plugin’s configuration:
533
402
 
534
- ### `language`
535
-
536
- <u>Type:</u> `string`.
537
-
538
- <u>Default:</u>`'en'`
403
+ ```js
404
+ ...
405
+ import ExploreView from '@scaleflex/widget-explorer/lib/components/ExploreView';
406
+ ...
407
+ scaleflexWidget.use(Explorer, {
408
+ target: '#asset-browser',
409
+ inline: true,
410
+ ExploreViewComponent: ExploreView, // set this to enable Asset Manager mode
411
+ useAssetsPicker: false,
412
+ hideDownloadButtonIcon: false,
413
+ // disableUpload: true // if true, the upload functionality won't be available
414
+ });
415
+ ...
416
+ ```
539
417
 
540
- Used to determine which language to use from the widget's backend translated languages.
418
+ Users can also upload new files to the Scaleflex DAM via the *Upload* button, which is displayed default. It can be hidden through the [*disableUpload*](https://www.npmjs.com/package/@scaleflex/widget-explorer#disableUpload) parameter.
541
419
 
542
- ### `locale`
420
+ > `useAssetsPicker` governs wether the widget will be in Asset Picker (`useAssetsPicker: true`) mode or Asset Manager (`useAssetsPicker: false`) mode.
543
421
 
544
- <u>Type:</u> `object`.
422
+ > Use case: building a *Media Library* page or tab within an admin panel where users manage company files and assets. They can browse all the company’s images, edit tags or metadata, and upload replacements.
545
423
 
546
- <u>Default:</u> default locales inside `lib/defaultLocale.js`
424
+ # Documentation (Core package)
547
425
 
548
- You can override some labels by specifying a translation object here, such as:
426
+ ## ReactJS (over package manager)
549
427
 
550
- ````js
551
- {
552
- strings: {
553
- loaderLoadingLabel: 'Loading'
554
- }
555
- }
428
+ ### Installation
556
429
 
557
- ## Methods
430
+ npm
558
431
 
559
- ### `scaleflexWidget.getId()`
432
+ ```bash
433
+ npm install --save @scaleflex/widget-core
434
+ ```
560
435
 
561
- Gets the Scaleflex Media Asset Widget's instance id.
436
+ yarn
562
437
 
563
- ### `scaleflexWidget.use(plugin, pluignOptions)`
438
+ ```bash
439
+ yarn add @scaleflex/widget-core
440
+ ```
564
441
 
565
- Adds a plugin to the Scaleflex Media Asset Widget's instance:
442
+ ### Usage
566
443
 
567
444
  ```js
568
445
  import ScaleflexWidget from '@scaleflex/widget-core'
569
- import Explorer from '@scaleflex/widget-explorer'
570
-
571
- const scaleflexWidget = ScaleflexWidget()
572
- scaleflexWidget.use(Explorer, {...})
573
- ````
574
-
575
- Refer to the individual plugin's documentation page for available configuration and customization options.
446
+ import "@scaleflex/widget-core/dist/style.min.css";
576
447
 
577
- ### `scaleflexWidget.getPlugin(pluginId)`
448
+ ...
449
+ ...
450
+ ...
578
451
 
579
- Returns the plugin's instance with the provided id for accessing its methods & state.
452
+ const scaleflexWidget = ScaleflexWidget(propertiesObject)
453
+ ```
580
454
 
581
- ### `scaleflexWidget.removePlugin(pluginInstance)`
455
+ ## Vanilla JS (over CDN link, containing all plugins)
582
456
 
583
- Removes a currently initialized plugin by passing the plugin's instance retrieved from the [getPlugin](#scaleflexwidgetgetpluginpluginid) method.
457
+ ### Installation
584
458
 
585
- ### `scaleflexWidget.setOptions(options)`
459
+ - add the following CSS file before the end of `</head>` in your `HTML` file
586
460
 
587
- Passes [Properties](#properties) to the Widget to change properties set during initialization:
461
+ ```html
462
+ <link
463
+ rel="stylesheet"
464
+ type="text/css"
465
+ href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css"
466
+ />
467
+ ```
588
468
 
589
- ```js
590
- import ScaleflexWidget from "@scaleflex/widget-core";
469
+ - add the following JS file before the end of `</body>` in your `HTML` file.
591
470
 
592
- const scaleflexWidget = ScaleflexWidget();
593
- scaleflexWidget.setOptions({
594
- autoProceed: true,
595
- });
471
+ ```html
472
+ <script
473
+ type="text/javascript"
474
+ src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"
475
+ ></script>
596
476
  ```
597
477
 
598
- Individual plugin options can also be changed by using [getPlugin](#scaleflexwidgetgetpluginpluginid)
478
+ ### Usage
599
479
 
600
480
  ```js
601
- import Scaleflex from "@scaleflex/widget-core";
602
-
603
- const scaleflexWidget = ScaleflexWidget();
604
- scaleflexWidget.use(Explorer, { id: "Explorer" });
605
- scaleflexWidget.getPlugin("Explorer").setOptions({
606
- animateOpenClose: false,
607
- });
481
+ const scaleflexWidgetCore = window.ScaleflexWidget.Core
482
+ ...
483
+ ...
484
+ ...
485
+ const scaleflexWidget = scaleflexWidgetCore(propertiesObject)
608
486
  ```
609
487
 
610
- ### `scaleflexWidget.addFile(fileObject)`
611
-
612
- Adds a file into the widget's state and returns the temporary generated id for that file.
613
-
614
- > [restrictions](#restrictions) are checked and [onBeforeFileAdded](#onbeforefileadded) called before adding the file.
615
-
616
- ### `scaleflexWidget.getFile(fileId)`
617
-
618
- Gets the file object using its id.
619
-
620
- ### `scaleflexWidget.removeFile(fileId)`
621
-
622
- Removes a file from the widget's state via its id.
623
-
624
- ### `scaleflexWidget.getFiles()`
625
-
626
- Returns all the file objects currently loaded in the widget.
627
-
628
- ### `scaleflexWidget.upload(files, callback)`
629
-
630
- An async function that starts uploading files, returns a promise resolved with an object `result: { successful, failed }` containing:
631
-
632
- - `successful`: array with file objects successfully uploaded.
633
- - `failed`: array with files objects for which upload failed.
634
-
635
- ### `scaleflexWidget.retryAll()` _Deprecated_
636
-
637
- Retries all the failed uploads.
488
+ ## Parameters
638
489
 
639
- ### `scaleflexWidget.retryUpload(fileId)`
490
+ ### General parameters relevant for all modes
640
491
 
641
- Retries a failed upload for a file referenced by its id.
642
-
643
- ### `scaleflexWidget.cancelUploads()`
492
+ **container**
493
+ Type: `string` (required)
494
+ Default: `undefined`
495
+ The Scaleflex DAM project token (e.g. *fhlcusomb*), [here](https://www.scaleflex.com/filerobot-free-trial) to get one for free.
644
496
 
645
- emit [cancel-uploads](#cancel-uploads) event and cancel uploads.
497
+ **securityTemplateId**
498
+ Type: `string` (required)
499
+ Default: `undefined`
500
+ The Id of a Security Template generated in the [Scaleflex DAM Access settings](https://hub.scaleflex.com/settings/project/access/security-templates). The Security Template defines permissions and restrictions similar to OAuth2 scopes and is used by the widget to customize its UI functions.
646
501
 
647
- ### `scaleflexWidget.setCoreCommonState(object)`
502
+ **id**
648
503
 
649
- Updates the internal state of the widget's core common state.
504
+ Type: `string`
505
+ Default: `'scaleflexWidget'`
506
+ Unique identifier for the widget instance (used in HTML selector).
650
507
 
651
- ### `scaleflexWidget.getGlobalState()`
508
+ **theme**
509
+ Type: `object`
510
+ Default: `{ palette: {...}, breakpoints: {...}, typography: {...}, shadows: {...} }`
511
+ Custom theme overrides for palette, breakpoints, typography, and shadows. The [**@scaleflex/ui**](https://github.com/scaleflex/ui/tree/master/packages/ui/src/theme) is used as a global theme. Default values for the properties are linked below:
652
512
 
653
- Returns the internal state/store of the widget's.
513
+ - [color palette](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/palette/entity/default-palette.ts)
514
+ - [typography](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/typography/entity/default-typography.ts)
515
+ - [breakpoints](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/breakpoints/entity/default-breakpoints.ts)
516
+ - [shadows](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/shadows/entity/default-shadows.ts)
654
517
 
655
- ### `scaleflexWidget.setUploadPanelFileState(fileId, state)` _Deprecated_ - changed to setFileStateBeforeUpload
518
+ Sample override below:
656
519
 
657
- updates the state of a file inside the uploads panel before triggering upload.
520
+ ```js
521
+ theme: {
522
+ palette: {
523
+ "accent-primary": "#479898",
524
+ "accent-primary-hover": "#479898",
525
+ "accent-primary-active": "#479898",
526
+ "accent-stateless": "#479898",
527
+ "link-pressed": "#479898",
528
+ "border-active-bottom": "#479898"
529
+ },
530
+ typography: {
531
+ "title-h6": {
532
+ fontWeight: FontWeight.Medium, // 500
533
+ fontSize: '12px',
534
+ lineHeight: '18px',
535
+ },
536
+ },
537
+ breakpoints: {
538
+ values: {
539
+ xs: 0,
540
+ md: 900,
541
+ xl: 1400
542
+ }
543
+ },
544
+ shadows: {
545
+ "shadow-sm": '6px -4px 12px 0px rgba(146, 166, 188, 0.14)'
546
+ }
547
+ }
548
+ ```
658
549
 
659
- ### `scaleflexWidget.setProgressPanelFileState(fileId, state)` _Deprecated_ - use [`setFileUploadingState`](#setFileUploadingState) instead
550
+ **language** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
551
+ Type: `string`
552
+ Default: `'en'`
553
+ Language code for widget UI.
660
554
 
661
- updates the state of a file inside the [Progress Panel](../@scaleflex/widget-progress-panel/#scaleflexwidgetprogress-panel).
555
+ **locale** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
556
+ Type: `object`
557
+ Default: Default locale from `lib/defaultLocale.js`
558
+ Override UI labels via object (e.g. `{ strings: { loaderLoadingLabel: 'Loading' } }`).
662
559
 
663
- ### `scaleflexWidget.setFileUploadingState(fileId, state)`
560
+ **debug** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
561
+ Type: `boolean`
562
+ Default: `false`
563
+ Turns on the debug mode by exposing the plugin's debug information to the global window object and turns on the logger.
664
564
 
665
- updates the state of a file uploading.
565
+ **logger** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
566
+ Type: `object`
567
+ Default:
666
568
 
667
- ### `scaleflexWidget.getFileUploading(fileId)`
569
+ ```js
570
+ errorsLogger = {
571
+ debug: (...args) => {},
572
+ warn: (...args) => {},
573
+ error: (...args) => console.error(`[Scaleflex] [${getTimeStamp()}]`, ...args),
574
+ };
575
+ ```
668
576
 
669
- Returns a file that is uploading.
577
+ Custom logger object for logging messages.
670
578
 
671
- ### `scaleflexWidget.setFilesInfoMetaTags(fileIds, filesInfoMetaTagsData, forceUpdate)`
579
+ ### Uploader-related properties
672
580
 
673
- Updates the info and/or meta object(s) of the passed files that would be uploaded with the provided `info` and `meta` objects parameters received from `filesInfoMetaTagsData` object in the following format `{ info: {}, meta: {}, tags: {} }`, `forceUpdate` means replace the current tags instead of deep merging with the current ones.
581
+ **autoProceed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
582
+ Type: `boolean`
583
+ Default: `false`
584
+ If `true`, upload process starts immediately after selecting/dropping files.
674
585
 
675
- ### `scaleflexWidget.reset()` _Deprecated_
586
+ **allowMultipleUploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
587
+ Type: `boolean`
588
+ Default: `true`
589
+ Allows simultaneous multiple file uploads.
676
590
 
677
- Returns everything to the initial state of the widget ex. stops all the files uploading, reset their progress and removes all of them.
591
+ **restrictions** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
592
+ Type: `object`
593
+ Default:
678
594
 
679
- ### `scaleflexWidget.close()`
595
+ ```js
596
+ restrictions: {
597
+ "maxFileSize": null,
598
+ "maxTotalFilesSize": null,
599
+ "hideRestrictionsInformer": null,
600
+ "maxNumberOfFiles": null,
601
+ "minNumberOfFiles": null,
602
+ "allowedFileTypes": null,
603
+ "maxItemsSizeForCompression": null,
604
+ "remoteMaxFolderImportCount": 500,
605
+ "remoteMaxFolderImportSize": 10737418240,
606
+ "remoteMaxFolderDepth": 5,
607
+ "remoteMaxFolderCount": 100
608
+ }
609
+ ```
680
610
 
681
- Removes all the installed plugins & closes the current widget's instance.
611
+ Restrictions relevant to Uploader mode:
682
612
 
683
- ### `scaleflexWidget.on('event', handler)`
613
+ | Property | Type | Default | Description |
614
+ | -------------------------- | ------------------- | ------- | -------------------------------------------------------------------------- |
615
+ | `maxFileSize` | `number` \| `null` | `null` | maximum file size in bytes |
616
+ | `maxTotalFilesSize` | `number` \| `null` | `null` | maximum files size in megabyte |
617
+ | `hideRestrictionsInformer` | `boolean` \| `null` | `null` | hide restrictions informer message |
618
+ | `maxNumberOfFiles` | `number` \| `null` | `null` | maximum number of files to be uploaded simultaneously |
619
+ | `minNumberOfFiles` | `number` \| `null` | `null` | minimum number of files before upload can start |
620
+ | `allowedFileTypes` | `array` \| `null` | `null` | accepted file types or extensions, eg. `['image/*', 'image/jpeg', '.jpg']` |
684
621
 
685
- Adds/Subscribe a handler/callback function to be called on emitting/firing the specified `scaleflexWidget event`, [full list of available events](#events).
622
+ Constraints for importing folders from Upload connectors (external storages providers such as [Google Drive](https://www.npmjs.com/package/@scaleflex/widget-google-drive), [Box](https://www.npmjs.com/package/@scaleflex/widget-box) or [Unsplash](https://www.npmjs.com/package/@scaleflex/widget-unsplash), etc.):
686
623
 
687
- ### `scaleflexWidget.once('event', handler)`
624
+ | Property | Type | Default | Description |
625
+ | ---------------------------- | ------------------ | ------------- | ------------------------------------------------------------------------ |
626
+ | `remoteMaxFolderImportCount` | `number` \| `null` | `500` | maximum number of files to import from folders |
627
+ | `remoteMaxFolderImportSize` | `number` \| `null` | `10737418240` | remote upload maximum total size of files to import from folders (bytes) |
628
+ | `remoteMaxFolderDepth` | `number` \| `null` | `5` | remote upload maximum folder depth level for recursive folder imports |
629
+ | `remoteMaxFolderCount` | `number` \| `null` | `100` | remote upload maximum number of folders that can be selected for upload |
688
630
 
689
- Same as `scaleflexWidget.on` but the handler is removed after being called once.
631
+ **customUploadedFilesSizeInMb** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
632
+ Type: `number`
633
+ Default: `0`
634
+ A number to consider (add) to the already uploaded files size while checking the restrictions with the maxTotalFilesSize.
690
635
 
691
- ### `scaleflexWidget.off('event', handler)`
636
+ **onBeforeFileAdded** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
637
+ Type: `function`
638
+ Default: `(currentFile, files) => currentFile`
639
+ Hook to validate or transform files before they’re added:
692
640
 
693
- Un-subscribe/Removes the specified handler for scaleflexWidget's event.
641
+ - if the function returns `true`, the file is added to the state
642
+ - if the function returns a modified `file` object the returned object would be added to the state
643
+ - if the function returns `false`, the file is not added to the state
694
644
 
695
- ### `scaleflexWidget.info(message, type, timeout)`
645
+ **onBeforeUpload** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
646
+ Type: `function`
647
+ Default: `(files) => files`
648
+ Hook before upload starts; can cancel or modify files:
696
649
 
697
- Shows an informer with the specified message to the user:
698
-
699
- | Property | Type | Default | Description |
700
- | ------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
701
- | **`message`** | `string` \| `object` _*Required*_ | `undefined` | Defines the message to be shown to the user, either a string ex. `Some message` or `{ message: 'Some headline message', details: 'Detailed message would be shown on hovering the informer' }` |
702
- | **`type`** | `string` | `info` | choses the type of the informer whether `info, warning or success` |
703
- | **`timeout`** | `number` | `3000` | The duration which the message would still be shown for in milliseconds |
650
+ - if the function returned `true` the upload would start
651
+ - if returned `files` object the returned object would be processed
652
+ - if returned `false` the uploading process won't start
704
653
 
705
- #### `scaleflexWidget.log(message, type)`
654
+ ### Events and Callbacks
706
655
 
707
- Logs a message in the [`logger`](#logger):
656
+ After configuring the widget, you’ll likely interact with it via **events**. The widget instance (*scaleflexWidget*) is an event emitter. You can subscribe to events using `scaleflexWidget.on('<event-name>', callback)`. Some useful events include:
708
657
 
709
- | Property | Type | Default | Description |
710
- | ------------- | --------------------- | ----------- | ---------------------------------------------------------------------- |
711
- | **`message`** | `string` _*Required*_ | `undefined` | the message would be logged/added/shown in the logger. |
712
- | **`type`** | `string` | `debug` | the type of that logged message whether `debug/info, warning or error` |
658
+ - **upload**: fired when an upload process is initiated (e.g., user clicks Upload button).
659
+ - **upload-started**, **upload-progress**, **upload-success**, **upload-error**: for tracking individual file upload status. For example, upload-success provides the file and server response when a file finishes uploading.
660
+ - **complete**: fired when a batch of uploads is fully done (all files either succeeded or failed).
661
+ - **file-added**, **file-removed**: when a user adds a file to the queue or removes it before upload.
662
+ - **restriction-failed**: when a file is rejected due to restrictions (size/type limits).
663
+ - **explorer:modal-open**, **explorer:modal-close**: when the modal is opened or closed.
664
+ - **export**: when files are selected in Asset Picker mode and "exported" (i.e., the user confirmed selection).
665
+ - **error** (global): if any unexpected error occurs.
713
666
 
714
- ## Events
667
+ > All of them are supported from ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
715
668
 
716
- The widget 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:
669
+ Using these events, you can integrate the widget deeply into your application’s workflow (e.g., show a toast when uploads complete, refresh your content after an image is inserted, etc.). For a full list of events, refer to the documentation below:
717
670
 
718
- ### `file-added`
671
+ **file-added** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
719
672
 
720
673
  Emitted when a file has been added to the selected files for uploading.
721
674
 
@@ -726,12 +679,12 @@ Emitted when a file has been added to the selected files for uploading.
726
679
  example
727
680
 
728
681
  ```js
729
- scaleflexWidget.on("file-added", (newFile) => {
730
- console.log("The new file object which is added:", newFile);
682
+ scaleflexWidget.on("file-added", (file) => {
683
+ console.log("The new file object which is added:", file);
731
684
  });
732
685
  ```
733
686
 
734
- ### `file-removed`
687
+ **file-removed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
735
688
 
736
689
  Emitted when a file has been removed from the selected files for uploading.
737
690
 
@@ -743,15 +696,15 @@ Emitted when a file has been removed from the selected files for uploading.
743
696
  example
744
697
 
745
698
  ```js
746
- scaleflexWidget.on("file-removed", (removedFile, reason) => {
699
+ scaleflexWidget.on("file-removed", (file, reason) => {
747
700
  console.log(
748
- `The file ${removedFile.name} is removed because ${reason}, file's object:`,
701
+ `The file ${file.name} is removed because ${reason}, file's object:`,
749
702
  removedFile
750
703
  );
751
704
  });
752
705
  ```
753
706
 
754
- ### `upload`
707
+ **upload** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
755
708
 
756
709
  Emitted on creating a new upload process.
757
710
 
@@ -768,9 +721,9 @@ scaleflexWidget.on("upload", (uploadProcess) => {
768
721
  });
769
722
  ```
770
723
 
771
- ### `restriction-failed`
724
+ **restriction-failed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
772
725
 
773
- Emitted when the restriction checking is failed and there is a file doesn't meet the restrictions.
726
+ Emitted when the restriction checking is failed and there is a file not meeting the restrictions.
774
727
 
775
728
  `params`:
776
729
 
@@ -786,7 +739,7 @@ scaleflexWidget.on("restriction-failed", (file, error) => {
786
739
  });
787
740
  ```
788
741
 
789
- ### `upload-started`
742
+ **upload-started** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
790
743
 
791
744
  Emitted when upload is started.
792
745
 
@@ -795,14 +748,16 @@ Emitted when upload is started.
795
748
  - `file`: The file object that started uploading.
796
749
  - `started`: An object contains upload Id, ex. `{ uploadId: upload id assigned to current file }`.
797
750
 
798
- ### `upload-progress`
751
+ **upload-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
799
752
 
800
- Emitted when there is a progress of some file uploading in the upload process.
753
+ Emitted with the upload progress.
801
754
 
802
755
  `params`:
803
756
 
804
757
  - `file`: The file object that has some progress in its uploading.
805
- - `progress`: An object contains the progress of the file being uploaded, ex. `{ filerobot: plugin's instance, bytesFinished: 1500, bytesTotal: 3500, uploadId: upload id assigned to current file }`.
758
+ - `progress`: An object containing the progress of the file being uploaded, ex. `
759
+ { filerobot: plugin's instance, bytesFinished: 1500, bytesTotal: 3500, uploadId: upload id assigned to current file }.
760
+ `
806
761
 
807
762
  example
808
763
 
@@ -813,7 +768,7 @@ scaleflexWidget.on("upload-progress", (file, progress) => {
813
768
  });
814
769
  ```
815
770
 
816
- ### `upload-success`
771
+ **upload-success** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
817
772
 
818
773
  Emitted when a file is successfully uploaded.
819
774
 
@@ -834,7 +789,7 @@ scaleflexWidget.on("upload-success", (file, response, { uploadId }) => {
834
789
  });
835
790
  ```
836
791
 
837
- ### `upload-error`
792
+ **upload-error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
838
793
 
839
794
  Emitted when a file faced some error/issue while uploading.
840
795
 
@@ -858,7 +813,7 @@ scaleflexWidget.on("upload-error", (file, error, { response, uploadId }) => {
858
813
  });
859
814
  ```
860
815
 
861
- ### `upload-retry`
816
+ **upload-retry** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
862
817
 
863
818
  Emitted on some file uploading is retried.
864
819
 
@@ -874,7 +829,7 @@ scaleflexWidget.on("upload-retry", (fileId) => {
874
829
  });
875
830
  ```
876
831
 
877
- ### `progress`
832
+ **progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
878
833
 
879
834
  Emitted on having a progress of an upload process's total progress.
880
835
 
@@ -890,7 +845,7 @@ scaleflexWidget.on("progress", (totalProgress) => {
890
845
  });
891
846
  ```
892
847
 
893
- ### `cancel-uploads`
848
+ **cancel-uploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
894
849
 
895
850
  Emitted when the whole upload process is canceled (all files uploading are canceled).
896
851
 
@@ -904,7 +859,7 @@ scaleflexWidget.on("cancel-uploads", () => {
904
859
  });
905
860
  ```
906
861
 
907
- ### `complete`
862
+ **complete** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
908
863
 
909
864
  Emitted when the whole upload process done and completed.
910
865
 
@@ -924,7 +879,7 @@ scaleflexWidget.on("complete", ({ failed, uploadId, successful }) => {
924
879
  });
925
880
  ```
926
881
 
927
- ### `items-deleted`
882
+ **items-deleted** ![asset-manager-supported]
928
883
 
929
884
  Emitted when files/folders are deleted.
930
885
 
@@ -942,7 +897,7 @@ scaleflexWidget.on("items-deleted", ({ removedFolders, removedFiles }) => {
942
897
  });
943
898
  ```
944
899
 
945
- ### `error`
900
+ **error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
946
901
 
947
902
  Emitted when the whole upload process faced an error.
948
903
 
@@ -963,7 +918,7 @@ scaleflexWidget.on("error", (filesIds, error, { uploadId }) => {
963
918
  });
964
919
  ```
965
920
 
966
- ### `reset-progress`
921
+ **reset-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
967
922
 
968
923
  Emitted when the upload's progress is reset to 0.
969
924
 
@@ -977,7 +932,7 @@ scaleflexWidget.on("reset-progress", () => {
977
932
  });
978
933
  ```
979
934
 
980
- ### `info-visible`
935
+ **info-visible** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
981
936
 
982
937
  Emitted on showing an `info` message to the user.
983
938
 
@@ -991,7 +946,7 @@ scaleflexWidget.on("info-visible", () => {
991
946
  });
992
947
  ```
993
948
 
994
- ### `info-hidden`
949
+ **info-hidden** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
995
950
 
996
951
  Emitted on hiding an `info` message that were shown to the user.
997
952
 
@@ -1005,9 +960,9 @@ scaleflexWidget.on("info-hidden", () => {
1005
960
  });
1006
961
  ```
1007
962
 
1008
- ### `explorer:modal-open`
963
+ **explorer:modal-open** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
1009
964
 
1010
- Emitted on opening the widget in a modal through the [explorer](../@scaleflex/widget-explorer) plugin.
965
+ Emitted on opening the widget in a modal through the [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) plugin.
1011
966
 
1012
967
  `params`: No params returned.
1013
968
 
@@ -1019,7 +974,7 @@ scaleflexWidget.on("explorer:modal-open", () => {
1019
974
  });
1020
975
  ```
1021
976
 
1022
- ### `explorer:modal-close`
977
+ **explorer:modal-close** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
1023
978
 
1024
979
  Emitted on closing the widget's main modal.
1025
980
 
@@ -1033,7 +988,7 @@ scaleflexWidget.on("explorer:modal-close", () => {
1033
988
  });
1034
989
  ```
1035
990
 
1036
- ### `export`
991
+ **export** ![asset-picker-supported] ![asset-manager-supported]
1037
992
 
1038
993
  emitted when the user downloads a file.
1039
994
 
@@ -1059,26 +1014,171 @@ scaleflexWidget.on(
1059
1014
  );
1060
1015
  ```
1061
1016
 
1062
- ### `url-modified`
1017
+ **url-modified** ![asset-manager-supported]
1063
1018
 
1064
- Emitted when the user uses the [image editor plugin](../@scaleflex/widget-image-editor) in cloudimage mode and changes the url.
1019
+ Emitted when the user uses the [**Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor) in Cloudimage mode and changes the url.
1065
1020
 
1066
1021
  `params`:
1067
1022
 
1068
1023
  - `modifiedUrl`: The modified url for the image.
1069
1024
  - `designState`: The image editor's design state object.
1070
- - `info`: the function that gives you possibility to show a [`@scaleflex/widget-informer`](../@scaleflex/widget-informer/#scaleflexwidgetinformer) message.
1025
+ - `info`: the function that gives you possibility to show a `@scaleflex/widget-informer` message.
1071
1026
 
1072
1027
  example
1073
1028
 
1074
- ```
1029
+ ```js
1075
1030
  scaleflexWidget.on('modified-url', (modifiedUrl, designState, info) => {
1076
1031
  console.log('The new url is', modifiedUrl)
1077
1032
  console.log('Image editor design state:', designState)
1078
1033
  info('Url has changed', 'success', 3000)
1079
1034
  })
1035
+
1080
1036
  ```
1081
1037
 
1038
+ ### Plugin APIs (advanced use)
1039
+
1040
+ Utilize the widget’s instance APIs to apply different functionalities on the current instance programmatically with the reflection on the UI.
1041
+
1042
+ **scaleflexWidget.getId()**
1043
+
1044
+ Gets the Scaleflex Media Asset Widget's current instance id.
1045
+
1046
+ **scaleflexWidget.use(plugin, pluginOptions)**
1047
+
1048
+ Adds a plugin to the Scaleflex Media Asset Widget's instance.
1049
+
1050
+ ```js
1051
+ // example
1052
+ import ScaleflexWidget from '@scaleflex/widget-core'
1053
+ import Explorer from '@scaleflex/widget-explorer'
1054
+
1055
+ const scaleflexWidget = ScaleflexWidget()
1056
+ scaleflexWidget.use(Explorer, {...})
1057
+ ```
1058
+
1059
+ **scaleflexWidget.getPlugin(pluginId)**
1060
+
1061
+ Returns the plugin's instance with the provided id for accessing its methods & state.
1062
+
1063
+ **scaleflexWidget.removePlugin(pluginInstance)**
1064
+
1065
+ Removes a currently initialized plugin by passing the plugin's instance retrieved from the [getPlugin](https://www.npmjs.com/package/@scaleflex/widget-core#scaleflexwidgetgetpluginpluginid) method.
1066
+
1067
+ **scaleflexWidget.setOptions(options)**
1068
+
1069
+ Passes [Properties](https://www.npmjs.com/package/@scaleflex/widget-core#parameters) to the Widget to change properties set during initialization:
1070
+
1071
+ ```js
1072
+ import ScaleflexWidget from "@scaleflex/widget-core";
1073
+
1074
+ const scaleflexWidget = ScaleflexWidget();
1075
+ scaleflexWidget.setOptions({
1076
+ autoProceed: true,
1077
+ });
1078
+ ```
1079
+
1080
+ Individual plugin options can also be changed by using [getPlugin](https://www.npmjs.com/package/@scaleflex/widget-core#scaleflexwidgetgetpluginpluginid)
1081
+
1082
+ ```js
1083
+ import Scaleflex from "@scaleflex/widget-core";
1084
+
1085
+ const scaleflexWidget = ScaleflexWidget();
1086
+ scaleflexWidget.use(Explorer, { id: "Explorer" });
1087
+ scaleflexWidget.getPlugin("Explorer").setOptions({
1088
+ animateOpenClose: false,
1089
+ });
1090
+ ```
1091
+
1092
+ **scaleflexWidget.addFile(fileObject)**
1093
+
1094
+ Adds a file into the widget's state and returns the temporary generated id for that file.
1095
+
1096
+ > [restrictions](https://www.npmjs.com/package/@scaleflex/widget-core#restrictions) are checked and [onBeforeFileAdded](https://www.npmjs.com/package/@scaleflex/widget-core#onbeforefileadded) called before adding the file.
1097
+
1098
+ **scaleflexWidget.getFile(fileId)**
1099
+
1100
+ Gets the file object using its id.
1101
+
1102
+ **scaleflexWidget.removeFile(fileId)**
1103
+
1104
+ Removes a file from the widget's state via its id.
1105
+
1106
+ **scaleflexWidget.getFiles()**
1107
+
1108
+ Returns all the file objects currently loaded in the widget.
1109
+
1110
+ **scaleflexWidget.upload(files, callback)**
1111
+
1112
+ An async function that starts uploading files, returns a promise resolved with an object `result: { successful, failed }` containing:
1113
+
1114
+ - `successful`: array with file objects successfully uploaded.
1115
+ - `failed`: array with files objects for which upload failed.
1116
+
1117
+ **scaleflexWidget.retryUpload(fileId)**
1118
+
1119
+ Retries a failed upload for a file referenced by its id.
1120
+
1121
+ **scaleflexWidget.cancelUploads()**
1122
+
1123
+ emit [cancel-uploads](https://www.npmjs.com/package/@scaleflex/widget-core#cancel-uploads) event and cancel uploads.
1124
+
1125
+ **scaleflexWidget.setCoreCommonState(object)**
1126
+
1127
+ Updates the internal state of the widget's core common state.
1128
+
1129
+ **scaleflexWidget.getGlobalState()**
1130
+
1131
+ Returns the internal state/store of the widget's.
1132
+
1133
+ updates the state of a file inside the uploads panel before triggering upload.
1134
+
1135
+ **scaleflexWidget.setFileUploadingState(fileId, state)**
1136
+
1137
+ updates the state of a file uploading.
1138
+
1139
+ **scaleflexWidget.getFileUploading(fileId)**
1140
+
1141
+ Returns a file that is uploading.
1142
+
1143
+ **scaleflexWidget.setFilesInfoMetaTags(fileIds, filesInfoMetaTagsData, forceUpdate)**
1144
+
1145
+ Updates the info and/or meta object(s) of the passed files that would be uploaded with the provided `info` and `meta` objects parameters received from `filesInfoMetaTagsData` object in the following format `{ info: {}, meta: {}, tags: {} }`, `forceUpdate` means replace the current tags instead of deep merging with the current ones.
1146
+
1147
+ **scaleflexWidget.close()**
1148
+
1149
+ Removes all the installed plugins & closes the current widget's instance.
1150
+
1151
+ **scaleflexWidget.on('event', handler)**
1152
+
1153
+ Adds/Subscribe a handler/callback function to be called on emitting/firing the specified `scaleflexWidget event`, [full list of available events](https://www.npmjs.com/package/@scaleflex/widget-core#events).
1154
+
1155
+ **scaleflexWidget.once('event', handler)**
1156
+
1157
+ Same as `scaleflexWidget.on` but the handler is removed after being called once.
1158
+
1159
+ **scaleflexWidget.off('event', handler)**
1160
+
1161
+ Un-subscribe/Removes the specified handler for scaleflexWidget's event.
1162
+
1163
+ **scaleflexWidget.info(message, type, timeout)**
1164
+
1165
+ Shows an informer with the specified message to the user:
1166
+
1167
+ | Property | Type | Default | Description |
1168
+ | --------- | ------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1169
+ | `message` | `string` \| `object` *Required* | `undefined` | Defines the message to be shown to the user, either a string ex. `Some message` or `{ message: 'Some headline message', details: 'Detailed message would be shown on hovering the informer' }` |
1170
+ | `type` | `string` | `info` | choses the type of the informer whether `info, warning or success` |
1171
+ | `timeout` | `number` | `3000` | The duration which the message would still be shown for in milliseconds |
1172
+
1173
+ **scaleflexWidget.log(message, type)**
1174
+
1175
+ Logs a message in the `logger`:
1176
+
1177
+ | Property | Type | Default | Description |
1178
+ | --------- | ------------------- | ----------- | ---------------------------------------------------------------------- |
1179
+ | `message` | `string` *Required* | `undefined` | the message would be logged/added/shown in the logger. |
1180
+ | `type` | `string` | `debug` | the type of that logged message whether `debug/info, warning or error` |
1181
+
1082
1182
  <!-- Variables -->
1083
1183
 
1084
1184
  [npm-url]: https://www.npmjs.com/package/@scaleflex/widget-core
@@ -1097,6 +1197,14 @@ scaleflexWidget.on('modified-url', (modifiedUrl, designState, info) => {
1097
1197
  [filerobot-version-stable]: https://img.shields.io/npm/v/@scaleflex/widget-core/stable?label=stable&style=for-the-badge&logo=npm
1098
1198
  [filerobot-version]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=Version&style=for-the-badge&logo=npm
1099
1199
  [codeSandbox-image]: https://img.shields.io/badge/CodeSandbox-black?style=for-the-badge&logo=CodeSandbox
1200
+ <!-- Supported modes variables -->
1201
+ [uploader-supported]: https://img.shields.io/badge/Uploader-orange
1202
+ [asset-picker-supported]: https://img.shields.io/badge/Asset%20Picker-green
1203
+ [asset-manager-supported]: https://img.shields.io/badge/Asset%20Manager-blue
1204
+ <!-- Usage -->
1205
+ <!-- ![uploader-supported]
1206
+ ![asset-picker-supported]
1207
+ ![asset-manager-supported] -->
1100
1208
 
1101
1209
  ## License
1102
1210