diff --git a/docs/modules/Assets.md b/docs/modules/Assets.md
index 928863f39..dac5164ca 100644
--- a/docs/modules/Assets.md
+++ b/docs/modules/Assets.md
@@ -25,7 +25,6 @@ const editor = grapesjs.init({
});
```
-
You can update most of them later by using `getConfig` inside of the module
```js
@@ -78,6 +77,7 @@ The built-in Asset Manager modal is implemented and is showing up when requested
+
-## Using programmatically
+## Uploading assets
-## Customization
+The default Asset Manager includes also an easy to use, drag-and-drop uploader with a few UI helpers. The default uploader is already visible when you open the Asset Manager.
+
+
+
+
+
+You can click on the uploader to select your files or just drag them directly from your computer to trigger the uploader. Obviously, before it will work you have to setup your server to receive your assets and specify the upload endpoint in your configuration
+
+
+```js
+const editor = grapesjs.init({
+ ...
+ assetManager: {
+ ...
+ // Upload endpoint, set `false` to disable upload, default `false`
+ upload: 'https://endpoint/upload/assets',
+
+ // The name used in POST to pass uploaded files, default: `'files'`
+ uploadName: 'files',
+ ...
+ },
+ ...
+});
+```
+
+
+### Listeners
+
+If you want to execute an action before/after the uploading process (eg. loading animation) or even on response, you can make use of these listeners
+
+```js
+// The upload is started
+editor.on('asset:upload:start', () => {
+ startAnimation();
+});
+
+// The upload is ended (completed or not)
+editor.on('asset:upload:end', () => {
+ endAnimation();
+});
+
+// Error handling
+editor.on('asset:upload:error', (err) => {
+ notifyError(err);
+});
+
+// Do something on response
+editor.on('asset:upload:response', (response) => {
+ ...
+});
+```
+
+
+### Response
-If you want to customize the Asset Manager after the initialization you have to use its [APIs](API-Asset-Manager)
+When the uploading is over, by default (via config parameter `autoAdd: 1`), the editor expects to receive a JSON of uploaded assets in a `data` key as a response and tries to add them to the main collection. The JSON might look like this:
+
+```js
+{
+ data: [
+ 'https://.../image.png',
+ // ...
+ {
+ src: 'https://.../image2.png',
+ type: 'image',
+ height: 100,
+ width: 200,
+ },
+ // ...
+ ]
+}
+```
+
+
+
+
+
+
+
+
+## Programmatic usage
+
+If you need to manage your assets programmatically you have to use its [APIs][API-Asset-Manager]
```js
// Get the Asset Manager module first
@@ -163,19 +262,60 @@ You can also mix arrays of assets
```js
am.render([...assets1, ...assets2, ...assets3]);
```
-
+
+
+In case you want to update or remove an asset, you can make use of this methods
+
+```js
+// Get the asset via its `src`
+const asset = am.get('http://.../img.jpg');
+
+// Update asset property
+asset.set({ src: 'http://.../new-img.jpg' });
+
+// Remove asset
+am.remove(asset); // or via src, am.remove('http://.../new-img.jpg');
+```
For more APIs methods check out the [API Reference](API-Asset-Manager)
+### Custom select logic
+
+::: warning
+This section is referring to GrapesJS v0.17.26 or higher
+:::
+
+You can open the Asset Manager with your own select logic.
+
+```js
+am.open({
+ types: ['image'], // This is the default option
+ // Without select, nothing will happen on asset selection
+ select(asset, complete) {
+ const selected = editor.getSelected();
+
+ if (selected && selected.is('image')) {
+ selected.addAttributes({ src: asset.getSrc() });
+ // The default AssetManager UI will trigger `select(asset, false)`
+ // on asset click and `select(asset, true)` on double-click
+ complete && am.close();
+ }
+ }
+});
+```
+
+## Customization
+
### Define new Asset type
Generally speaking, images aren't the only asset you'll use, it could be a `video`, `svg-icon`, or any other kind of `document`. Each type of asset is applied in our templates/pages differently. If you need to change the image of the Component all you need is another `url` in `src` attribute. However In case of a `svg-icon`, its not the same, you might want to replace the element with a new `