From 3f053af969ef6a688d526d158b9df7e6aa076838 Mon Sep 17 00:00:00 2001
From: Artur Arseniev <artur.catch@hotmail.it>
Date: Thu, 2 May 2019 01:28:33 +0200
Subject: [PATCH] Update docs

---
 docs/.vuepress/theme/CarbonAds.vue | 25 ++++----
 docs/api/canvas.md                 |  6 ++
 docs/api/commands.md               | 81 ++++++++++++++++---------
 docs/api/component.md              | 96 ++++++++++++++++++++++++++++++
 docs/api/editor.md                 |  6 +-
 docs/api/modal_dialog.md           | 54 +++++++++++++----
 6 files changed, 214 insertions(+), 54 deletions(-)

diff --git a/docs/.vuepress/theme/CarbonAds.vue b/docs/.vuepress/theme/CarbonAds.vue
index 4076011fd..1c86aa26a 100644
--- a/docs/.vuepress/theme/CarbonAds.vue
+++ b/docs/.vuepress/theme/CarbonAds.vue
@@ -1,22 +1,21 @@
 <script>
-window.BSANativeCallback = (a) => {
-  const total = a.ads.length;
-
-  if (!total) {
-    const src = document.createElement('script');
-    src.src = `//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=grapesjscom`;
-    src.setAttribute('id', '_carbonads_js');
-    const adCont = document.getElementById('native-carbon');
-    adCont && adCont.appendChild(src);
-  }
-}
-
 module.exports = {
   render (h) {
     return h('div', { class: 'carbon-ads', attrs: { id: 'native-carbon' }})
   },
   mounted () {
-    this.load()
+    window.BSANativeCallback = (a) => {
+      const total = a.ads.length;
+
+      if (!total) {
+        const src = document.createElement('script');
+        src.src = `//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=grapesjscom`;
+        src.setAttribute('id', '_carbonads_js');
+        const adCont = document.getElementById('native-carbon');
+        adCont && adCont.appendChild(src);
+      }
+    };
+    this.load();
   },
   watch: {
     '$route' (to, from) {
diff --git a/docs/api/canvas.md b/docs/api/canvas.md
index 45d23d25c..1b4886144 100644
--- a/docs/api/canvas.md
+++ b/docs/api/canvas.md
@@ -89,6 +89,12 @@ canvas.setCustomBadgeLabel(function(component){
 });
 ```
 
+## getRect
+
+Get canvas rectangular data
+
+Returns **[Object][14]** 
+
 ## hasFocus
 
 Check if the canvas is focused
diff --git a/docs/api/commands.md b/docs/api/commands.md
index c1b75cbb1..839d28548 100644
--- a/docs/api/commands.md
+++ b/docs/api/commands.md
@@ -21,11 +21,12 @@ const commands = editor.Commands;
 -   [add][2]
 -   [get][3]
 -   [getAll][4]
--   [has][5]
--   [run][6]
--   [stop][7]
--   [isActive][8]
--   [getActive][9]
+-   [extend][5]
+-   [has][6]
+-   [run][7]
+-   [stop][8]
+-   [isActive][9]
+-   [getActive][10]
 
 ## add
 
@@ -33,8 +34,8 @@ Add new command to the collection
 
 ### Parameters
 
--   `id` **[string][10]** Command's ID
--   `command` **([Object][11] \| [Function][12])** Object representing your command,
+-   `id` **[string][11]** Command's ID
+-   `command` **([Object][12] \| [Function][13])** Object representing your command,
      By passing just a function it's intended as a stateless command
      (just like passing an object with only `run` method).
 
@@ -60,7 +61,7 @@ Get command by ID
 
 ### Parameters
 
--   `id` **[string][10]** Command's ID
+-   `id` **[string][11]** Command's ID
 
 ### Examples
 
@@ -69,7 +70,29 @@ var myCommand = commands.get('myCommand');
 myCommand.run();
 ```
 
-Returns **[Object][11]** Object representing the command
+Returns **[Object][12]** Object representing the command
+
+## extend
+
+Extend the command. The command to extend should be defined as an object
+
+### Parameters
+
+-   `id` **[string][11]** Command's ID
+-   `cmd`   (optional, default `{}`)
+-   `Object` **[Object][12]** with the new command functions
+
+### Examples
+
+```javascript
+commands.extend('old-command', {
+ someInnerFunction() {
+ // ...
+ }
+});
+```
+
+Returns **this** 
 
 ## has
 
@@ -77,15 +100,15 @@ Check if command exists
 
 ### Parameters
 
--   `id` **[string][10]** Command's ID
+-   `id` **[string][11]** Command's ID
 
-Returns **[Boolean][13]** 
+Returns **[Boolean][14]** 
 
 ## getAll
 
 Get an object containing all the commands
 
-Returns **[Object][11]** 
+Returns **[Object][12]** 
 
 ## run
 
@@ -93,8 +116,8 @@ Execute the command
 
 ### Parameters
 
--   `id` **[String][10]** Command ID
--   `options` **[Object][11]** Options (optional, default `{}`)
+-   `id` **[String][11]** Command ID
+-   `options` **[Object][12]** Options (optional, default `{}`)
 
 ### Examples
 
@@ -110,8 +133,8 @@ Stop the command
 
 ### Parameters
 
--   `id` **[String][10]** Command ID
--   `options` **[Object][11]** Options (optional, default `{}`)
+-   `id` **[String][11]** Command ID
+-   `options` **[Object][12]** Options (optional, default `{}`)
 
 ### Examples
 
@@ -129,7 +152,7 @@ method it can't be registered as active
 
 ### Parameters
 
--   `id` **[String][10]** Command id
+-   `id` **[String][11]** Command id
 
 ### Examples
 
@@ -143,7 +166,7 @@ commands.isActive(cId);
 // -> false
 ```
 
-Returns **[Boolean][13]** 
+Returns **[Boolean][14]** 
 
 ## getActive
 
@@ -156,7 +179,7 @@ console.log(commands.getActive());
 // -> { someCommand: itsLastReturn, anotherOne: ... };
 ```
 
-Returns **[Object][11]** 
+Returns **[Object][12]** 
 
 [1]: https://github.com/artf/grapesjs/blob/master/src/commands/config/config.js
 
@@ -166,20 +189,22 @@ Returns **[Object][11]**
 
 [4]: #getall
 
-[5]: #has
+[5]: #extend
+
+[6]: #has
 
-[6]: #run
+[7]: #run
 
-[7]: #stop
+[8]: #stop
 
-[8]: #isactive
+[9]: #isactive
 
-[9]: #getactive
+[10]: #getactive
 
-[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
diff --git a/docs/api/component.md b/docs/api/component.md
index ffe6e946b..61774a1ad 100644
--- a/docs/api/component.md
+++ b/docs/api/component.md
@@ -116,6 +116,25 @@ component.find('div > .class');
 
 Returns **[Array][4]** Array of components
 
+## findType
+
+Find all inner components by component id.
+The advantage of this method over `find` is that you can use it
+also before rendering the component
+
+### Parameters
+
+-   `id` **[String][1]** Component id
+
+### Examples
+
+```javascript
+const allImages = component.findType('image');
+console.log(allImages[0]) // prints the first found component
+```
+
+Returns **[Array][4]&lt;[Component][9]>** 
+
 ## closest
 
 Find the closest parent component by query string.
@@ -351,6 +370,83 @@ traitTitle && traitTitle.set('label', 'New label');
 
 Returns **Trait** Trait model
 
+## updateTrait
+
+Update a trait
+
+### Parameters
+
+-   `id` **[String][1]** The `id` or `name` of the trait
+-   `props` **[Object][2]** Object with the props to update
+
+### Examples
+
+```javascript
+component.updateTrait('title', {
+ type: 'select',
+ options: [ 'Option 1', 'Option 2' ],
+});
+```
+
+Returns **this** 
+
+## getTraitIndex
+
+Get the trait position index by id/name. Useful in case you want to
+replace some trait, at runtime, with something else.
+
+### Parameters
+
+-   `id` **[String][1]** The `id` or `name` of the trait
+
+### Examples
+
+```javascript
+const traitTitle = component.getTraitIndex('title');
+console.log(traitTitle); // 1
+```
+
+Returns **[Number][10]** Index position of the current trait
+
+## removeTrait
+
+Remove trait/s by id/s.
+
+### Parameters
+
+-   `id` **([String][1] \| [Array][4]&lt;[String][1]>)** The `id`/`name` of the trait (or an array)
+
+### Examples
+
+```javascript
+component.removeTrait('title');
+component.removeTrait(['title', 'id']);
+```
+
+Returns **[Array][4]** Array of removed traits
+
+## addTrait
+
+Add trait/s by id/s.
+
+### Parameters
+
+-   `trait` **([String][1] \| [Object][2] \| [Array][4]&lt;([String][1] \| [Object][2])>)** Trait to add (or an array of traits)
+-   `opts` **Options** Options for the add (optional, default `{}`)
+
+### Examples
+
+```javascript
+component.addTrat('title', { at: 1 }); // Add title trait (`at` option is the position index)
+component.addTrat({
+ type: 'checkbox',
+ name: 'disabled',
+});
+component.addTrat(['title', {...}, ...]);
+```
+
+Returns **[Array][4]** Array of added traits
+
 ## getName
 
 Get the name of the component
diff --git a/docs/api/editor.md b/docs/api/editor.md
index bc85ccefe..1bb912922 100644
--- a/docs/api/editor.md
+++ b/docs/api/editor.md
@@ -24,7 +24,7 @@ editor.on('EVENT-NAME', (some, argument) => {
 ### Components
 
 -   `component:create` - Component is created (only the model, is not yet mounted in the canvas), called after the init() method
--   `component:mount` - Component is monted to an element and rendered in canvas
+-   `component:mount` - Component is mounted to an element and rendered in canvas
 -   `component:add` - Triggered when a new component is added to the editor, the model is passed as an argument to the callback
 -   `component:remove` - Triggered when a component is removed, the model is passed as an argument to the callback
 -   `component:clone` - Triggered when a component is cloned, the new model is passed as an argument to the callback
@@ -112,6 +112,8 @@ editor.on('EVENT-NAME', (some, argument) => {
 -   `run:{commandName}:before` - Triggered before the command is called
 -   `stop:{commandName}:before` - Triggered before the command is called to stop
 -   `abort:{commandName}` - Triggered when the command execution is aborted (`editor.on(`run:preview:before`, opts => opts.abort = 1);`)
+-   `run` - Triggered on run of any command. The id and the result are passed as arguments to the callback
+-   `stop` - Triggered on stop of any command. The id and the result are passed as arguments to the callback
 
 ### General
 
@@ -274,6 +276,8 @@ Select a component
 ### Parameters
 
 -   `el` **(Component | [HTMLElement][6])** Component to select
+-   `opts` **[Object][3]?** Options
+    -   `opts.scroll` **[Boolean][5]?** Scroll canvas to the selected element
 
 ### Examples
 
diff --git a/docs/api/modal_dialog.md b/docs/api/modal_dialog.md
index f88c35fee..e3ff89dbb 100644
--- a/docs/api/modal_dialog.md
+++ b/docs/api/modal_dialog.md
@@ -25,6 +25,8 @@ const modal = editor.Modal;
 -   [getTitle][6]
 -   [setContent][7]
 -   [getContent][8]
+-   [onceClose][9]
+-   [onceOpen][10]
 
 ## open
 
@@ -32,9 +34,9 @@ Open the modal window
 
 ### Parameters
 
--   `opts` **[Object][9]** Options (optional, default `{}`)
-    -   `opts.title` **([String][10] \| [HTMLElement][11])?** Title to set for the modal
-    -   `opts.content` **([String][10] \| [HTMLElement][11])?** Content to set for the modal
+-   `opts` **[Object][11]** Options (optional, default `{}`)
+    -   `opts.title` **([String][12] \| [HTMLElement][13])?** Title to set for the modal
+    -   `opts.content` **([String][12] \| [HTMLElement][13])?** Content to set for the modal
 
 Returns **this** 
 
@@ -44,11 +46,33 @@ Close the modal window
 
 Returns **this** 
 
+## onceClose
+
+Execute callback when the modal will be closed.
+The callback will be called one only time
+
+### Parameters
+
+-   `clb` **[Function][14]** 
+
+Returns **this** 
+
+## onceOpen
+
+Execute callback when the modal will be opened.
+The callback will be called one only time
+
+### Parameters
+
+-   `clb` **[Function][14]** 
+
+Returns **this** 
+
 ## isOpen
 
 Checks if the modal window is open
 
-Returns **[Boolean][12]** 
+Returns **[Boolean][15]** 
 
 ## setTitle
 
@@ -56,7 +80,7 @@ Set the title to the modal window
 
 ### Parameters
 
--   `title` **[string][10]** Title
+-   `title` **[string][12]** Title
 
 ### Examples
 
@@ -70,7 +94,7 @@ Returns **this**
 
 Returns the title of the modal window
 
-Returns **[string][10]** 
+Returns **[string][12]** 
 
 ## setContent
 
@@ -78,7 +102,7 @@ Set the content of the modal window
 
 ### Parameters
 
--   `content` **([string][10] \| [HTMLElement][11])** Content
+-   `content` **([string][12] \| [HTMLElement][13])** Content
 
 ### Examples
 
@@ -92,7 +116,7 @@ Returns **this**
 
 Get the content of the modal window
 
-Returns **[string][10]** 
+Returns **[string][12]** 
 
 [1]: https://github.com/artf/grapesjs/blob/master/src/modal_dialog/config/config.js
 
@@ -110,10 +134,16 @@ Returns **[string][10]**
 
 [8]: #getcontent
 
-[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[9]: #onceclose
+
+[10]: #onceopen
+
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[13]: https://developer.mozilla.org/docs/Web/HTML/Element
 
-[11]: https://developer.mozilla.org/docs/Web/HTML/Element
+[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean