@scaleflex/widget-core 4.0.7-beta.0 → 4.1.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.
- package/CHANGELOG.md +7521 -0
- package/LICENSE +21 -21
- package/README.md +1201 -1201
- package/dist/style.css +94 -58
- package/dist/style.min.css +1 -1
- package/lib/Client.js +5 -5
- package/lib/Plugin.js +40 -40
- package/lib/SassKeyRenewer.js +12 -12
- package/lib/_common.scss +243 -243
- package/lib/_utils.scss +38 -38
- package/lib/_variables.scss +63 -63
- package/lib/index.js +196 -196
- package/lib/slices/common.slice.js +9 -9
- package/lib/slices/info.slice.js +10 -10
- package/lib/slices/uploads.slice.js +9 -9
- package/lib/slices/user.slice.js +9 -9
- package/lib/style.scss +3 -3
- package/package.json +4 -4
- package/types/index.d.ts +301 -301
package/README.md
CHANGED
|
@@ -1,1201 +1,1201 @@
|
|
|
1
|
-
# Scaleflex Media Asset Widget (SMAW)
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
> This is the successor of [Filerobot Media Asset Widget (FMAW) - V3](https://www.npmjs.com/package/@filerobot/core).
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
[![Plugins][plugins-image]](#plugins)
|
|
8
|
-
[![Website][filerobot-image]][sfx-url]
|
|
9
|
-
[![Version][filerobot-version]][version-url]
|
|
10
|
-
[![Version][filerobot-version-latest]][version-url-latest]
|
|
11
|
-
[![Version][filerobot-version-stable]][version-url-stable]
|
|
12
|
-
[![Scaleflex team][made-by-image]][sfx-url]
|
|
13
|
-
[![License][license-image]][license-url]
|
|
14
|
-
[![CodeSandbox][codeSandbox-image]][codeSandbox-url]
|
|
15
|
-
|
|
16
|
-
<div align='center'>
|
|
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"/>
|
|
18
|
-
</div>
|
|
19
|
-
|
|
20
|
-
<details>
|
|
21
|
-
<summary>Table of contents</summary>
|
|
22
|
-
|
|
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)
|
|
41
|
-
- [Usage](#usage)
|
|
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)
|
|
50
|
-
- [License](#license)
|
|
51
|
-
</details>
|
|
52
|
-
|
|
53
|
-
# What is the SMAW?
|
|
54
|
-
|
|
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).
|
|
57
|
-
|
|
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.
|
|
59
|
-
|
|
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.
|
|
61
|
-
|
|
62
|
-
**Key features:**
|
|
63
|
-
|
|
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.
|
|
68
|
-
|
|
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.
|
|
70
|
-
|
|
71
|
-
## Installation (minimal drag and drop upload zone)
|
|
72
|
-
|
|
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.
|
|
74
|
-
|
|
75
|
-
Below is a simple installation example in both ReactJS and Vanilla JS.
|
|
76
|
-
|
|
77
|
-
### ReactJS (over package manager)
|
|
78
|
-
|
|
79
|
-
npm
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
npm install --save @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
yarn
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
yarn add @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
Sample code to instantiate the widget:
|
|
92
|
-
|
|
93
|
-
```js
|
|
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';
|
|
98
|
-
|
|
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';
|
|
102
|
-
|
|
103
|
-
function App() {
|
|
104
|
-
const scaleflexWidgetRef = useRef(null);
|
|
105
|
-
|
|
106
|
-
useEffect(() => {
|
|
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();
|
|
120
|
-
}, []);
|
|
121
|
-
|
|
122
|
-
return <div id="widget-container" style={{ width: '800px', height: '600px' }}></div>;
|
|
123
|
-
}
|
|
124
|
-
|
|
125
|
-
export default App;
|
|
126
|
-
```
|
|
127
|
-
|
|
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.
|
|
129
|
-
|
|
130
|
-
### Vanilla JS (over CDN link, containing all plugins)
|
|
131
|
-
|
|
132
|
-
- add the following CSS file before the end of `</head>` in your `HTML` file
|
|
133
|
-
|
|
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
|
-
```
|
|
141
|
-
|
|
142
|
-
- add the following JS file before the end of `</body>` in your `HTML` file.
|
|
143
|
-
|
|
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
|
-
```
|
|
150
|
-
|
|
151
|
-
Sample code to instantiate the widget:
|
|
152
|
-
|
|
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
|
-
```
|
|
177
|
-
|
|
178
|
-
This achieves the same outcome as the ReactJS example: an inline file explorer/uploader within the `#widget-container` div.
|
|
179
|
-
|
|
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.
|
|
181
|
-
|
|
182
|
-
## Widget modes and use cases
|
|
183
|
-
|
|
184
|
-
The SMAW supports multiple **modes** to fit different use cases:
|
|
185
|
-
|
|
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))
|
|
189
|
-
|
|
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))
|
|
193
|
-
|
|
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))
|
|
197
|
-
|
|
198
|
-
## Core package and plugins
|
|
199
|
-
|
|
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.
|
|
201
|
-
|
|
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).
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
# Quick Start
|
|
223
|
-
|
|
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 !).
|
|
225
|
-
|
|
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.).
|
|
228
|
-
|
|
229
|
-
## Uploader mode (as modal to upload files in the Scaleflex DAM)
|
|
230
|
-
|
|
231
|
-
> Use case: a web app where users upload media (images/videos) or documents (UGC) into a central library.
|
|
232
|
-
|
|
233
|
-
You can implement the SMAW in **Uploader** mode in two ways:
|
|
234
|
-
|
|
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
|
|
237
|
-
|
|
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:
|
|
239
|
-
|
|
240
|
-
```html
|
|
241
|
-
<!-- ... -->
|
|
242
|
-
<button id="open-uploader">Upload Assets</button>
|
|
243
|
-
<!-- ... -->
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
Add the following code to the widget’s instantiation:
|
|
247
|
-
|
|
248
|
-
```js
|
|
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
|
-
// ...
|
|
255
|
-
```
|
|
256
|
-
|
|
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.
|
|
258
|
-
|
|
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.
|
|
260
|
-
|
|
261
|
-
### Enabling upload connectors for import from external storage sources
|
|
262
|
-
|
|
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**:
|
|
264
|
-
|
|
265
|
-
```js
|
|
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);
|
|
289
|
-
|
|
290
|
-
// ...
|
|
291
|
-
```
|
|
292
|
-
|
|
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).
|
|
294
|
-
|
|
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.
|
|
296
|
-
|
|
297
|
-
### Adding the progress panel
|
|
298
|
-
|
|
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:
|
|
300
|
-
|
|
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
|
-
// ...
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
### Customizing the Uploader and listening to events
|
|
325
|
-
|
|
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:
|
|
327
|
-
|
|
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)
|
|
330
|
-
|
|
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).
|
|
332
|
-
|
|
333
|
-
## Asset Picker mode (for searching and selecting assets from the Scaleflex DAM)
|
|
334
|
-
|
|
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.
|
|
336
|
-
|
|
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.
|
|
338
|
-
|
|
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:
|
|
340
|
-
|
|
341
|
-
```js
|
|
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
|
-
...
|
|
352
|
-
```
|
|
353
|
-
|
|
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`).
|
|
357
|
-
|
|
358
|
-
### **Inserting selected selected assets into your application**
|
|
359
|
-
|
|
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:
|
|
361
|
-
|
|
362
|
-
```js
|
|
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
|
-
...
|
|
370
|
-
```
|
|
371
|
-
|
|
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.
|
|
373
|
-
|
|
374
|
-
### Customizing the Asset Picker experience
|
|
375
|
-
|
|
376
|
-
You can use optional parameters from the [Explorer](https://www.npmjs.com/package/@scaleflex/widget-core#properties) plugin, for example:
|
|
377
|
-
|
|
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)
|
|
380
|
-
|
|
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).
|
|
382
|
-
|
|
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.
|
|
384
|
-
|
|
385
|
-
## Asset Manager mode (light DAM)
|
|
386
|
-
|
|
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.
|
|
388
|
-
|
|
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.
|
|
390
|
-
|
|
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:
|
|
392
|
-
|
|
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
|
-
```
|
|
407
|
-
|
|
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.
|
|
409
|
-
|
|
410
|
-
> `useAssetsPicker` governs wether the widget will be in Asset Picker (`useAssetsPicker: true`) mode or Asset Manager (`useAssetsPicker: false`) mode.
|
|
411
|
-
|
|
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.
|
|
413
|
-
|
|
414
|
-
# Documentation (Core package)
|
|
415
|
-
|
|
416
|
-
## ReactJS (over package manager)
|
|
417
|
-
|
|
418
|
-
### Installation
|
|
419
|
-
|
|
420
|
-
npm
|
|
421
|
-
|
|
422
|
-
```bash
|
|
423
|
-
npm install --save @scaleflex/widget-core
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
yarn
|
|
427
|
-
|
|
428
|
-
```bash
|
|
429
|
-
yarn add @scaleflex/widget-core
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
### Usage
|
|
433
|
-
|
|
434
|
-
```js
|
|
435
|
-
import ScaleflexWidget from '@scaleflex/widget-core'
|
|
436
|
-
import "@scaleflex/widget-core/dist/style.min.css";
|
|
437
|
-
|
|
438
|
-
...
|
|
439
|
-
...
|
|
440
|
-
...
|
|
441
|
-
|
|
442
|
-
const scaleflexWidget = ScaleflexWidget(propertiesObject)
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
## Vanilla JS (over CDN link, containing all plugins)
|
|
446
|
-
|
|
447
|
-
### Installation
|
|
448
|
-
|
|
449
|
-
- add the following CSS file before the end of `</head>` in your `HTML` file
|
|
450
|
-
|
|
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
|
-
```
|
|
458
|
-
|
|
459
|
-
- add the following JS file before the end of `</body>` in your `HTML` file.
|
|
460
|
-
|
|
461
|
-
```html
|
|
462
|
-
<script
|
|
463
|
-
type="text/javascript"
|
|
464
|
-
src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"
|
|
465
|
-
></script>
|
|
466
|
-
```
|
|
467
|
-
|
|
468
|
-
### Usage
|
|
469
|
-
|
|
470
|
-
```js
|
|
471
|
-
const scaleflexWidgetCore = window.ScaleflexWidget.Core
|
|
472
|
-
...
|
|
473
|
-
...
|
|
474
|
-
...
|
|
475
|
-
const scaleflexWidget = scaleflexWidgetCore(propertiesObject)
|
|
476
|
-
```
|
|
477
|
-
|
|
478
|
-
## Parameters
|
|
479
|
-
|
|
480
|
-
### General parameters relevant for all modes
|
|
481
|
-
|
|
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.
|
|
486
|
-
|
|
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.
|
|
491
|
-
|
|
492
|
-
**id**
|
|
493
|
-
|
|
494
|
-
Type: `string`
|
|
495
|
-
Default: `'scaleflexWidget'`
|
|
496
|
-
Unique identifier for the widget instance (used in HTML selector).
|
|
497
|
-
|
|
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:
|
|
502
|
-
|
|
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)
|
|
507
|
-
|
|
508
|
-
Sample override below:
|
|
509
|
-
|
|
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
|
-
```
|
|
539
|
-
|
|
540
|
-
**language** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
541
|
-
Type: `string`
|
|
542
|
-
Default: `'en'`
|
|
543
|
-
Language code for widget UI.
|
|
544
|
-
|
|
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' } }`).
|
|
549
|
-
|
|
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.
|
|
554
|
-
|
|
555
|
-
**logger** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
556
|
-
Type: `object`
|
|
557
|
-
Default:
|
|
558
|
-
|
|
559
|
-
```js
|
|
560
|
-
errorsLogger = {
|
|
561
|
-
debug: (...args) => {},
|
|
562
|
-
warn: (...args) => {},
|
|
563
|
-
error: (...args) => console.error(`[Scaleflex] [${getTimeStamp()}]`, ...args),
|
|
564
|
-
};
|
|
565
|
-
```
|
|
566
|
-
|
|
567
|
-
Custom logger object for logging messages.
|
|
568
|
-
|
|
569
|
-
### Uploader-related properties
|
|
570
|
-
|
|
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.
|
|
575
|
-
|
|
576
|
-
**allowMultipleUploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
577
|
-
Type: `boolean`
|
|
578
|
-
Default: `true`
|
|
579
|
-
Allows simultaneous multiple file uploads.
|
|
580
|
-
|
|
581
|
-
**restrictions** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
582
|
-
Type: `object`
|
|
583
|
-
Default:
|
|
584
|
-
|
|
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
|
-
```
|
|
600
|
-
|
|
601
|
-
Restrictions relevant to Uploader mode:
|
|
602
|
-
|
|
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']` |
|
|
611
|
-
|
|
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.):
|
|
613
|
-
|
|
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 |
|
|
620
|
-
|
|
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.
|
|
625
|
-
|
|
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:
|
|
630
|
-
|
|
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
|
|
634
|
-
|
|
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:
|
|
639
|
-
|
|
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
|
|
643
|
-
|
|
644
|
-
### Events and Callbacks
|
|
645
|
-
|
|
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:
|
|
647
|
-
|
|
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.
|
|
656
|
-
|
|
657
|
-
> All of them are supported from ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
658
|
-
|
|
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:
|
|
660
|
-
|
|
661
|
-
**file-added** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
662
|
-
|
|
663
|
-
Emitted when a file has been added to the selected files for uploading.
|
|
664
|
-
|
|
665
|
-
`params`:
|
|
666
|
-
|
|
667
|
-
- `file`: The file object whom thumbnail is generated.
|
|
668
|
-
|
|
669
|
-
example
|
|
670
|
-
|
|
671
|
-
```js
|
|
672
|
-
scaleflexWidget.on("file-added", (file) => {
|
|
673
|
-
console.log("The new file object which is added:", file);
|
|
674
|
-
});
|
|
675
|
-
```
|
|
676
|
-
|
|
677
|
-
**file-removed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
678
|
-
|
|
679
|
-
Emitted when a file has been removed from the selected files for uploading.
|
|
680
|
-
|
|
681
|
-
`params`:
|
|
682
|
-
|
|
683
|
-
- `file`: The file object removed.
|
|
684
|
-
- `deletionReason`: The reason for deleting the file or from where the deletion has done might be provided or not.
|
|
685
|
-
|
|
686
|
-
example
|
|
687
|
-
|
|
688
|
-
```js
|
|
689
|
-
scaleflexWidget.on("file-removed", (file, reason) => {
|
|
690
|
-
console.log(
|
|
691
|
-
`The file ${file.name} is removed because ${reason}, file's object:`,
|
|
692
|
-
removedFile
|
|
693
|
-
);
|
|
694
|
-
});
|
|
695
|
-
```
|
|
696
|
-
|
|
697
|
-
**upload** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
698
|
-
|
|
699
|
-
Emitted on creating a new upload process.
|
|
700
|
-
|
|
701
|
-
`params`:
|
|
702
|
-
|
|
703
|
-
- `object`: An object contains both the uploading process id and the the files ids for files to be uploaded, ex. `{ id: uploadId, filesIds: fileIds, files }`.
|
|
704
|
-
|
|
705
|
-
example
|
|
706
|
-
|
|
707
|
-
```js
|
|
708
|
-
scaleflexWidget.on("upload", (uploadProcess) => {
|
|
709
|
-
console.log("Upload started with upload id: ", uploadProcess.id);
|
|
710
|
-
console.log("Contains the following file ids", uploadProcess.filesIds);
|
|
711
|
-
});
|
|
712
|
-
```
|
|
713
|
-
|
|
714
|
-
**restriction-failed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
715
|
-
|
|
716
|
-
Emitted when the restriction checking is failed and there is a file not meeting the restrictions.
|
|
717
|
-
|
|
718
|
-
`params`:
|
|
719
|
-
|
|
720
|
-
- `file`: The file object that has failed the check.
|
|
721
|
-
- `error`: The error faced/fired during the check.
|
|
722
|
-
|
|
723
|
-
example
|
|
724
|
-
|
|
725
|
-
```js
|
|
726
|
-
scaleflexWidget.on("restriction-failed", (file, error) => {
|
|
727
|
-
console.log("Couldnt process the following file object", file);
|
|
728
|
-
console.log("As the following error fired:", error);
|
|
729
|
-
});
|
|
730
|
-
```
|
|
731
|
-
|
|
732
|
-
**upload-started** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
733
|
-
|
|
734
|
-
Emitted when upload is started.
|
|
735
|
-
|
|
736
|
-
`params`:
|
|
737
|
-
|
|
738
|
-
- `file`: The file object that started uploading.
|
|
739
|
-
- `started`: An object contains upload Id, ex. `{ uploadId: upload id assigned to current file }`.
|
|
740
|
-
|
|
741
|
-
**upload-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
742
|
-
|
|
743
|
-
Emitted with the upload progress.
|
|
744
|
-
|
|
745
|
-
`params`:
|
|
746
|
-
|
|
747
|
-
- `file`: The file object that has some progress in its uploading.
|
|
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
|
-
`
|
|
751
|
-
|
|
752
|
-
example
|
|
753
|
-
|
|
754
|
-
```js
|
|
755
|
-
scaleflexWidget.on("upload-progress", (file, progress) => {
|
|
756
|
-
console.log("The following file object progressed", file);
|
|
757
|
-
console.log("The progress object is as following", progress);
|
|
758
|
-
});
|
|
759
|
-
```
|
|
760
|
-
|
|
761
|
-
**upload-success** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
762
|
-
|
|
763
|
-
Emitted when a file is successfully uploaded.
|
|
764
|
-
|
|
765
|
-
`params`:
|
|
766
|
-
|
|
767
|
-
- `file`: The file object that has uploaded.
|
|
768
|
-
- `response`: The upload request response received.
|
|
769
|
-
- `options`: object that contains the uploadId
|
|
770
|
-
|
|
771
|
-
example
|
|
772
|
-
|
|
773
|
-
```js
|
|
774
|
-
scaleflexWidget.on("upload-success", (file, response, { uploadId }) => {
|
|
775
|
-
console.log(
|
|
776
|
-
`The ${file.name} with the object ${file} is uploaded ${uploadId} and the whole response`,
|
|
777
|
-
response
|
|
778
|
-
);
|
|
779
|
-
});
|
|
780
|
-
```
|
|
781
|
-
|
|
782
|
-
**upload-error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
783
|
-
|
|
784
|
-
Emitted when a file faced some error/issue while uploading.
|
|
785
|
-
|
|
786
|
-
`params`:
|
|
787
|
-
|
|
788
|
-
- `file`: The file object which fired the error.
|
|
789
|
-
- `error`: object that contains error details, upload response and uploadId that was assigned to current file.
|
|
790
|
-
- `options`: object that contains the upload response and uploadId
|
|
791
|
-
|
|
792
|
-
example
|
|
793
|
-
|
|
794
|
-
```js
|
|
795
|
-
scaleflexWidget.on("upload-error", (file, error, { response, uploadId }) => {
|
|
796
|
-
console.log(
|
|
797
|
-
"File faced that error while uploading",
|
|
798
|
-
file,
|
|
799
|
-
error,
|
|
800
|
-
response,
|
|
801
|
-
uploadId
|
|
802
|
-
);
|
|
803
|
-
});
|
|
804
|
-
```
|
|
805
|
-
|
|
806
|
-
**upload-retry** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
807
|
-
|
|
808
|
-
Emitted on some file uploading is retried.
|
|
809
|
-
|
|
810
|
-
`params`:
|
|
811
|
-
|
|
812
|
-
- `fileId`: The id of the file which its upload process is retried.
|
|
813
|
-
|
|
814
|
-
example
|
|
815
|
-
|
|
816
|
-
```js
|
|
817
|
-
scaleflexWidget.on("upload-retry", (fileId) => {
|
|
818
|
-
console.log("The following file id is being re-uploaded:", fileId);
|
|
819
|
-
});
|
|
820
|
-
```
|
|
821
|
-
|
|
822
|
-
**progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
823
|
-
|
|
824
|
-
Emitted on having a progress of an upload process's total progress.
|
|
825
|
-
|
|
826
|
-
`params`:
|
|
827
|
-
|
|
828
|
-
- `totalProgress`: The total progress value of the current uploading process.
|
|
829
|
-
|
|
830
|
-
example
|
|
831
|
-
|
|
832
|
-
```js
|
|
833
|
-
scaleflexWidget.on("progress", (totalProgress) => {
|
|
834
|
-
console.log("The uploading total progress for now: ", totalProgress);
|
|
835
|
-
});
|
|
836
|
-
```
|
|
837
|
-
|
|
838
|
-
**cancel-uploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
839
|
-
|
|
840
|
-
Emitted when the whole upload process is canceled (all files uploading are canceled).
|
|
841
|
-
|
|
842
|
-
`params`: No params returned.
|
|
843
|
-
|
|
844
|
-
example
|
|
845
|
-
|
|
846
|
-
```js
|
|
847
|
-
scaleflexWidget.on("cancel-uploads", () => {
|
|
848
|
-
console.log("The upload is canceled");
|
|
849
|
-
});
|
|
850
|
-
```
|
|
851
|
-
|
|
852
|
-
**complete** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
853
|
-
|
|
854
|
-
Emitted when the whole upload process done and completed.
|
|
855
|
-
|
|
856
|
-
`params`:
|
|
857
|
-
|
|
858
|
-
- `completionObject`: An object contains the results of the completed upload process, ex. `{ failed: failedFiles, uploadId: ..., successful: uploadedFiles }`.
|
|
859
|
-
|
|
860
|
-
example
|
|
861
|
-
|
|
862
|
-
```js
|
|
863
|
-
scaleflexWidget.on("complete", ({ failed, uploadId, successful }) => {
|
|
864
|
-
console.log(
|
|
865
|
-
`The upload ${uploadId} is completed with following results success then failed files`,
|
|
866
|
-
successful,
|
|
867
|
-
failed
|
|
868
|
-
);
|
|
869
|
-
});
|
|
870
|
-
```
|
|
871
|
-
|
|
872
|
-
**items-deleted** ![asset-manager-supported]
|
|
873
|
-
|
|
874
|
-
Emitted when files/folders are deleted.
|
|
875
|
-
|
|
876
|
-
`params`:
|
|
877
|
-
|
|
878
|
-
- `detailsObject`: An object contains details of removed items, ex. `{ removedFolders: [...], removedFiles: [...] }`.
|
|
879
|
-
|
|
880
|
-
example
|
|
881
|
-
|
|
882
|
-
```js
|
|
883
|
-
scaleflexWidget.on("items-deleted", ({ removedFolders, removedFiles }) => {
|
|
884
|
-
console.log("Items deleted:");
|
|
885
|
-
console.log("Removed folders:", removedFolders);
|
|
886
|
-
console.log("Removed files:", removedFiles);
|
|
887
|
-
});
|
|
888
|
-
```
|
|
889
|
-
|
|
890
|
-
**error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
891
|
-
|
|
892
|
-
Emitted when the whole upload process faced an error.
|
|
893
|
-
|
|
894
|
-
`params`:
|
|
895
|
-
|
|
896
|
-
- `filesIds`: files ids that have an error.
|
|
897
|
-
- `error`: The error shown of the uploading process.
|
|
898
|
-
- `uploadId`: The id of the errored uploading process.
|
|
899
|
-
|
|
900
|
-
example
|
|
901
|
-
|
|
902
|
-
```js
|
|
903
|
-
scaleflexWidget.on("error", (filesIds, error, { uploadId }) => {
|
|
904
|
-
console.log(
|
|
905
|
-
`The upload with id ${uploadId} faced this error while uploading`,
|
|
906
|
-
error
|
|
907
|
-
);
|
|
908
|
-
});
|
|
909
|
-
```
|
|
910
|
-
|
|
911
|
-
**reset-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
912
|
-
|
|
913
|
-
Emitted when the upload's progress is reset to 0.
|
|
914
|
-
|
|
915
|
-
`params`: No params returned.
|
|
916
|
-
|
|
917
|
-
example
|
|
918
|
-
|
|
919
|
-
```js
|
|
920
|
-
scaleflexWidget.on("reset-progress", () => {
|
|
921
|
-
console.log("The progress is reset");
|
|
922
|
-
});
|
|
923
|
-
```
|
|
924
|
-
|
|
925
|
-
**info-visible** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
926
|
-
|
|
927
|
-
Emitted on showing an `info` message to the user.
|
|
928
|
-
|
|
929
|
-
`params`: No params returned.
|
|
930
|
-
|
|
931
|
-
example
|
|
932
|
-
|
|
933
|
-
```js
|
|
934
|
-
scaleflexWidget.on("info-visible", () => {
|
|
935
|
-
console.log("inFo message shown.");
|
|
936
|
-
});
|
|
937
|
-
```
|
|
938
|
-
|
|
939
|
-
**info-hidden** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
940
|
-
|
|
941
|
-
Emitted on hiding an `info` message that were shown to the user.
|
|
942
|
-
|
|
943
|
-
`params`: No params returned.
|
|
944
|
-
|
|
945
|
-
example
|
|
946
|
-
|
|
947
|
-
```js
|
|
948
|
-
scaleflexWidget.on("info-hidden", () => {
|
|
949
|
-
console.log("The progress is hidden.");
|
|
950
|
-
});
|
|
951
|
-
```
|
|
952
|
-
|
|
953
|
-
**explorer:modal-open** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
954
|
-
|
|
955
|
-
Emitted on opening the widget in a modal through the [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) plugin.
|
|
956
|
-
|
|
957
|
-
`params`: No params returned.
|
|
958
|
-
|
|
959
|
-
example
|
|
960
|
-
|
|
961
|
-
```js
|
|
962
|
-
scaleflexWidget.on("explorer:modal-open", () => {
|
|
963
|
-
console.log("The widget's explorer modal is opened .");
|
|
964
|
-
});
|
|
965
|
-
```
|
|
966
|
-
|
|
967
|
-
**explorer:modal-close** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
968
|
-
|
|
969
|
-
Emitted on closing the widget's main modal.
|
|
970
|
-
|
|
971
|
-
`params`: No params returned.
|
|
972
|
-
|
|
973
|
-
example
|
|
974
|
-
|
|
975
|
-
```js
|
|
976
|
-
scaleflexWidget.on("explorer:modal-close", () => {
|
|
977
|
-
console.log("The widget's modal is closed.");
|
|
978
|
-
});
|
|
979
|
-
```
|
|
980
|
-
|
|
981
|
-
**export** ![asset-picker-supported] ![asset-manager-supported]
|
|
982
|
-
|
|
983
|
-
emitted when the user downloads a file.
|
|
984
|
-
|
|
985
|
-
`params`:
|
|
986
|
-
|
|
987
|
-
- `files`: An array of files checked/selected for exporting.
|
|
988
|
-
- `popupExportSucessMsgFn`: A function if called will show exported successfully pop-up to the user.
|
|
989
|
-
- `downloadFilesPackagedFn`: A function if called will download files (the files passed in the first argument if nothing passed then the files exported will be used) as ZIP and show download progress in widget (item's Uuid is used & must exists on backend's side -- NOT FULLY WORKING --).
|
|
990
|
-
- `downloadFileFn`: A function if called will download one file (the file passed as first argument if nothing passed then the first file in exported files will be used) directly without packaging/zipping it and show download progress in widget (`file.url.download` link is used in download and fallbacks to `file.url.permalink`).
|
|
991
|
-
|
|
992
|
-
example
|
|
993
|
-
|
|
994
|
-
```js
|
|
995
|
-
scaleflexWidget.on(
|
|
996
|
-
"export",
|
|
997
|
-
(files, popupExportSucessMsgFn, downloadFilesPackagedFn, downloadFileFn) => {
|
|
998
|
-
console.log("The following files are chosen to be exported", files);
|
|
999
|
-
popupExportSucessMsgFn(); // shows exported successfully message as pop-up.
|
|
1000
|
-
downloadFilesPackagedFn(files.slice(1).map(({ file }) => file)); // no need to pass file.slice(1) if u would download all exported files.
|
|
1001
|
-
const { file } = file[0];
|
|
1002
|
-
downloadFileFn({ ...file, url: { ...file.url, download: files[0].link } }); // no need to pass file[0] if u would download the first file of exported files.
|
|
1003
|
-
}
|
|
1004
|
-
);
|
|
1005
|
-
```
|
|
1006
|
-
|
|
1007
|
-
**url-modified** ![asset-manager-supported]
|
|
1008
|
-
|
|
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.
|
|
1010
|
-
|
|
1011
|
-
`params`:
|
|
1012
|
-
|
|
1013
|
-
- `modifiedUrl`: The modified url for the image.
|
|
1014
|
-
- `designState`: The image editor's design state object.
|
|
1015
|
-
- `info`: the function that gives you possibility to show a `@scaleflex/widget-informer` message.
|
|
1016
|
-
|
|
1017
|
-
example
|
|
1018
|
-
|
|
1019
|
-
```js
|
|
1020
|
-
scaleflexWidget.on('modified-url', (modifiedUrl, designState, info) => {
|
|
1021
|
-
console.log('The new url is', modifiedUrl)
|
|
1022
|
-
console.log('Image editor design state:', designState)
|
|
1023
|
-
info('Url has changed', 'success', 3000)
|
|
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, {...})
|
|
1047
|
-
```
|
|
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
|
-
|
|
1172
|
-
<!-- Variables -->
|
|
1173
|
-
|
|
1174
|
-
[npm-url]: https://www.npmjs.com/package/@scaleflex/widget-core
|
|
1175
|
-
[license-url]: https://opensource.org/licenses/MIT
|
|
1176
|
-
[sfx-url]: https://www.scaleflex.com/
|
|
1177
|
-
[version-url-latest]: https://www.npmjs.com/package/@scaleflex/widget-core
|
|
1178
|
-
[version-url-stable]: https://www.npmjs.com/package/@scaleflex/widget-core/v/stable
|
|
1179
|
-
[version-url]: https://www.npmjs.com/package/@scaleflex/widget-core
|
|
1180
|
-
[codeSandbox-url]: https://codesandbox.io/p/sandbox/r9scjl
|
|
1181
|
-
[npm-image]: https://img.shields.io/npm/v/@telus/remark-config.svg?style=for-the-badge&logo=npm
|
|
1182
|
-
[license-image]: https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge
|
|
1183
|
-
[made-by-image]: https://img.shields.io/badge/%3C%2F%3E%20with%20%E2%99%A5%20by-the%20Scaleflex%20team-6986fa.svg?style=for-the-badge
|
|
1184
|
-
[plugins-image]: https://img.shields.io/static/v1?label=Scaleflex&message=Plugins&color=yellow&style=for-the-badge
|
|
1185
|
-
[filerobot-image]: https://img.shields.io/static/v1?label=Scaleflex&message=website&color=orange&style=for-the-badge
|
|
1186
|
-
[filerobot-version-latest]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=latest&style=for-the-badge&logo=npm
|
|
1187
|
-
[filerobot-version-stable]: https://img.shields.io/npm/v/@scaleflex/widget-core/stable?label=stable&style=for-the-badge&logo=npm
|
|
1188
|
-
[filerobot-version]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=Version&style=for-the-badge&logo=npm
|
|
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] -->
|
|
1198
|
-
|
|
1199
|
-
## License
|
|
1200
|
-
|
|
1201
|
-
The Scaleflex Media Asset Widget (SMAW) is provided under the [MIT License](https://opensource.org/licenses/MIT)
|
|
1
|
+
# Scaleflex Media Asset Widget (SMAW)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
> This is the successor of [Filerobot Media Asset Widget (FMAW) - V3](https://www.npmjs.com/package/@filerobot/core).
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
[![Plugins][plugins-image]](#plugins)
|
|
8
|
+
[![Website][filerobot-image]][sfx-url]
|
|
9
|
+
[![Version][filerobot-version]][version-url]
|
|
10
|
+
[![Version][filerobot-version-latest]][version-url-latest]
|
|
11
|
+
[![Version][filerobot-version-stable]][version-url-stable]
|
|
12
|
+
[![Scaleflex team][made-by-image]][sfx-url]
|
|
13
|
+
[![License][license-image]][license-url]
|
|
14
|
+
[![CodeSandbox][codeSandbox-image]][codeSandbox-url]
|
|
15
|
+
|
|
16
|
+
<div align='center'>
|
|
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"/>
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
<details>
|
|
21
|
+
<summary>Table of contents</summary>
|
|
22
|
+
|
|
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)
|
|
41
|
+
- [Usage](#usage)
|
|
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)
|
|
50
|
+
- [License](#license)
|
|
51
|
+
</details>
|
|
52
|
+
|
|
53
|
+
# What is the SMAW?
|
|
54
|
+
|
|
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).
|
|
57
|
+
|
|
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.
|
|
59
|
+
|
|
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.
|
|
61
|
+
|
|
62
|
+
**Key features:**
|
|
63
|
+
|
|
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.
|
|
68
|
+
|
|
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.
|
|
70
|
+
|
|
71
|
+
## Installation (minimal drag and drop upload zone)
|
|
72
|
+
|
|
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.
|
|
74
|
+
|
|
75
|
+
Below is a simple installation example in both ReactJS and Vanilla JS.
|
|
76
|
+
|
|
77
|
+
### ReactJS (over package manager)
|
|
78
|
+
|
|
79
|
+
npm
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
npm install --save @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
yarn
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
yarn add @scaleflex/widget-core @scaleflex/widget-explorer @scaleflex/widget-xhr-upload
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Sample code to instantiate the widget:
|
|
92
|
+
|
|
93
|
+
```js
|
|
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';
|
|
98
|
+
|
|
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';
|
|
102
|
+
|
|
103
|
+
function App() {
|
|
104
|
+
const scaleflexWidgetRef = useRef(null);
|
|
105
|
+
|
|
106
|
+
useEffect(() => {
|
|
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();
|
|
120
|
+
}, []);
|
|
121
|
+
|
|
122
|
+
return <div id="widget-container" style={{ width: '800px', height: '600px' }}></div>;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export default App;
|
|
126
|
+
```
|
|
127
|
+
|
|
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.
|
|
129
|
+
|
|
130
|
+
### Vanilla JS (over CDN link, containing all plugins)
|
|
131
|
+
|
|
132
|
+
- add the following CSS file before the end of `</head>` in your `HTML` file
|
|
133
|
+
|
|
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
|
+
```
|
|
141
|
+
|
|
142
|
+
- add the following JS file before the end of `</body>` in your `HTML` file.
|
|
143
|
+
|
|
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
|
+
```
|
|
150
|
+
|
|
151
|
+
Sample code to instantiate the widget:
|
|
152
|
+
|
|
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
|
+
```
|
|
177
|
+
|
|
178
|
+
This achieves the same outcome as the ReactJS example: an inline file explorer/uploader within the `#widget-container` div.
|
|
179
|
+
|
|
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.
|
|
181
|
+
|
|
182
|
+
## Widget modes and use cases
|
|
183
|
+
|
|
184
|
+
The SMAW supports multiple **modes** to fit different use cases:
|
|
185
|
+
|
|
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))
|
|
189
|
+
|
|
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))
|
|
193
|
+
|
|
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))
|
|
197
|
+
|
|
198
|
+
## Core package and plugins
|
|
199
|
+
|
|
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.
|
|
201
|
+
|
|
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).
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
# Quick Start
|
|
223
|
+
|
|
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 !).
|
|
225
|
+
|
|
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.).
|
|
228
|
+
|
|
229
|
+
## Uploader mode (as modal to upload files in the Scaleflex DAM)
|
|
230
|
+
|
|
231
|
+
> Use case: a web app where users upload media (images/videos) or documents (UGC) into a central library.
|
|
232
|
+
|
|
233
|
+
You can implement the SMAW in **Uploader** mode in two ways:
|
|
234
|
+
|
|
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
|
|
237
|
+
|
|
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:
|
|
239
|
+
|
|
240
|
+
```html
|
|
241
|
+
<!-- ... -->
|
|
242
|
+
<button id="open-uploader">Upload Assets</button>
|
|
243
|
+
<!-- ... -->
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Add the following code to the widget’s instantiation:
|
|
247
|
+
|
|
248
|
+
```js
|
|
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
|
+
// ...
|
|
255
|
+
```
|
|
256
|
+
|
|
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.
|
|
258
|
+
|
|
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.
|
|
260
|
+
|
|
261
|
+
### Enabling upload connectors for import from external storage sources
|
|
262
|
+
|
|
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**:
|
|
264
|
+
|
|
265
|
+
```js
|
|
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);
|
|
289
|
+
|
|
290
|
+
// ...
|
|
291
|
+
```
|
|
292
|
+
|
|
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).
|
|
294
|
+
|
|
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.
|
|
296
|
+
|
|
297
|
+
### Adding the progress panel
|
|
298
|
+
|
|
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:
|
|
300
|
+
|
|
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
|
+
// ...
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
### Customizing the Uploader and listening to events
|
|
325
|
+
|
|
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:
|
|
327
|
+
|
|
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)
|
|
330
|
+
|
|
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).
|
|
332
|
+
|
|
333
|
+
## Asset Picker mode (for searching and selecting assets from the Scaleflex DAM)
|
|
334
|
+
|
|
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.
|
|
336
|
+
|
|
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.
|
|
338
|
+
|
|
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:
|
|
340
|
+
|
|
341
|
+
```js
|
|
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
|
+
...
|
|
352
|
+
```
|
|
353
|
+
|
|
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`).
|
|
357
|
+
|
|
358
|
+
### **Inserting selected selected assets into your application**
|
|
359
|
+
|
|
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:
|
|
361
|
+
|
|
362
|
+
```js
|
|
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
|
+
...
|
|
370
|
+
```
|
|
371
|
+
|
|
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.
|
|
373
|
+
|
|
374
|
+
### Customizing the Asset Picker experience
|
|
375
|
+
|
|
376
|
+
You can use optional parameters from the [Explorer](https://www.npmjs.com/package/@scaleflex/widget-core#properties) plugin, for example:
|
|
377
|
+
|
|
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)
|
|
380
|
+
|
|
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).
|
|
382
|
+
|
|
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.
|
|
384
|
+
|
|
385
|
+
## Asset Manager mode (light DAM)
|
|
386
|
+
|
|
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.
|
|
388
|
+
|
|
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.
|
|
390
|
+
|
|
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:
|
|
392
|
+
|
|
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
|
+
```
|
|
407
|
+
|
|
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.
|
|
409
|
+
|
|
410
|
+
> `useAssetsPicker` governs wether the widget will be in Asset Picker (`useAssetsPicker: true`) mode or Asset Manager (`useAssetsPicker: false`) mode.
|
|
411
|
+
|
|
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.
|
|
413
|
+
|
|
414
|
+
# Documentation (Core package)
|
|
415
|
+
|
|
416
|
+
## ReactJS (over package manager)
|
|
417
|
+
|
|
418
|
+
### Installation
|
|
419
|
+
|
|
420
|
+
npm
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
npm install --save @scaleflex/widget-core
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
yarn
|
|
427
|
+
|
|
428
|
+
```bash
|
|
429
|
+
yarn add @scaleflex/widget-core
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
### Usage
|
|
433
|
+
|
|
434
|
+
```js
|
|
435
|
+
import ScaleflexWidget from '@scaleflex/widget-core'
|
|
436
|
+
import "@scaleflex/widget-core/dist/style.min.css";
|
|
437
|
+
|
|
438
|
+
...
|
|
439
|
+
...
|
|
440
|
+
...
|
|
441
|
+
|
|
442
|
+
const scaleflexWidget = ScaleflexWidget(propertiesObject)
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
## Vanilla JS (over CDN link, containing all plugins)
|
|
446
|
+
|
|
447
|
+
### Installation
|
|
448
|
+
|
|
449
|
+
- add the following CSS file before the end of `</head>` in your `HTML` file
|
|
450
|
+
|
|
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
|
+
```
|
|
458
|
+
|
|
459
|
+
- add the following JS file before the end of `</body>` in your `HTML` file.
|
|
460
|
+
|
|
461
|
+
```html
|
|
462
|
+
<script
|
|
463
|
+
type="text/javascript"
|
|
464
|
+
src="https://cdn.scaleflex.com/plugins/widget/v4/stable/scaleflex-widget.min.js"
|
|
465
|
+
></script>
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
### Usage
|
|
469
|
+
|
|
470
|
+
```js
|
|
471
|
+
const scaleflexWidgetCore = window.ScaleflexWidget.Core
|
|
472
|
+
...
|
|
473
|
+
...
|
|
474
|
+
...
|
|
475
|
+
const scaleflexWidget = scaleflexWidgetCore(propertiesObject)
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
## Parameters
|
|
479
|
+
|
|
480
|
+
### General parameters relevant for all modes
|
|
481
|
+
|
|
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.
|
|
486
|
+
|
|
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.
|
|
491
|
+
|
|
492
|
+
**id**
|
|
493
|
+
|
|
494
|
+
Type: `string`
|
|
495
|
+
Default: `'scaleflexWidget'`
|
|
496
|
+
Unique identifier for the widget instance (used in HTML selector).
|
|
497
|
+
|
|
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:
|
|
502
|
+
|
|
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)
|
|
507
|
+
|
|
508
|
+
Sample override below:
|
|
509
|
+
|
|
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
|
+
```
|
|
539
|
+
|
|
540
|
+
**language** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
541
|
+
Type: `string`
|
|
542
|
+
Default: `'en'`
|
|
543
|
+
Language code for widget UI.
|
|
544
|
+
|
|
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' } }`).
|
|
549
|
+
|
|
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.
|
|
554
|
+
|
|
555
|
+
**logger** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
556
|
+
Type: `object`
|
|
557
|
+
Default:
|
|
558
|
+
|
|
559
|
+
```js
|
|
560
|
+
errorsLogger = {
|
|
561
|
+
debug: (...args) => {},
|
|
562
|
+
warn: (...args) => {},
|
|
563
|
+
error: (...args) => console.error(`[Scaleflex] [${getTimeStamp()}]`, ...args),
|
|
564
|
+
};
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
Custom logger object for logging messages.
|
|
568
|
+
|
|
569
|
+
### Uploader-related properties
|
|
570
|
+
|
|
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.
|
|
575
|
+
|
|
576
|
+
**allowMultipleUploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
577
|
+
Type: `boolean`
|
|
578
|
+
Default: `true`
|
|
579
|
+
Allows simultaneous multiple file uploads.
|
|
580
|
+
|
|
581
|
+
**restrictions** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
582
|
+
Type: `object`
|
|
583
|
+
Default:
|
|
584
|
+
|
|
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
|
+
```
|
|
600
|
+
|
|
601
|
+
Restrictions relevant to Uploader mode:
|
|
602
|
+
|
|
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']` |
|
|
611
|
+
|
|
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.):
|
|
613
|
+
|
|
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 |
|
|
620
|
+
|
|
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.
|
|
625
|
+
|
|
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:
|
|
630
|
+
|
|
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
|
|
634
|
+
|
|
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:
|
|
639
|
+
|
|
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
|
|
643
|
+
|
|
644
|
+
### Events and Callbacks
|
|
645
|
+
|
|
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:
|
|
647
|
+
|
|
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.
|
|
656
|
+
|
|
657
|
+
> All of them are supported from ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
658
|
+
|
|
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:
|
|
660
|
+
|
|
661
|
+
**file-added** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
662
|
+
|
|
663
|
+
Emitted when a file has been added to the selected files for uploading.
|
|
664
|
+
|
|
665
|
+
`params`:
|
|
666
|
+
|
|
667
|
+
- `file`: The file object whom thumbnail is generated.
|
|
668
|
+
|
|
669
|
+
example
|
|
670
|
+
|
|
671
|
+
```js
|
|
672
|
+
scaleflexWidget.on("file-added", (file) => {
|
|
673
|
+
console.log("The new file object which is added:", file);
|
|
674
|
+
});
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
**file-removed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
678
|
+
|
|
679
|
+
Emitted when a file has been removed from the selected files for uploading.
|
|
680
|
+
|
|
681
|
+
`params`:
|
|
682
|
+
|
|
683
|
+
- `file`: The file object removed.
|
|
684
|
+
- `deletionReason`: The reason for deleting the file or from where the deletion has done might be provided or not.
|
|
685
|
+
|
|
686
|
+
example
|
|
687
|
+
|
|
688
|
+
```js
|
|
689
|
+
scaleflexWidget.on("file-removed", (file, reason) => {
|
|
690
|
+
console.log(
|
|
691
|
+
`The file ${file.name} is removed because ${reason}, file's object:`,
|
|
692
|
+
removedFile
|
|
693
|
+
);
|
|
694
|
+
});
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
**upload** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
698
|
+
|
|
699
|
+
Emitted on creating a new upload process.
|
|
700
|
+
|
|
701
|
+
`params`:
|
|
702
|
+
|
|
703
|
+
- `object`: An object contains both the uploading process id and the the files ids for files to be uploaded, ex. `{ id: uploadId, filesIds: fileIds, files }`.
|
|
704
|
+
|
|
705
|
+
example
|
|
706
|
+
|
|
707
|
+
```js
|
|
708
|
+
scaleflexWidget.on("upload", (uploadProcess) => {
|
|
709
|
+
console.log("Upload started with upload id: ", uploadProcess.id);
|
|
710
|
+
console.log("Contains the following file ids", uploadProcess.filesIds);
|
|
711
|
+
});
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
**restriction-failed** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
715
|
+
|
|
716
|
+
Emitted when the restriction checking is failed and there is a file not meeting the restrictions.
|
|
717
|
+
|
|
718
|
+
`params`:
|
|
719
|
+
|
|
720
|
+
- `file`: The file object that has failed the check.
|
|
721
|
+
- `error`: The error faced/fired during the check.
|
|
722
|
+
|
|
723
|
+
example
|
|
724
|
+
|
|
725
|
+
```js
|
|
726
|
+
scaleflexWidget.on("restriction-failed", (file, error) => {
|
|
727
|
+
console.log("Couldnt process the following file object", file);
|
|
728
|
+
console.log("As the following error fired:", error);
|
|
729
|
+
});
|
|
730
|
+
```
|
|
731
|
+
|
|
732
|
+
**upload-started** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
733
|
+
|
|
734
|
+
Emitted when upload is started.
|
|
735
|
+
|
|
736
|
+
`params`:
|
|
737
|
+
|
|
738
|
+
- `file`: The file object that started uploading.
|
|
739
|
+
- `started`: An object contains upload Id, ex. `{ uploadId: upload id assigned to current file }`.
|
|
740
|
+
|
|
741
|
+
**upload-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
742
|
+
|
|
743
|
+
Emitted with the upload progress.
|
|
744
|
+
|
|
745
|
+
`params`:
|
|
746
|
+
|
|
747
|
+
- `file`: The file object that has some progress in its uploading.
|
|
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
|
+
`
|
|
751
|
+
|
|
752
|
+
example
|
|
753
|
+
|
|
754
|
+
```js
|
|
755
|
+
scaleflexWidget.on("upload-progress", (file, progress) => {
|
|
756
|
+
console.log("The following file object progressed", file);
|
|
757
|
+
console.log("The progress object is as following", progress);
|
|
758
|
+
});
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
**upload-success** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
762
|
+
|
|
763
|
+
Emitted when a file is successfully uploaded.
|
|
764
|
+
|
|
765
|
+
`params`:
|
|
766
|
+
|
|
767
|
+
- `file`: The file object that has uploaded.
|
|
768
|
+
- `response`: The upload request response received.
|
|
769
|
+
- `options`: object that contains the uploadId
|
|
770
|
+
|
|
771
|
+
example
|
|
772
|
+
|
|
773
|
+
```js
|
|
774
|
+
scaleflexWidget.on("upload-success", (file, response, { uploadId }) => {
|
|
775
|
+
console.log(
|
|
776
|
+
`The ${file.name} with the object ${file} is uploaded ${uploadId} and the whole response`,
|
|
777
|
+
response
|
|
778
|
+
);
|
|
779
|
+
});
|
|
780
|
+
```
|
|
781
|
+
|
|
782
|
+
**upload-error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
783
|
+
|
|
784
|
+
Emitted when a file faced some error/issue while uploading.
|
|
785
|
+
|
|
786
|
+
`params`:
|
|
787
|
+
|
|
788
|
+
- `file`: The file object which fired the error.
|
|
789
|
+
- `error`: object that contains error details, upload response and uploadId that was assigned to current file.
|
|
790
|
+
- `options`: object that contains the upload response and uploadId
|
|
791
|
+
|
|
792
|
+
example
|
|
793
|
+
|
|
794
|
+
```js
|
|
795
|
+
scaleflexWidget.on("upload-error", (file, error, { response, uploadId }) => {
|
|
796
|
+
console.log(
|
|
797
|
+
"File faced that error while uploading",
|
|
798
|
+
file,
|
|
799
|
+
error,
|
|
800
|
+
response,
|
|
801
|
+
uploadId
|
|
802
|
+
);
|
|
803
|
+
});
|
|
804
|
+
```
|
|
805
|
+
|
|
806
|
+
**upload-retry** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
807
|
+
|
|
808
|
+
Emitted on some file uploading is retried.
|
|
809
|
+
|
|
810
|
+
`params`:
|
|
811
|
+
|
|
812
|
+
- `fileId`: The id of the file which its upload process is retried.
|
|
813
|
+
|
|
814
|
+
example
|
|
815
|
+
|
|
816
|
+
```js
|
|
817
|
+
scaleflexWidget.on("upload-retry", (fileId) => {
|
|
818
|
+
console.log("The following file id is being re-uploaded:", fileId);
|
|
819
|
+
});
|
|
820
|
+
```
|
|
821
|
+
|
|
822
|
+
**progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
823
|
+
|
|
824
|
+
Emitted on having a progress of an upload process's total progress.
|
|
825
|
+
|
|
826
|
+
`params`:
|
|
827
|
+
|
|
828
|
+
- `totalProgress`: The total progress value of the current uploading process.
|
|
829
|
+
|
|
830
|
+
example
|
|
831
|
+
|
|
832
|
+
```js
|
|
833
|
+
scaleflexWidget.on("progress", (totalProgress) => {
|
|
834
|
+
console.log("The uploading total progress for now: ", totalProgress);
|
|
835
|
+
});
|
|
836
|
+
```
|
|
837
|
+
|
|
838
|
+
**cancel-uploads** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
839
|
+
|
|
840
|
+
Emitted when the whole upload process is canceled (all files uploading are canceled).
|
|
841
|
+
|
|
842
|
+
`params`: No params returned.
|
|
843
|
+
|
|
844
|
+
example
|
|
845
|
+
|
|
846
|
+
```js
|
|
847
|
+
scaleflexWidget.on("cancel-uploads", () => {
|
|
848
|
+
console.log("The upload is canceled");
|
|
849
|
+
});
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
**complete** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
853
|
+
|
|
854
|
+
Emitted when the whole upload process done and completed.
|
|
855
|
+
|
|
856
|
+
`params`:
|
|
857
|
+
|
|
858
|
+
- `completionObject`: An object contains the results of the completed upload process, ex. `{ failed: failedFiles, uploadId: ..., successful: uploadedFiles }`.
|
|
859
|
+
|
|
860
|
+
example
|
|
861
|
+
|
|
862
|
+
```js
|
|
863
|
+
scaleflexWidget.on("complete", ({ failed, uploadId, successful }) => {
|
|
864
|
+
console.log(
|
|
865
|
+
`The upload ${uploadId} is completed with following results success then failed files`,
|
|
866
|
+
successful,
|
|
867
|
+
failed
|
|
868
|
+
);
|
|
869
|
+
});
|
|
870
|
+
```
|
|
871
|
+
|
|
872
|
+
**items-deleted** ![asset-manager-supported]
|
|
873
|
+
|
|
874
|
+
Emitted when files/folders are deleted.
|
|
875
|
+
|
|
876
|
+
`params`:
|
|
877
|
+
|
|
878
|
+
- `detailsObject`: An object contains details of removed items, ex. `{ removedFolders: [...], removedFiles: [...] }`.
|
|
879
|
+
|
|
880
|
+
example
|
|
881
|
+
|
|
882
|
+
```js
|
|
883
|
+
scaleflexWidget.on("items-deleted", ({ removedFolders, removedFiles }) => {
|
|
884
|
+
console.log("Items deleted:");
|
|
885
|
+
console.log("Removed folders:", removedFolders);
|
|
886
|
+
console.log("Removed files:", removedFiles);
|
|
887
|
+
});
|
|
888
|
+
```
|
|
889
|
+
|
|
890
|
+
**error** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
891
|
+
|
|
892
|
+
Emitted when the whole upload process faced an error.
|
|
893
|
+
|
|
894
|
+
`params`:
|
|
895
|
+
|
|
896
|
+
- `filesIds`: files ids that have an error.
|
|
897
|
+
- `error`: The error shown of the uploading process.
|
|
898
|
+
- `uploadId`: The id of the errored uploading process.
|
|
899
|
+
|
|
900
|
+
example
|
|
901
|
+
|
|
902
|
+
```js
|
|
903
|
+
scaleflexWidget.on("error", (filesIds, error, { uploadId }) => {
|
|
904
|
+
console.log(
|
|
905
|
+
`The upload with id ${uploadId} faced this error while uploading`,
|
|
906
|
+
error
|
|
907
|
+
);
|
|
908
|
+
});
|
|
909
|
+
```
|
|
910
|
+
|
|
911
|
+
**reset-progress** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
912
|
+
|
|
913
|
+
Emitted when the upload's progress is reset to 0.
|
|
914
|
+
|
|
915
|
+
`params`: No params returned.
|
|
916
|
+
|
|
917
|
+
example
|
|
918
|
+
|
|
919
|
+
```js
|
|
920
|
+
scaleflexWidget.on("reset-progress", () => {
|
|
921
|
+
console.log("The progress is reset");
|
|
922
|
+
});
|
|
923
|
+
```
|
|
924
|
+
|
|
925
|
+
**info-visible** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
926
|
+
|
|
927
|
+
Emitted on showing an `info` message to the user.
|
|
928
|
+
|
|
929
|
+
`params`: No params returned.
|
|
930
|
+
|
|
931
|
+
example
|
|
932
|
+
|
|
933
|
+
```js
|
|
934
|
+
scaleflexWidget.on("info-visible", () => {
|
|
935
|
+
console.log("inFo message shown.");
|
|
936
|
+
});
|
|
937
|
+
```
|
|
938
|
+
|
|
939
|
+
**info-hidden** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
940
|
+
|
|
941
|
+
Emitted on hiding an `info` message that were shown to the user.
|
|
942
|
+
|
|
943
|
+
`params`: No params returned.
|
|
944
|
+
|
|
945
|
+
example
|
|
946
|
+
|
|
947
|
+
```js
|
|
948
|
+
scaleflexWidget.on("info-hidden", () => {
|
|
949
|
+
console.log("The progress is hidden.");
|
|
950
|
+
});
|
|
951
|
+
```
|
|
952
|
+
|
|
953
|
+
**explorer:modal-open** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
954
|
+
|
|
955
|
+
Emitted on opening the widget in a modal through the [**Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer) plugin.
|
|
956
|
+
|
|
957
|
+
`params`: No params returned.
|
|
958
|
+
|
|
959
|
+
example
|
|
960
|
+
|
|
961
|
+
```js
|
|
962
|
+
scaleflexWidget.on("explorer:modal-open", () => {
|
|
963
|
+
console.log("The widget's explorer modal is opened .");
|
|
964
|
+
});
|
|
965
|
+
```
|
|
966
|
+
|
|
967
|
+
**explorer:modal-close** ![uploader-supported] ![asset-picker-supported] ![asset-manager-supported]
|
|
968
|
+
|
|
969
|
+
Emitted on closing the widget's main modal.
|
|
970
|
+
|
|
971
|
+
`params`: No params returned.
|
|
972
|
+
|
|
973
|
+
example
|
|
974
|
+
|
|
975
|
+
```js
|
|
976
|
+
scaleflexWidget.on("explorer:modal-close", () => {
|
|
977
|
+
console.log("The widget's modal is closed.");
|
|
978
|
+
});
|
|
979
|
+
```
|
|
980
|
+
|
|
981
|
+
**export** ![asset-picker-supported] ![asset-manager-supported]
|
|
982
|
+
|
|
983
|
+
emitted when the user downloads a file.
|
|
984
|
+
|
|
985
|
+
`params`:
|
|
986
|
+
|
|
987
|
+
- `files`: An array of files checked/selected for exporting.
|
|
988
|
+
- `popupExportSucessMsgFn`: A function if called will show exported successfully pop-up to the user.
|
|
989
|
+
- `downloadFilesPackagedFn`: A function if called will download files (the files passed in the first argument if nothing passed then the files exported will be used) as ZIP and show download progress in widget (item's Uuid is used & must exists on backend's side -- NOT FULLY WORKING --).
|
|
990
|
+
- `downloadFileFn`: A function if called will download one file (the file passed as first argument if nothing passed then the first file in exported files will be used) directly without packaging/zipping it and show download progress in widget (`file.url.download` link is used in download and fallbacks to `file.url.permalink`).
|
|
991
|
+
|
|
992
|
+
example
|
|
993
|
+
|
|
994
|
+
```js
|
|
995
|
+
scaleflexWidget.on(
|
|
996
|
+
"export",
|
|
997
|
+
(files, popupExportSucessMsgFn, downloadFilesPackagedFn, downloadFileFn) => {
|
|
998
|
+
console.log("The following files are chosen to be exported", files);
|
|
999
|
+
popupExportSucessMsgFn(); // shows exported successfully message as pop-up.
|
|
1000
|
+
downloadFilesPackagedFn(files.slice(1).map(({ file }) => file)); // no need to pass file.slice(1) if u would download all exported files.
|
|
1001
|
+
const { file } = file[0];
|
|
1002
|
+
downloadFileFn({ ...file, url: { ...file.url, download: files[0].link } }); // no need to pass file[0] if u would download the first file of exported files.
|
|
1003
|
+
}
|
|
1004
|
+
);
|
|
1005
|
+
```
|
|
1006
|
+
|
|
1007
|
+
**url-modified** ![asset-manager-supported]
|
|
1008
|
+
|
|
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.
|
|
1010
|
+
|
|
1011
|
+
`params`:
|
|
1012
|
+
|
|
1013
|
+
- `modifiedUrl`: The modified url for the image.
|
|
1014
|
+
- `designState`: The image editor's design state object.
|
|
1015
|
+
- `info`: the function that gives you possibility to show a `@scaleflex/widget-informer` message.
|
|
1016
|
+
|
|
1017
|
+
example
|
|
1018
|
+
|
|
1019
|
+
```js
|
|
1020
|
+
scaleflexWidget.on('modified-url', (modifiedUrl, designState, info) => {
|
|
1021
|
+
console.log('The new url is', modifiedUrl)
|
|
1022
|
+
console.log('Image editor design state:', designState)
|
|
1023
|
+
info('Url has changed', 'success', 3000)
|
|
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, {...})
|
|
1047
|
+
```
|
|
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
|
+
|
|
1172
|
+
<!-- Variables -->
|
|
1173
|
+
|
|
1174
|
+
[npm-url]: https://www.npmjs.com/package/@scaleflex/widget-core
|
|
1175
|
+
[license-url]: https://opensource.org/licenses/MIT
|
|
1176
|
+
[sfx-url]: https://www.scaleflex.com/
|
|
1177
|
+
[version-url-latest]: https://www.npmjs.com/package/@scaleflex/widget-core
|
|
1178
|
+
[version-url-stable]: https://www.npmjs.com/package/@scaleflex/widget-core/v/stable
|
|
1179
|
+
[version-url]: https://www.npmjs.com/package/@scaleflex/widget-core
|
|
1180
|
+
[codeSandbox-url]: https://codesandbox.io/p/sandbox/r9scjl
|
|
1181
|
+
[npm-image]: https://img.shields.io/npm/v/@telus/remark-config.svg?style=for-the-badge&logo=npm
|
|
1182
|
+
[license-image]: https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge
|
|
1183
|
+
[made-by-image]: https://img.shields.io/badge/%3C%2F%3E%20with%20%E2%99%A5%20by-the%20Scaleflex%20team-6986fa.svg?style=for-the-badge
|
|
1184
|
+
[plugins-image]: https://img.shields.io/static/v1?label=Scaleflex&message=Plugins&color=yellow&style=for-the-badge
|
|
1185
|
+
[filerobot-image]: https://img.shields.io/static/v1?label=Scaleflex&message=website&color=orange&style=for-the-badge
|
|
1186
|
+
[filerobot-version-latest]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=latest&style=for-the-badge&logo=npm
|
|
1187
|
+
[filerobot-version-stable]: https://img.shields.io/npm/v/@scaleflex/widget-core/stable?label=stable&style=for-the-badge&logo=npm
|
|
1188
|
+
[filerobot-version]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=Version&style=for-the-badge&logo=npm
|
|
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] -->
|
|
1198
|
+
|
|
1199
|
+
## License
|
|
1200
|
+
|
|
1201
|
+
The Scaleflex Media Asset Widget (SMAW) is provided under the [MIT License](https://opensource.org/licenses/MIT)
|