From 8641c2bba694311e5c20b8d4b9645e777287389a Mon Sep 17 00:00:00 2001
From: Artur Arseniev <artur.catch@hotmail.it>
Date: Sat, 14 Aug 2021 00:47:03 +0200
Subject: [PATCH] Add Block API Reference

---
 docs/.vuepress/config.js         |  1 +
 docs/api.js                      |  1 +
 docs/api/block.md                | 26 +++++++++++++++
 docs/api/canvas.md               | 56 ++++++++++++++++++--------------
 src/block_manager/model/Block.js | 46 +++++++++++++++-----------
 src/common/Collection.js         |  1 +
 src/common/Model.js              |  1 +
 src/common/index.js              |  2 ++
 8 files changed, 90 insertions(+), 44 deletions(-)
 create mode 100644 docs/api/block.md
 create mode 100644 src/common/Collection.js
 create mode 100644 src/common/Model.js
 create mode 100644 src/common/index.js

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 860bc5c16..1a235b67f 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -62,6 +62,7 @@ module.exports = {
         ['/api/canvas', 'Canvas'],
         ['/api/assets', 'Asset Manager'],
         ['/api/block_manager', 'Block Manager'],
+        ['/api/block', `${subDivider}Block`],
         ['/api/commands', 'Commands'],
         ['/api/components', 'DOM Components'],
         ['/api/component', `${subDivider}Component`],
diff --git a/docs/api.js b/docs/api.js
index 6fa9290bb..2867f078c 100644
--- a/docs/api.js
+++ b/docs/api.js
@@ -14,6 +14,7 @@ async function generateDocs () {
     ['editor/index.js', 'editor.md'],
     ['asset_manager/index.js', 'assets.md'],
     ['block_manager/index.js', 'block_manager.md'],
+    ['block_manager/model/Block.js', 'block.md'],
     ['commands/index.js', 'commands.md'],
     ['dom_components/index.js', 'components.md'],
     ['dom_components/model/Component.js', 'component.md'],
diff --git a/docs/api/block.md b/docs/api/block.md
new file mode 100644
index 000000000..377b4acae
--- /dev/null
+++ b/docs/api/block.md
@@ -0,0 +1,26 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Block
+
+
+
+### Properties
+
+*   `label` **[String][1]?** Block label, eg. `My block`
+*   `activate` **[Boolean][2]?** If true, triggers an the 'active' event on dropped component
+*   `select` **[Boolean][2]?** If true, the dropped component will be selected
+*   `resetId` **[Boolean][2]?** If true, all IDs of dropped components and their styles will be changed
+*   `disable` **[Boolean][2]?** Disable the drag of the block
+*   `media` **[String][1]?** HTML string for the media/icon of the block, eg. `<svg ...`, `<img ...`, etc.
+    (**WARNING:** In order to support HTML strings, this property is not escaped)
+*   `content` **([String][1] | [Object][3])** The content of the block. Might be an HTML string or a [Component Defintion][4]
+*   `category` **[String][1]?** Block category
+*   `attributes` **[Object][3]?** Block attributes to apply in the view element
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[4]: /modules/Components.html#component-definition
diff --git a/docs/api/canvas.md b/docs/api/canvas.md
index 5b3ae7214..d3356d320 100644
--- a/docs/api/canvas.md
+++ b/docs/api/canvas.md
@@ -29,6 +29,8 @@ const canvas = editor.Canvas;
 *   [scrollTo][10]
 *   [setZoom][11]
 *   [getZoom][12]
+*   [getCoords][13]
+*   [setCoords][14]
 
 [Component]: component.html
 
@@ -42,25 +44,25 @@ Get the configuration object
 console.log(canvas.getConfig())
 ```
 
-Returns **[Object][13]** Configuration object
+Returns **[Object][15]** Configuration object
 
 ## getElement
 
 Get the canvas element
 
-Returns **[HTMLElement][14]** 
+Returns **[HTMLElement][16]** 
 
 ## getFrameEl
 
 Get the main frame element of the canvas
 
-Returns **[HTMLIFrameElement][15]** 
+Returns **[HTMLIFrameElement][17]** 
 
 ## getWindow
 
 Get the main frame window instance
 
-Returns **[Window][16]** 
+Returns **[Window][18]** 
 
 ## getDocument
 
@@ -72,7 +74,7 @@ Returns **HTMLDocument**
 
 Get the main frame body element
 
-Returns **[HTMLBodyElement][17]** 
+Returns **[HTMLBodyElement][19]** 
 
 ## setCustomBadgeLabel
 
@@ -80,7 +82,7 @@ Set custom badge naming strategy
 
 ### Parameters
 
-*   `f` **[Function][18]** 
+*   `f` **[Function][20]** 
 
 ### Examples
 
@@ -94,13 +96,13 @@ canvas.setCustomBadgeLabel(function(component){
 
 Get canvas rectangular data
 
-Returns **[Object][13]** 
+Returns **[Object][15]** 
 
 ## hasFocus
 
 Check if the canvas is focused
 
-Returns **[Boolean][19]** 
+Returns **[Boolean][21]** 
 
 ## scrollTo
 
@@ -111,10 +113,10 @@ passed to it. For instance, you can scroll smoothly by using
 
 ### Parameters
 
-*   `el` **([HTMLElement][14] | [Component])** 
-*   `opts` **[Object][13]** Options, same as options for `scrollIntoView` (optional, default `{}`)
+*   `el` **([HTMLElement][16] | [Component])** 
+*   `opts` **[Object][15]** Options, same as options for `scrollIntoView` (optional, default `{}`)
 
-    *   `opts.force` **[Boolean][19]** Force the scroll, even if the element is already visible (optional, default `false`)
+    *   `opts.force` **[Boolean][21]** Force the scroll, even if the element is already visible (optional, default `false`)
 
 ### Examples
 
@@ -132,7 +134,7 @@ Set canvas zoom value
 
 ### Parameters
 
-*   `value` **[Number][20]** The zoom value, from 0 to 100
+*   `value` **[Number][22]** The zoom value, from 0 to 100
 
 ### Examples
 
@@ -153,7 +155,7 @@ canvas.setZoom(50); // set zoom to 50%
 const zoom = canvas.getZoom(); // 50
 ```
 
-Returns **[Number][20]** 
+Returns **[Number][22]** 
 
 ## setCoords
 
@@ -161,8 +163,8 @@ Set canvas position coordinates
 
 ### Parameters
 
-*   `x` **[Number][20]** Horizontal position
-*   `y` **[Number][20]** Vertical position
+*   `x` **[Number][22]** Horizontal position
+*   `y` **[Number][22]** Vertical position
 
 ### Examples
 
@@ -184,7 +186,7 @@ const coords = canvas.getCoords();
 // { x: 100, y: 100 }
 ```
 
-Returns **[Object][13]** Object containing coordinates
+Returns **[Object][15]** Object containing coordinates
 
 ## addFrame
 
@@ -192,7 +194,7 @@ Add new frame to the canvas
 
 ### Parameters
 
-*   `props` **[Object][13]** Frame properties (optional, default `{}`)
+*   `props` **[Object][15]** Frame properties (optional, default `{}`)
 *   `opts`   (optional, default `{}`)
 
 ### Examples
@@ -242,18 +244,22 @@ Returns **Frame**
 
 [12]: #getzoom
 
-[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[13]: #getcoords
 
-[14]: https://developer.mozilla.org/docs/Web/HTML/Element
+[14]: #setcoords
 
-[15]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement
+[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[16]: https://developer.mozilla.org/docs/Web/API/Window
+[16]: https://developer.mozilla.org/docs/Web/HTML/Element
 
-[17]: https://developer.mozilla.org/docs/Web/HTML/Element/body
+[17]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement
 
-[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[18]: https://developer.mozilla.org/docs/Web/API/Window
 
-[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[19]: https://developer.mozilla.org/docs/Web/HTML/Element/body
 
-[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
diff --git a/src/block_manager/model/Block.js b/src/block_manager/model/Block.js
index 00e3b5620..2dd97bf6e 100644
--- a/src/block_manager/model/Block.js
+++ b/src/block_manager/model/Block.js
@@ -1,21 +1,29 @@
-import Backbone from 'backbone';
+import { Model } from 'common';
 
-export default Backbone.Model.extend({
-  defaults: {
-    // If true, triggers an 'active' event on dropped component
-    activate: 0,
-    // If true, the dropped component will be selected
-    select: 0,
-    // If true, all IDs of dropped component and its style will be changed
-    resetId: 0,
-    // Block label
-    label: '',
-    // Disable the drag of the block
-    disable: 0,
-    // HTML string for the media of the block, eg. SVG icon, image, etc.
-    media: '',
-    content: '',
-    category: '',
-    attributes: {}
+/**
+ * @property {String} [label=''] Block label, eg. `My block`
+ * @property {Boolean} [activate=false] If true, triggers an the 'active' event on dropped component
+ * @property {Boolean} [select=false] If true, the dropped component will be selected
+ * @property {Boolean} [resetId=false] If true, all IDs of dropped components and their styles will be changed
+ * @property {Boolean} [disable=false] Disable the drag of the block
+ * @property {String} [media=''] HTML string for the media/icon of the block, eg. `<svg ...`, `<img ...`, etc.
+ *  (**WARNING:** In order to support HTML strings, this property is not escaped)
+ * @property {String|Object} content The content of the block. Might be an HTML string or a [Component Defintion](/modules/Components.html#component-definition)
+ * @property {String} [category=''] Block category
+ * @property {Object} [attributes={}] Block attributes to apply in the view element
+ */
+export default class Block extends Model {
+  defaults() {
+    return {
+      label: '',
+      activate: false,
+      select: false,
+      resetId: false,
+      disable: false,
+      media: '',
+      content: '',
+      category: '',
+      attributes: {}
+    };
   }
-});
+}
diff --git a/src/common/Collection.js b/src/common/Collection.js
new file mode 100644
index 000000000..c719ed4c9
--- /dev/null
+++ b/src/common/Collection.js
@@ -0,0 +1 @@
+export { Collection as default } from 'backbone';
diff --git a/src/common/Model.js b/src/common/Model.js
new file mode 100644
index 000000000..cac98d1f3
--- /dev/null
+++ b/src/common/Model.js
@@ -0,0 +1 @@
+export { Model as default } from 'backbone';
diff --git a/src/common/index.js b/src/common/index.js
new file mode 100644
index 000000000..346ca5cbe
--- /dev/null
+++ b/src/common/index.js
@@ -0,0 +1,2 @@
+export { default as Model } from './Model';
+export { default as Collection } from './Collection';