@scaleflex/widget-core 4.0.5 → 4.0.7-beta.0

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/README.md +659 -561
  2. package/lib/index.js +4 -4
  3. package/package.json +4 -4
  4. package/CHANGELOG.md +0 -7484
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]
@@ -17,705 +14,651 @@
17
14
  [![CodeSandbox][codeSandbox-image]][codeSandbox-url]
18
15
 
19
16
  <div align='center'>
20
- <img title="Scaleflex Widget logo" alt="Scaleflex Widget logo" src="https://assets.scaleflex.com/Corporate+Branding/%5B2025%5D+ALL+LOGOS+%2B+ICONS/SCALEFLEX/VXP+logo/Horizontal+White/VXP+logo+WHITE.png?vh=663932" width="140"/>
17
+ <img title="Scaleflex Widget logo" alt="Scaleflex Widget logo" src="https://assets.scaleflex.com/Corporate%20Branding/%5B2025%5D%20ALL%20LOGOS%20+%20ICONS/SCALEFLEX/VXP%20logo/Horizontal%20Black/VXP%20logo%20BLACK.png?vh=13b506&w=300" width="300"/>
21
18
  </div>
22
19
 
23
- The **SMAW** is a file uploader and media gallery in one easy-to-integrate modal or inline widget. It is the storefront of the [**Scaleflex**](https://scaleflex.com) DAM (Digital Asset Management) and enables accelerated uploads through Scaleflex's content ingestion network and reverse CDN.
24
-
25
- Various plugins like for example the [**Scaleflex Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor/#scaleflexwidgetimage-editor) can be enabled to address use cases requiring the interaction with images, videos and static files in your web application. The modular architecture only loads relevant code, thus making the widget as lightweight as possible.
26
-
27
- <!-- <img src="https://cdn.scaleflex.com/demo/widget-npm_v8.gif?vh=4780be" title="Overview of the widget GIF" alt="Overview of the widget GIF" width="600" /> -->
28
-
29
- **[Check it live in action](https://cdn.scaleflex.com/plugins/widget/v4/demo/index.html)**
30
-
31
20
  <details>
32
21
  <summary>Table of contents</summary>
33
22
 
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)
23
+ - [What is the SMAW?](#what-is-the-smaw)
24
+ - [Installation (minimal drag and drop upload zone)](#installation-minimal-drag-and-drop-upload-zone)
25
+ - [ReactJS (over package manager)](#reactjs-over-package-manager)
26
+ - [Vanilla JS (over CDN link, containing all plugins)](#vanilla-js-over-cdn-link-containing-all-plugins)
27
+ - [Widget modes and use cases](#widget-modes-and-use-cases)
28
+ - [Core package and plugins](#core-package-and-plugins)
29
+ - [Quick Start](#quick-start)
30
+ - [Uploader mode (as modal to upload files in the Scaleflex DAM)](#uploader-mode-as-modal-to-upload-files-in-the-scaleflex-dam)
31
+ - [Enabling upload connectors for import from external storage sources](#enabling-upload-connectors-for-import-from-external-storage-sources)
32
+ - [Adding the progress panel](#adding-the-progress-panel)
33
+ - [Customizing the Uploader and listening to events](#customizing-the-uploader-and-listening-to-events)
34
+ - [Asset Picker mode (for searching and selecting assets from the Scaleflex DAM)](#asset-picker-mode-for-searching-and-selecting-assets-from-the-scaleflex-dam)
35
+ - [Inserting selected selected assets into your application](#inserting-selected-selected-assets-into-your-application)
36
+ - [Customizing the Asset Picker experience](#customizing-the-asset-picker-experience)
37
+ - [Asset Manager mode (light DAM)](#asset-manager-mode-light-dam)
38
+ - [Documentation (Core package)](#documentation-core-package)
39
+ - [ReactJS (over package manager)](#reactjs-over-package-manager-1)
40
+ - [Installation](#installation)
49
41
  - [Usage](#usage)
50
- - [Properties](#properties)
51
- - [Events](#events)
42
+ - [Vanilla JS (over CDN link, containing all plugins)](#vanilla-js-over-cdn-link-containing-all-plugins-1)
43
+ - [Installation](#installation-1)
44
+ - [Usage](#usage-1)
45
+ - [Parameters](#parameters)
46
+ - [General parameters relevant for all modes](#general-parameters-relevant-for-all-modes)
47
+ - [Uploader-related properties](#uploader-related-properties)
48
+ - [Events and Callbacks](#events-and-callbacks)
49
+ - [Plugin APIs (advanced use)](#plugin-apis-advanced-use)
52
50
  - [License](#license)
53
51
  </details>
54
52
 
55
- ## Main features:
53
+ # What is the SMAW?
56
54
 
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)
55
+ 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.
56
+ It can be extended and customized by a robust ecosystem of [plugins](#user-content-core-package-and-plugins).
72
57
 
73
- The widget can be integrated in a web page HTML element, as a pop-up modal on button click.
58
+ > Check out the <a href="https://scaleflex.cloudimg.io/v7/plugins/widget/v4/demo/index.html?func=proxy" target="_blank" rel="noopener noreferrer">interactive sandbox</a> to try the different widget modes and play with its parameters.
74
59
 
75
- ## Installation
60
+ > You need a Scaleflex DAM account to use the SMAW. Get one <a href="https://www.scaleflex.com/filerobot-free-trial" target="_blank" rel="noopener noreferrer">here</a> for free.
76
61
 
77
- The widget's architecture contains the [**Core**](#scaleflexwidget-core) module and various [**plugins**](#plugins). Each [**plugin**](#plugins) has its own dedicated documentation.
62
+ **Key features:**
78
63
 
79
- **CDN links to JS and CSS (containing all plugins)**
64
+ - **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.
65
+ - **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.
66
+ - **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.
67
+ - **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
68
 
81
- - Add the following CSS file before the end of `</head>` in your `HTML` file
69
+ 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
70
 
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
- ```
71
+ ## Installation (minimal drag and drop upload zone)
90
72
 
91
- - Add the following JS file before the end of `</body>` in your `HTML` file.
73
+ 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
74
 
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
75
+ Below is a simple installation example in both ReactJS and Vanilla JS.
103
76
 
104
- ### Demo
77
+ ### ReactJS (over package manager)
105
78
 
106
- [See the SMAW in action here](https://cdn.scaleflex.com/plugins/widget/v4/demo/index.html).
79
+ npm
107
80
 
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:
81
+ ```bash
82
+ npm install --save @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
83
+ ```
111
84
 
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)
85
+ yarn
115
86
 
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).
87
+ ```bash
88
+ yarn add @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
89
+ ```
117
90
 
118
- ### React
91
+ Sample code to instantiate the widget:
119
92
 
120
93
  ```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";
94
+ import { useEffect, useRef } from 'react';
95
+ import ScaleflexWidget from '@scaleflex/widget-core';
96
+ import Explorer from '@scaleflex/widget-explorer';
97
+ import XHRUpload from '@scaleflex/widget-xhr-upload';
126
98
 
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";
99
+ // Import base styles (Core first, then Explorer - included in the packages above)
100
+ import '@scaleflex/widget-core/dist/style.min.css';
101
+ import '@scaleflex/widget-explorer/dist/style.min.css';
131
102
 
132
- const App = () => {
133
- const scaleflexWidget = useRef(null);
103
+ function App() {
104
+ const scaleflexWidgetRef = useRef(null);
134
105
 
135
106
  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
- };
107
+ // Initialize the core widget
108
+ scaleflexWidgetRef.current = ScaleflexWidget({
109
+ container: "YOUR_CONTAINER",
110
+ securityTemplateId: "YOUR_SECURITY_TEMPLATE_ID"
111
+ });
112
+
113
+ // Use the Explorer UI in default uploader mode, and enable XHR upload
114
+ scaleflexWidgetRef.current
115
+ .use(Explorer, { target: "#widget-container", inline: true })
116
+ .use(XHRUpload);
117
+
118
+ // Cleanup on unmount (close widget to free resources)
119
+ return () => scaleflexWidgetRef.current.close();
152
120
  }, []);
153
121
 
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
122
+ return <div id="widget-container" style={{ width: '800px', height: '600px' }}></div>;
123
+ }
166
124
 
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>
125
+ export default App;
204
126
  ```
205
127
 
206
- ## Modules
207
-
208
- The Scaleflex Core module: [**Core**](#scaleflexwidget-core)
209
-
210
- ## Plugins
211
-
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.
128
+ 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.
225
129
 
226
- ### Upload connectors
130
+ ### Vanilla JS (over CDN link, containing all plugins)
227
131
 
228
- - [**Google Drive**](https://www.npmjs.com/package/@scaleflex/widget-google-drive/#scaleflexwidgetgoogle-drive): import files from Google Drive.
132
+ - add the following CSS file before the end of `</head>` in your `HTML` file
229
133
 
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.
134
+ ```html
135
+ <link
136
+ rel="stylesheet"
137
+ type="text/css"
138
+ href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css"
139
+ />
140
+ ```
233
141
 
234
- - [**Instagram**](https://www.npmjs.com/package/@scaleflex/widget-instagram/#scaleflexwidgetinstagram): import images and videos from Instagram.
142
+ - add the following JS file before the end of `</body>` in your `HTML` file.
235
143
 
236
- - [**Facebook**](https://www.npmjs.com/package/@scaleflex/widget-facebook/#scaleflexwidgetfacebook): import images and videos from Facebook.
144
+ ```html
145
+ <script
146
+ type="text/javascript"
147
+ src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"
148
+ ></script>
149
+ ```
237
150
 
238
- - [**OneDrive**](https://www.npmjs.com/package/@scaleflex/widget-onedrive/#scaleflexwidgetonedrive): import files from Microsoft OneDrive.
151
+ Sample code to instantiate the widget:
239
152
 
240
- - [**Import From URL**](https://www.npmjs.com/package/@scaleflex/widget-url/#scaleflexwidgeturl): import direct URLs from anywhere on the web.
153
+ ```html
154
+ <!-- Include CSS in <head> -->
155
+ <link rel="stylesheet" href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css" />
156
+
157
+ <!-- Container element for the widget -->
158
+ <div id="widget-container"></div>
159
+
160
+ <!-- Include JS in <body> -->
161
+ <script src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"></script>
162
+ <script>
163
+ // Access global widget object
164
+ const Widget = window.ScaleflexWidget;
165
+ // Initialize core
166
+ const scaleflexWidget = Widget.Core({
167
+ container: "YOUR_CONTAINER",
168
+ securityTemplateId: "YOUR_SECURITY_TEMPLATE_ID",
169
+ // dev: false
170
+ });
171
+ // Add plugins
172
+ scaleflexWidget
173
+ .use(Widget.Explorer, { target: "#widget-container", inline: true })
174
+ .use(Widget.XHRUpload);
175
+ </script>
176
+ ```
241
177
 
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.
178
+ This achieves the same outcome as the ReactJS example: an inline file explorer/uploader within the `#widget-container` div.
243
179
 
244
- - [**Screen Capture**](https://www.npmjs.com/package/@scaleflex/widget-screen-capture/#scaleflexwidgetscreen-capture): device screen recorder.
180
+ > 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
181
 
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.
182
+ ## Widget modes and use cases
247
183
 
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.
184
+ The SMAW supports multiple **modes** to fit different use cases:
249
185
 
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.
186
+ - **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).
187
+ Use case: a web app where users upload media (images/videos) or documents (UGC) into a central library.
188
+ [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
189
 
252
- - [**Unsplash**](https://www.npmjs.com/package/@scaleflex/widget-unsplash/#scaleflexwidgetunsplash): import files from unsplash.
190
+ - **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.
191
+ 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.
192
+ [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
193
 
254
- ### Destinations
194
+ - **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.
195
+ 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.
196
+ [Example code](https://scaleflexhq.atlassian.net/wiki/spaces/FIL/pages/1677557765/Scaleflex+Media+Asset+Widget+SMAW#Asset-Manager-mode-(light-DAM))
255
197
 
256
- - [**XHR Upload**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload/#scaleflexwidgetxhr-upload): handles multipart file upload.
198
+ ## Core package and plugins
257
199
 
258
- - [**Tus**](https://www.npmjs.com/package/@scaleflex/widget-Tus/#scaleflexwidgettus): applies resumable upload (BE must support that).
200
+ 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
201
 
260
- ### Miscellaneous
202
+ - `@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*.
203
+ - `@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:
204
+ - `@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
205
+ - `@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.
206
+ - `@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:
207
+ - `@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
208
+ - `@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
209
+ - `@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
210
+ - **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:
211
+ - [Box](https://www.npmjs.com/package/@scaleflex/widget-box)
212
+ - [Dropbox](https://www.npmjs.com/package/@scaleflex/widget-dropbox)
213
+ - [Facebook](https://www.npmjs.com/package/@scaleflex/widget-facebook)
214
+ - [Google Drive](https://www.npmjs.com/package/@scaleflex/widget-google-drive)
215
+ - [Instagram](https://www.npmjs.com/package/@scaleflex/widget-instagram)
216
+ - [OneDrive](https://www.npmjs.com/package/@scaleflex/widget-onedrive)
217
+ - [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.
218
+ - [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
219
+ - `@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
220
 
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
221
 
264
- ## Widget modes
222
+ # Quick Start
265
223
 
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.
224
+ 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
225
 
268
- ## `@scaleflex/widget-core`
226
+ - **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).
227
+ - **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
228
 
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.
229
+ ## Uploader mode (as modal to upload files in the Scaleflex DAM)
271
230
 
272
- ## Usage
231
+ > Use case: a web app where users upload media (images/videos) or documents (UGC) into a central library.
273
232
 
274
- ### NPM
233
+ You can implement the SMAW in **Uploader** mode in two ways:
275
234
 
276
- ```bash
277
- npm install --save @scaleflex/widget-core
278
- ```
235
+ - **as a modal:** the widget opens when triggered (e.g., by a button), and appears as a modal
236
+ - **inline embedded in page:** the widget is always visible in a given page section, acting as an upload panel or drop zone
279
237
 
280
- ### YARN
238
+ 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
239
 
282
- ```bash
283
- yarn add @scaleflex/widget-core
240
+ ```html
241
+ <!-- ... -->
242
+ <button id="open-uploader">Upload Assets</button>
243
+ <!-- ... -->
284
244
  ```
285
245
 
286
- then
246
+ Add the following code to the widget’s instantiation:
287
247
 
288
248
  ```js
289
- import ScaleflexWidget from '@scaleflex/widget-core'
290
- ...
291
- ...
292
- ...
293
- const scaleflexWidget = ScaleflexWidget(propertiesObject)
249
+ // ...
250
+ scaleflexWidget.use(Explorer, {
251
+ trigger: "#open-uploader", // CSS selector for the trigger element
252
+ target: "body" // where to attach the modal in the DOM
253
+ });
254
+ // ...
294
255
  ```
295
256
 
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
- ```
257
+ 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
258
 
308
- ### Module's styles
259
+ 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
260
 
310
- ```js
311
- import "@scaleflex/widget-core/dist/style.css";
312
- ```
261
+ ### Enabling upload connectors for import from external storage sources
313
262
 
314
- or via the minified versions
263
+ 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
264
 
316
265
  ```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>
266
+ import { useEffect, useRef } from 'react';
267
+ import ScaleflexWidget from '@scaleflex/widget-core';
268
+ import Explorer from '@scaleflex/widget-explorer';
269
+ import XHRUpload from '@scaleflex/widget-xhr-upload';
270
+ import GoogleDrive from '@scaleflex/widget-google-drive';
271
+ import Box from '@scaleflex/widget-box';
272
+ import Unsplash from '@scaleflex/widget-unsplash';
273
+ // ... other imports ...
274
+
275
+ import '@scaleflex/widget-core/dist/style.min.css';
276
+ import '@scaleflex/widget-explorer/dist/style.min.css';
277
+
278
+ // ...
279
+
280
+ scaleflexWidget
281
+ .use(Explorer, {
282
+ trigger: "#open-uploader",
283
+ target: "#widget-container"
284
+ })
285
+ .use(XHRUpload)
286
+ .use(GoogleDrive)
287
+ .use(Box)
288
+ .user(Unsplash);
367
289
 
368
- ```
369
- {
370
- palette: {...},
371
- breakpoints: {...},
372
- typography: {...}
373
- shadows: {...}
374
- }
290
+ // ...
375
291
  ```
376
292
 
377
- > You can check default values for each property here:
293
+ 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
294
 
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)
295
+ > 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.
383
296
 
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.
297
+ ### Adding the progress panel
385
298
 
386
- You can check the values you can override for each property:
299
+ 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:
387
300
 
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)
392
-
393
- ```
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
- }
301
+ ```js
302
+ import GoogleDrive from '@scaleflex/widget-google-drive';
303
+ import Dropbox from '@scaleflex/widget-box';
304
+ import Dropbox from '@scaleflex/widget-unsplash';
305
+ import ProgressPanel from '@scaleflex/widget-progress-panel';
306
+ // ... other imports ...
307
+
308
+ import '@scaleflex/widget-core/dist/style.min.css';
309
+ import '@scaleflex/widget-explorer/dist/style.min.css';
310
+
311
+ scaleflexWidget
312
+ .use(Explorer, {
313
+ trigger: "#open-uploader",
314
+ target: "#widget-container"
315
+ })
316
+ .use(XHRUpload)
317
+ .use(ProgressPanel)
318
+ .use(GoogleDrive)
319
+ .use(Dropbox);
320
+
321
+ // ...
421
322
  ```
422
323
 
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.
324
+ ### Customizing the Uploader and listening to events
432
325
 
433
- > Note: this won't open the progress-panel automatically.
326
+ 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:
434
327
 
435
- ### `allowMultipleUploads`
328
+ - target folder through [*uploadToFolderPath*](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload#uploadToFolderPath)
329
+ - upload limits and file format restrictions through [*restrictions*](https://www.npmjs.com/package/@scaleflex/widget-core#restrictions)
436
330
 
437
- <u>Type:</u> `boolean`.
331
+ 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-and-callbacks).
438
332
 
439
- <u>Default:</u> `true`.
333
+ ## Asset Picker mode (for searching and selecting assets from the Scaleflex DAM)
440
334
 
441
- If set to `false`, only one upload will be possible simultaneously.
335
+ > 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.
442
336
 
443
- ### `debug`
337
+ 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.
444
338
 
445
- <u>Type:</u> `boolean`.
446
-
447
- <u>Default:</u> `false`.
448
-
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>
339
+ 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
340
 
457
341
  ```js
458
- errorsLogger = {
459
- debug: (...args) => {},
460
- warn: (...args) => {},
461
- error: (...args) => console.error(`[Scaleflex] [${getTimeStamp()}]`, ...args),
462
- };
342
+ ...
343
+ scaleflexWidget.use(Explorer, {
344
+ trigger: "#open-uploader",
345
+ target: "#widget-container"
346
+ ExploreViewComponent: ExploreView,
347
+ useAssetsPicker: true,
348
+ disableUpload: true // prevents users from uploading assets
349
+ // hideDownloadButtonIcon: true, // optionally hide download button in UI to prevent users from downloading assets
350
+ });
351
+ ...
463
352
  ```
464
353
 
465
- ### `restrictions`
354
+ 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.
355
+
356
+ > If using the Vanilla JS, then the ExploreViewComponent is accessible via the global object as well (e.g. `window.ScaleflexWidget.Explorer.ExploreViewComponent`).
466
357
 
467
- <u>Type:</u> `object`.
358
+ ### **Inserting selected selected assets into your application**
468
359
 
469
- <u>Default:</u>
360
+ 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
361
 
471
362
  ```js
472
- {
473
- maxFileSize: null,
474
- maxNumberOfFiles: null,
475
- minNumberOfFiles: null,
476
- allowedFileTypes: null,
477
- maxItemsSizeForCompression: null,
478
- }
363
+ ...
364
+ scaleflexWidget.on('export', (files) => {
365
+ // 'files' is an array of selected file objects
366
+ console.log("User selected assets:", files);
367
+ // You can then use file URLs or metadata from these objects as needed
368
+ });
369
+ ...
479
370
  ```
480
371
 
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 |
372
+ 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.
509
373
 
510
- ### `onBeforeFileAdded`
374
+ ### Customizing the Asset Picker experience
511
375
 
512
- <u>Type:</u> `function`.
376
+ You can use optional parameters from the [Explorer](https://www.npmjs.com/package/@scaleflex/widget-core#properties) plugin, for example:
513
377
 
514
- <u>Default:</u> `(currentFile, files) => currentFile`
378
+ - set a limit on the amount of selectable files through [*maxCountOfSelectedFiles*](https://www.npmjs.com/package/@scaleflex/widget-explorer#maxCountOfSelectedFiles)
379
+ - prevent the user from downloading the file on his device through [*hideDownloadButtonIcon*](https://www.npmjs.com/package/@scaleflex/widget-explorer#hideDownloadButtonIcon)
515
380
 
516
- Gives the possibility to do some checks before adding the file to the state's object,
381
+ 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).
517
382
 
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.
383
+ > 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.
521
384
 
522
- ### `onBeforeUpload`
385
+ ## Asset Manager mode (light DAM)
523
386
 
524
- <u>Type:</u> `function`.
387
+ > 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.
525
388
 
526
- <u>Default:</u> `onBeforeUpload: (files) => files`
389
+ 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.
527
390
 
528
- Gives the possibility to do some checks before starting the upload process
391
+ 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:
529
392
 
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.
533
-
534
- ### `language`
535
-
536
- <u>Type:</u> `string`.
537
-
538
- <u>Default:</u>`'en'`
393
+ ```js
394
+ ...
395
+ import ExploreView from '@scaleflex/widget-explorer/lib/components/ExploreView';
396
+ ...
397
+ scaleflexWidget.use(Explorer, {
398
+ target: '#asset-browser',
399
+ inline: true,
400
+ ExploreViewComponent: ExploreView, // set this to enable Asset Manager mode
401
+ useAssetsPicker: false,
402
+ hideDownloadButtonIcon: false,
403
+ // disableUpload: true // if true, the upload functionality won't be available
404
+ });
405
+ ...
406
+ ```
539
407
 
540
- Used to determine which language to use from the widget's backend translated languages.
408
+ 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
409
 
542
- ### `locale`
410
+ > `useAssetsPicker` governs wether the widget will be in Asset Picker (`useAssetsPicker: true`) mode or Asset Manager (`useAssetsPicker: false`) mode.
543
411
 
544
- <u>Type:</u> `object`.
412
+ > 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
413
 
546
- <u>Default:</u> default locales inside `lib/defaultLocale.js`
414
+ # Documentation (Core package)
547
415
 
548
- You can override some labels by specifying a translation object here, such as:
416
+ ## ReactJS (over package manager)
549
417
 
550
- ````js
551
- {
552
- strings: {
553
- loaderLoadingLabel: 'Loading'
554
- }
555
- }
418
+ ### Installation
556
419
 
557
- ## Methods
420
+ npm
558
421
 
559
- ### `scaleflexWidget.getId()`
422
+ ```bash
423
+ npm install --save @scaleflex/widget-core
424
+ ```
560
425
 
561
- Gets the Scaleflex Media Asset Widget's instance id.
426
+ yarn
562
427
 
563
- ### `scaleflexWidget.use(plugin, pluignOptions)`
428
+ ```bash
429
+ yarn add @scaleflex/widget-core
430
+ ```
564
431
 
565
- Adds a plugin to the Scaleflex Media Asset Widget's instance:
432
+ ### Usage
566
433
 
567
434
  ```js
568
435
  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.
436
+ import "@scaleflex/widget-core/dist/style.min.css";
576
437
 
577
- ### `scaleflexWidget.getPlugin(pluginId)`
438
+ ...
439
+ ...
440
+ ...
578
441
 
579
- Returns the plugin's instance with the provided id for accessing its methods & state.
442
+ const scaleflexWidget = ScaleflexWidget(propertiesObject)
443
+ ```
580
444
 
581
- ### `scaleflexWidget.removePlugin(pluginInstance)`
445
+ ## Vanilla JS (over CDN link, containing all plugins)
582
446
 
583
- Removes a currently initialized plugin by passing the plugin's instance retrieved from the [getPlugin](#scaleflexwidgetgetpluginpluginid) method.
447
+ ### Installation
584
448
 
585
- ### `scaleflexWidget.setOptions(options)`
449
+ - add the following CSS file before the end of `</head>` in your `HTML` file
586
450
 
587
- Passes [Properties](#properties) to the Widget to change properties set during initialization:
451
+ ```html
452
+ <link
453
+ rel="stylesheet"
454
+ type="text/css"
455
+ href="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.css"
456
+ />
457
+ ```
588
458
 
589
- ```js
590
- import ScaleflexWidget from "@scaleflex/widget-core";
459
+ - add the following JS file before the end of `</body>` in your `HTML` file.
591
460
 
592
- const scaleflexWidget = ScaleflexWidget();
593
- scaleflexWidget.setOptions({
594
- autoProceed: true,
595
- });
461
+ ```html
462
+ <script
463
+ type="text/javascript"
464
+ src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"
465
+ ></script>
596
466
  ```
597
467
 
598
- Individual plugin options can also be changed by using [getPlugin](#scaleflexwidgetgetpluginpluginid)
468
+ ### Usage
599
469
 
600
470
  ```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
- });
471
+ const scaleflexWidgetCore = window.ScaleflexWidget.Core
472
+ ...
473
+ ...
474
+ ...
475
+ const scaleflexWidget = scaleflexWidgetCore(propertiesObject)
608
476
  ```
609
477
 
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_
478
+ ## Parameters
636
479
 
637
- Retries all the failed uploads.
480
+ ### General parameters relevant for all modes
638
481
 
639
- ### `scaleflexWidget.retryUpload(fileId)`
482
+ **container**
483
+ Type: `string` (required)
484
+ Default: `undefined`
485
+ The Scaleflex DAM project token (e.g. *fhlcusomb*), [here](https://www.scaleflex.com/filerobot-free-trial) to get one for free.
640
486
 
641
- Retries a failed upload for a file referenced by its id.
642
-
643
- ### `scaleflexWidget.cancelUploads()`
644
-
645
- emit [cancel-uploads](#cancel-uploads) event and cancel uploads.
487
+ **securityTemplateId**
488
+ Type: `string` (required)
489
+ Default: `undefined`
490
+ 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
491
 
647
- ### `scaleflexWidget.setCoreCommonState(object)`
492
+ **id**
648
493
 
649
- Updates the internal state of the widget's core common state.
650
-
651
- ### `scaleflexWidget.getGlobalState()`
494
+ Type: `string`
495
+ Default: `'scaleflexWidget'`
496
+ Unique identifier for the widget instance (used in HTML selector).
652
497
 
653
- Returns the internal state/store of the widget's.
498
+ **theme**
499
+ Type: `object`
500
+ Default: `{ palette: {...}, breakpoints: {...}, typography: {...}, shadows: {...} }`
501
+ 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:
654
502
 
655
- ### `scaleflexWidget.setUploadPanelFileState(fileId, state)` _Deprecated_ - changed to setFileStateBeforeUpload
503
+ - [color palette](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/palette/entity/default-palette.ts)
504
+ - [typography](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/typography/entity/default-typography.ts)
505
+ - [breakpoints](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/breakpoints/entity/default-breakpoints.ts)
506
+ - [shadows](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/shadows/entity/default-shadows.ts)
656
507
 
657
- updates the state of a file inside the uploads panel before triggering upload.
508
+ Sample override below:
658
509
 
659
- ### `scaleflexWidget.setProgressPanelFileState(fileId, state)` _Deprecated_ - use [`setFileUploadingState`](#setFileUploadingState) instead
510
+ ```js
511
+ theme: {
512
+ palette: {
513
+ "accent-primary": "#479898",
514
+ "accent-primary-hover": "#479898",
515
+ "accent-primary-active": "#479898",
516
+ "accent-stateless": "#479898",
517
+ "link-pressed": "#479898",
518
+ "border-active-bottom": "#479898"
519
+ },
520
+ typography: {
521
+ "title-h6": {
522
+ fontWeight: FontWeight.Medium, // 500
523
+ fontSize: '12px',
524
+ lineHeight: '18px',
525
+ },
526
+ },
527
+ breakpoints: {
528
+ values: {
529
+ xs: 0,
530
+ md: 900,
531
+ xl: 1400
532
+ }
533
+ },
534
+ shadows: {
535
+ "shadow-sm": '6px -4px 12px 0px rgba(146, 166, 188, 0.14)'
536
+ }
537
+ }
538
+ ```
660
539
 
661
- updates the state of a file inside the [Progress Panel](../@scaleflex/widget-progress-panel/#scaleflexwidgetprogress-panel).
540
+ **language** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
541
+ Type: `string`
542
+ Default: `'en'`
543
+ Language code for widget UI.
662
544
 
663
- ### `scaleflexWidget.setFileUploadingState(fileId, state)`
545
+ **locale** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
546
+ Type: `object`
547
+ Default: Default locale from `lib/defaultLocale.js`
548
+ Override UI labels via object (e.g. `{ strings: { loaderLoadingLabel: 'Loading' } }`).
664
549
 
665
- updates the state of a file uploading.
550
+ **debug** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
551
+ Type: `boolean`
552
+ Default: `false`
553
+ Turns on the debug mode by exposing the plugin's debug information to the global window object and turns on the logger.
666
554
 
667
- ### `scaleflexWidget.getFileUploading(fileId)`
555
+ **logger** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
556
+ Type: `object`
557
+ Default:
668
558
 
669
- Returns a file that is uploading.
559
+ ```js
560
+ errorsLogger = {
561
+ debug: (...args) => {},
562
+ warn: (...args) => {},
563
+ error: (...args) => console.error(`[Scaleflex] [${getTimeStamp()}]`, ...args),
564
+ };
565
+ ```
670
566
 
671
- ### `scaleflexWidget.setFilesInfoMetaTags(fileIds, filesInfoMetaTagsData, forceUpdate)`
567
+ Custom logger object for logging messages.
672
568
 
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.
569
+ ### Uploader-related properties
674
570
 
675
- ### `scaleflexWidget.reset()` _Deprecated_
571
+ **autoProceed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
572
+ Type: `boolean`
573
+ Default: `false`
574
+ If `true`, upload process starts immediately after selecting/dropping files.
676
575
 
677
- Returns everything to the initial state of the widget ex. stops all the files uploading, reset their progress and removes all of them.
576
+ **allowMultipleUploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
577
+ Type: `boolean`
578
+ Default: `true`
579
+ Allows simultaneous multiple file uploads.
678
580
 
679
- ### `scaleflexWidget.close()`
581
+ **restrictions** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
582
+ Type: `object`
583
+ Default:
680
584
 
681
- Removes all the installed plugins & closes the current widget's instance.
585
+ ```js
586
+ restrictions: {
587
+ "maxFileSize": null,
588
+ "maxTotalFilesSize": null,
589
+ "hideRestrictionsInformer": null,
590
+ "maxNumberOfFiles": null,
591
+ "minNumberOfFiles": null,
592
+ "allowedFileTypes": null,
593
+ "maxItemsSizeForCompression": null,
594
+ "remoteMaxFolderImportCount": 500,
595
+ "remoteMaxFolderImportSize": 10737418240,
596
+ "remoteMaxFolderDepth": 5,
597
+ "remoteMaxFolderCount": 100
598
+ }
599
+ ```
682
600
 
683
- ### `scaleflexWidget.on('event', handler)`
601
+ Restrictions relevant to Uploader mode:
684
602
 
685
- Adds/Subscribe a handler/callback function to be called on emitting/firing the specified `scaleflexWidget event`, [full list of available events](#events).
603
+ | Property | Type | Default | Description |
604
+ | -------------------------- | ------------------- | ------- | -------------------------------------------------------------------------- |
605
+ | `maxFileSize` | `number` \| `null` | `null` | maximum file size in bytes |
606
+ | `maxTotalFilesSize` | `number` \| `null` | `null` | maximum files size in megabyte |
607
+ | `hideRestrictionsInformer` | `boolean` \| `null` | `null` | hide restrictions informer message |
608
+ | `maxNumberOfFiles` | `number` \| `null` | `null` | maximum number of files to be uploaded simultaneously |
609
+ | `minNumberOfFiles` | `number` \| `null` | `null` | minimum number of files before upload can start |
610
+ | `allowedFileTypes` | `array` \| `null` | `null` | accepted file types or extensions, eg. `['image/*', 'image/jpeg', '.jpg']` |
686
611
 
687
- ### `scaleflexWidget.once('event', handler)`
612
+ 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.):
688
613
 
689
- Same as `scaleflexWidget.on` but the handler is removed after being called once.
614
+ | Property | Type | Default | Description |
615
+ | ---------------------------- | ------------------ | ------------- | ------------------------------------------------------------------------ |
616
+ | `remoteMaxFolderImportCount` | `number` \| `null` | `500` | maximum number of files to import from folders |
617
+ | `remoteMaxFolderImportSize` | `number` \| `null` | `10737418240` | remote upload maximum total size of files to import from folders (bytes) |
618
+ | `remoteMaxFolderDepth` | `number` \| `null` | `5` | remote upload maximum folder depth level for recursive folder imports |
619
+ | `remoteMaxFolderCount` | `number` \| `null` | `100` | remote upload maximum number of folders that can be selected for upload |
690
620
 
691
- ### `scaleflexWidget.off('event', handler)`
621
+ **customUploadedFilesSizeInMb** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
622
+ Type: `number`
623
+ Default: `0`
624
+ A number to consider (add) to the already uploaded files size while checking the restrictions with the maxTotalFilesSize.
692
625
 
693
- Un-subscribe/Removes the specified handler for scaleflexWidget's event.
626
+ **onBeforeFileAdded** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
627
+ Type: `function`
628
+ Default: `(currentFile, files) => currentFile`
629
+ Hook to validate or transform files before they’re added:
694
630
 
695
- ### `scaleflexWidget.info(message, type, timeout)`
631
+ - if the function returns `true`, the file is added to the state
632
+ - if the function returns a modified `file` object the returned object would be added to the state
633
+ - if the function returns `false`, the file is not added to the state
696
634
 
697
- Shows an informer with the specified message to the user:
635
+ **onBeforeUpload** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
636
+ Type: `function`
637
+ Default: `(files) => files`
638
+ Hook before upload starts; can cancel or modify files:
698
639
 
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 |
640
+ - if the function returned `true` the upload would start
641
+ - if returned `files` object the returned object would be processed
642
+ - if returned `false` the uploading process won't start
704
643
 
705
- #### `scaleflexWidget.log(message, type)`
644
+ ### Events and Callbacks
706
645
 
707
- Logs a message in the [`logger`](#logger):
646
+ 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
647
 
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` |
648
+ - **upload**: fired when an upload process is initiated (e.g., user clicks Upload button).
649
+ - **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.
650
+ - **complete**: fired when a batch of uploads is fully done (all files either succeeded or failed).
651
+ - **file-added**, **file-removed**: when a user adds a file to the queue or removes it before upload.
652
+ - **restriction-failed**: when a file is rejected due to restrictions (size/type limits).
653
+ - **explorer:modal-open**, **explorer:modal-close**: when the modal is opened or closed.
654
+ - **export**: when files are selected in Asset Picker mode and "exported" (i.e., the user confirmed selection).
655
+ - **error** (global): if any unexpected error occurs.
713
656
 
714
- ## Events
657
+ > All of them are supported from ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
715
658
 
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:
659
+ 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
660
 
718
- ### `file-added`
661
+ **file-added** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
719
662
 
720
663
  Emitted when a file has been added to the selected files for uploading.
721
664
 
@@ -726,12 +669,12 @@ Emitted when a file has been added to the selected files for uploading.
726
669
  example
727
670
 
728
671
  ```js
729
- scaleflexWidget.on("file-added", (newFile) => {
730
- console.log("The new file object which is added:", newFile);
672
+ scaleflexWidget.on("file-added", (file) => {
673
+ console.log("The new file object which is added:", file);
731
674
  });
732
675
  ```
733
676
 
734
- ### `file-removed`
677
+ **file-removed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
735
678
 
736
679
  Emitted when a file has been removed from the selected files for uploading.
737
680
 
@@ -743,15 +686,15 @@ Emitted when a file has been removed from the selected files for uploading.
743
686
  example
744
687
 
745
688
  ```js
746
- scaleflexWidget.on("file-removed", (removedFile, reason) => {
689
+ scaleflexWidget.on("file-removed", (file, reason) => {
747
690
  console.log(
748
- `The file ${removedFile.name} is removed because ${reason}, file's object:`,
691
+ `The file ${file.name} is removed because ${reason}, file's object:`,
749
692
  removedFile
750
693
  );
751
694
  });
752
695
  ```
753
696
 
754
- ### `upload`
697
+ **upload** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
755
698
 
756
699
  Emitted on creating a new upload process.
757
700
 
@@ -768,9 +711,9 @@ scaleflexWidget.on("upload", (uploadProcess) => {
768
711
  });
769
712
  ```
770
713
 
771
- ### `restriction-failed`
714
+ **restriction-failed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
772
715
 
773
- Emitted when the restriction checking is failed and there is a file doesn't meet the restrictions.
716
+ Emitted when the restriction checking is failed and there is a file not meeting the restrictions.
774
717
 
775
718
  `params`:
776
719
 
@@ -786,7 +729,7 @@ scaleflexWidget.on("restriction-failed", (file, error) => {
786
729
  });
787
730
  ```
788
731
 
789
- ### `upload-started`
732
+ **upload-started** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
790
733
 
791
734
  Emitted when upload is started.
792
735
 
@@ -795,14 +738,16 @@ Emitted when upload is started.
795
738
  - `file`: The file object that started uploading.
796
739
  - `started`: An object contains upload Id, ex. `{ uploadId: upload id assigned to current file }`.
797
740
 
798
- ### `upload-progress`
741
+ **upload-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
799
742
 
800
- Emitted when there is a progress of some file uploading in the upload process.
743
+ Emitted with the upload progress.
801
744
 
802
745
  `params`:
803
746
 
804
747
  - `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 }`.
748
+ - `progress`: An object containing the progress of the file being uploaded, ex. `
749
+ { filerobot: plugin's instance, bytesFinished: 1500, bytesTotal: 3500, uploadId: upload id assigned to current file }.
750
+ `
806
751
 
807
752
  example
808
753
 
@@ -813,7 +758,7 @@ scaleflexWidget.on("upload-progress", (file, progress) => {
813
758
  });
814
759
  ```
815
760
 
816
- ### `upload-success`
761
+ **upload-success** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
817
762
 
818
763
  Emitted when a file is successfully uploaded.
819
764
 
@@ -834,7 +779,7 @@ scaleflexWidget.on("upload-success", (file, response, { uploadId }) => {
834
779
  });
835
780
  ```
836
781
 
837
- ### `upload-error`
782
+ **upload-error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
838
783
 
839
784
  Emitted when a file faced some error/issue while uploading.
840
785
 
@@ -858,7 +803,7 @@ scaleflexWidget.on("upload-error", (file, error, { response, uploadId }) => {
858
803
  });
859
804
  ```
860
805
 
861
- ### `upload-retry`
806
+ **upload-retry** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
862
807
 
863
808
  Emitted on some file uploading is retried.
864
809
 
@@ -874,7 +819,7 @@ scaleflexWidget.on("upload-retry", (fileId) => {
874
819
  });
875
820
  ```
876
821
 
877
- ### `progress`
822
+ **progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
878
823
 
879
824
  Emitted on having a progress of an upload process's total progress.
880
825
 
@@ -890,7 +835,7 @@ scaleflexWidget.on("progress", (totalProgress) => {
890
835
  });
891
836
  ```
892
837
 
893
- ### `cancel-uploads`
838
+ **cancel-uploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
894
839
 
895
840
  Emitted when the whole upload process is canceled (all files uploading are canceled).
896
841
 
@@ -904,7 +849,7 @@ scaleflexWidget.on("cancel-uploads", () => {
904
849
  });
905
850
  ```
906
851
 
907
- ### `complete`
852
+ **complete** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
908
853
 
909
854
  Emitted when the whole upload process done and completed.
910
855
 
@@ -924,7 +869,7 @@ scaleflexWidget.on("complete", ({ failed, uploadId, successful }) => {
924
869
  });
925
870
  ```
926
871
 
927
- ### `items-deleted`
872
+ **items-deleted** ![asset-manager-supported]
928
873
 
929
874
  Emitted when files/folders are deleted.
930
875
 
@@ -942,7 +887,7 @@ scaleflexWidget.on("items-deleted", ({ removedFolders, removedFiles }) => {
942
887
  });
943
888
  ```
944
889
 
945
- ### `error`
890
+ **error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
946
891
 
947
892
  Emitted when the whole upload process faced an error.
948
893
 
@@ -963,7 +908,7 @@ scaleflexWidget.on("error", (filesIds, error, { uploadId }) => {
963
908
  });
964
909
  ```
965
910
 
966
- ### `reset-progress`
911
+ **reset-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
967
912
 
968
913
  Emitted when the upload's progress is reset to 0.
969
914
 
@@ -977,7 +922,7 @@ scaleflexWidget.on("reset-progress", () => {
977
922
  });
978
923
  ```
979
924
 
980
- ### `info-visible`
925
+ **info-visible** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
981
926
 
982
927
  Emitted on showing an `info` message to the user.
983
928
 
@@ -991,7 +936,7 @@ scaleflexWidget.on("info-visible", () => {
991
936
  });
992
937
  ```
993
938
 
994
- ### `info-hidden`
939
+ **info-hidden** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
995
940
 
996
941
  Emitted on hiding an `info` message that were shown to the user.
997
942
 
@@ -1005,9 +950,9 @@ scaleflexWidget.on("info-hidden", () => {
1005
950
  });
1006
951
  ```
1007
952
 
1008
- ### `explorer:modal-open`
953
+ **explorer:modal-open** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
1009
954
 
1010
- Emitted on opening the widget in a modal through the [explorer](../@scaleflex/widget-explorer) plugin.
955
+ Emitted on opening the widget in a modal through the [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) plugin.
1011
956
 
1012
957
  `params`: No params returned.
1013
958
 
@@ -1019,7 +964,7 @@ scaleflexWidget.on("explorer:modal-open", () => {
1019
964
  });
1020
965
  ```
1021
966
 
1022
- ### `explorer:modal-close`
967
+ **explorer:modal-close** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
1023
968
 
1024
969
  Emitted on closing the widget's main modal.
1025
970
 
@@ -1033,7 +978,7 @@ scaleflexWidget.on("explorer:modal-close", () => {
1033
978
  });
1034
979
  ```
1035
980
 
1036
- ### `export`
981
+ **export** ![asset-picker-supported] ![asset-manager-supported]
1037
982
 
1038
983
  emitted when the user downloads a file.
1039
984
 
@@ -1059,26 +1004,171 @@ scaleflexWidget.on(
1059
1004
  );
1060
1005
  ```
1061
1006
 
1062
- ### `url-modified`
1007
+ **url-modified** ![asset-manager-supported]
1063
1008
 
1064
- Emitted when the user uses the [image editor plugin](../@scaleflex/widget-image-editor) in cloudimage mode and changes the url.
1009
+ 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
1010
 
1066
1011
  `params`:
1067
1012
 
1068
1013
  - `modifiedUrl`: The modified url for the image.
1069
1014
  - `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.
1015
+ - `info`: the function that gives you possibility to show a `@scaleflex/widget-informer` message.
1071
1016
 
1072
1017
  example
1073
1018
 
1074
- ```
1019
+ ```js
1075
1020
  scaleflexWidget.on('modified-url', (modifiedUrl, designState, info) => {
1076
1021
  console.log('The new url is', modifiedUrl)
1077
1022
  console.log('Image editor design state:', designState)
1078
1023
  info('Url has changed', 'success', 3000)
1079
1024
  })
1025
+
1026
+ ```
1027
+
1028
+ ### Plugin APIs (advanced use)
1029
+
1030
+ Utilize the widget’s instance APIs to apply different functionalities on the current instance programmatically with the reflection on the UI.
1031
+
1032
+ **scaleflexWidget.getId()**
1033
+
1034
+ Gets the Scaleflex Media Asset Widget's current instance id.
1035
+
1036
+ **scaleflexWidget.use(plugin, pluginOptions)**
1037
+
1038
+ Adds a plugin to the Scaleflex Media Asset Widget's instance.
1039
+
1040
+ ```js
1041
+ // example
1042
+ import ScaleflexWidget from '@scaleflex/widget-core'
1043
+ import Explorer from '@scaleflex/widget-explorer'
1044
+
1045
+ const scaleflexWidget = ScaleflexWidget()
1046
+ scaleflexWidget.use(Explorer, {...})
1080
1047
  ```
1081
1048
 
1049
+ **scaleflexWidget.getPlugin(pluginId)**
1050
+
1051
+ Returns the plugin's instance with the provided id for accessing its methods & state.
1052
+
1053
+ **scaleflexWidget.removePlugin(pluginInstance)**
1054
+
1055
+ 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.
1056
+
1057
+ **scaleflexWidget.setOptions(options)**
1058
+
1059
+ Passes [Properties](https://www.npmjs.com/package/@scaleflex/widget-core#parameters) to the Widget to change properties set during initialization:
1060
+
1061
+ ```js
1062
+ import ScaleflexWidget from "@scaleflex/widget-core";
1063
+
1064
+ const scaleflexWidget = ScaleflexWidget();
1065
+ scaleflexWidget.setOptions({
1066
+ autoProceed: true,
1067
+ });
1068
+ ```
1069
+
1070
+ Individual plugin options can also be changed by using [getPlugin](https://www.npmjs.com/package/@scaleflex/widget-core#scaleflexwidgetgetpluginpluginid)
1071
+
1072
+ ```js
1073
+ import Scaleflex from "@scaleflex/widget-core";
1074
+
1075
+ const scaleflexWidget = ScaleflexWidget();
1076
+ scaleflexWidget.use(Explorer, { id: "Explorer" });
1077
+ scaleflexWidget.getPlugin("Explorer").setOptions({
1078
+ animateOpenClose: false,
1079
+ });
1080
+ ```
1081
+
1082
+ **scaleflexWidget.addFile(fileObject)**
1083
+
1084
+ Adds a file into the widget's state and returns the temporary generated id for that file.
1085
+
1086
+ > [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.
1087
+
1088
+ **scaleflexWidget.getFile(fileId)**
1089
+
1090
+ Gets the file object using its id.
1091
+
1092
+ **scaleflexWidget.removeFile(fileId)**
1093
+
1094
+ Removes a file from the widget's state via its id.
1095
+
1096
+ **scaleflexWidget.getFiles()**
1097
+
1098
+ Returns all the file objects currently loaded in the widget.
1099
+
1100
+ **scaleflexWidget.upload(files, callback)**
1101
+
1102
+ An async function that starts uploading files, returns a promise resolved with an object `result: { successful, failed }` containing:
1103
+
1104
+ - `successful`: array with file objects successfully uploaded.
1105
+ - `failed`: array with files objects for which upload failed.
1106
+
1107
+ **scaleflexWidget.retryUpload(fileId)**
1108
+
1109
+ Retries a failed upload for a file referenced by its id.
1110
+
1111
+ **scaleflexWidget.cancelUploads()**
1112
+
1113
+ emit [cancel-uploads](https://www.npmjs.com/package/@scaleflex/widget-core#cancel-uploads) event and cancel uploads.
1114
+
1115
+ **scaleflexWidget.setCoreCommonState(object)**
1116
+
1117
+ Updates the internal state of the widget's core common state.
1118
+
1119
+ **scaleflexWidget.getGlobalState()**
1120
+
1121
+ Returns the internal state/store of the widget's.
1122
+
1123
+ updates the state of a file inside the uploads panel before triggering upload.
1124
+
1125
+ **scaleflexWidget.setFileUploadingState(fileId, state)**
1126
+
1127
+ updates the state of a file uploading.
1128
+
1129
+ **scaleflexWidget.getFileUploading(fileId)**
1130
+
1131
+ Returns a file that is uploading.
1132
+
1133
+ **scaleflexWidget.setFilesInfoMetaTags(fileIds, filesInfoMetaTagsData, forceUpdate)**
1134
+
1135
+ 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.
1136
+
1137
+ **scaleflexWidget.close()**
1138
+
1139
+ Removes all the installed plugins & closes the current widget's instance.
1140
+
1141
+ **scaleflexWidget.on('event', handler)**
1142
+
1143
+ 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).
1144
+
1145
+ **scaleflexWidget.once('event', handler)**
1146
+
1147
+ Same as `scaleflexWidget.on` but the handler is removed after being called once.
1148
+
1149
+ **scaleflexWidget.off('event', handler)**
1150
+
1151
+ Un-subscribe/Removes the specified handler for scaleflexWidget's event.
1152
+
1153
+ **scaleflexWidget.info(message, type, timeout)**
1154
+
1155
+ Shows an informer with the specified message to the user:
1156
+
1157
+ | Property | Type | Default | Description |
1158
+ | --------- | ------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1159
+ | `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' }` |
1160
+ | `type` | `string` | `info` | choses the type of the informer whether `info, warning or success` |
1161
+ | `timeout` | `number` | `3000` | The duration which the message would still be shown for in milliseconds |
1162
+
1163
+ **scaleflexWidget.log(message, type)**
1164
+
1165
+ Logs a message in the `logger`:
1166
+
1167
+ | Property | Type | Default | Description |
1168
+ | --------- | ------------------- | ----------- | ---------------------------------------------------------------------- |
1169
+ | `message` | `string` *Required* | `undefined` | the message would be logged/added/shown in the logger. |
1170
+ | `type` | `string` | `debug` | the type of that logged message whether `debug/info, warning or error` |
1171
+
1082
1172
  <!-- Variables -->
1083
1173
 
1084
1174
  [npm-url]: https://www.npmjs.com/package/@scaleflex/widget-core
@@ -1097,6 +1187,14 @@ scaleflexWidget.on('modified-url', (modifiedUrl, designState, info) => {
1097
1187
  [filerobot-version-stable]: https://img.shields.io/npm/v/@scaleflex/widget-core/stable?label=stable&style=for-the-badge&logo=npm
1098
1188
  [filerobot-version]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=Version&style=for-the-badge&logo=npm
1099
1189
  [codeSandbox-image]: https://img.shields.io/badge/CodeSandbox-black?style=for-the-badge&logo=CodeSandbox
1190
+ <!-- Supported modes variables -->
1191
+ [uploader-supported]: https://img.shields.io/badge/Uploader-orange
1192
+ [asset-picker-supported]: https://img.shields.io/badge/Asset%20Picker-green
1193
+ [asset-manager-supported]: https://img.shields.io/badge/Asset%20Manager-blue
1194
+ <!-- Usage -->
1195
+ <!-- ![uploader-supported]
1196
+ ![asset-picker-supported]
1197
+ ![asset-manager-supported] -->
1100
1198
 
1101
1199
  ## License
1102
1200