API shorthands (#627)

* Api shorthands

closes #612

* Remove docs about events

* Update embed submodule

* Update example

docs/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
+### 2.11.0
+
+- `New` — Add API methods shorthands
+
 ### 2.10.0
 
-- `New` Rename from CodeX Editor to Editor.js
+- `New` — Rename from CodeX Editor to Editor.js
 
 ### 2.9.5
 

docs/api.md

@@ -65,16 +65,6 @@ Methods that working with Toolbar
 
 `close()` - closes toolbar, toolbox and blockSettings if they are opened
 
-### EventsAPI
-
-Methods that allows to subscribe on Editor.js events
-
-`on(eventName: string, callback: Function)` - subscribe callback on event
-
-`off(eventName: string, callback: Function)` - unsubscribe callback from event
-
-`emit(eventName: string, data: object)` - fires all subscribed callbacks with passed data
-
 ### ListenerAPI
 
 Methods that allows to work with DOM listener. Useful when you forgot to remove listener. Module collects all listeners and destroys automatically
@@ -110,6 +100,8 @@ Each method returns `boolean` value: true if caret is set successfully or false
 
 `setToBlock(index: number, position?: 'end'|'start'|'default', offset?: number): boolean;` — set caret to the Block by passed `index`
 
+`focus(atEnd?: boolean): boolean;` — set caret to the Editor. If `atEnd` is true, set it at the end.
+
 ### NotifierAPI
 
 If you need to show any messages for success or failure events you can use notifications module.
@@ -153,3 +145,23 @@ It makes following steps:
 3. Delete all properties from instance object and set it\`s prototype to `null`
 
 After executing the `destroy` method, editor inctance becomes an empty object. This way you will free occupied JS Heap on your page.
+
+### Shorthands
+
+Editor`s API provides some shorthands for API methods. 
+
+| Alias    | Method          |
+| ------   | --------------- |
+| `clear`  | `blocks.clear`  |
+| `render` | `blocks.render` |
+| `focus`  | `caret.focus`   |
+| `save`   | `saver.save`    |
+
+> Example
+
+```javascript
+const editor = EditorJS();
+
+editor.focus();
+editor.save();
+```

docs/events.md

@@ -1,50 +0,0 @@
-# Editor.js Events Module
-
-Module allows Developers to subscribe on events or trigger own events
-
-## Methods
-
-### On
-
-```javascript
-Events.on(eventName, callback)
-``` 
-
-> Method subscribes callback on event. It will be called when Editor.js emits this event
-
-#### params
-
-| Param        | Type | Description|
-| -------------|------ |:-------------:|
-| eventName        | String | event name|
-| callback | Function | event callback|
-
-### Off
-
-```javascript
-Events.off(eventName, callback)
-``` 
-
-> Method unsubscribes callback on event
-
-#### params
-
-| Param        | Type | Description|
-| -------------|------ |:-------------:|
-| eventName        | String | event name|
-| callback | Function | event callback|
-
-### Emit
-
-```javascript
-Events.emit(eventName, data)
-``` 
-
-> Method emits data to all subscribed callbacks
-
-#### params
-
-| Param        | Type | Description|
-| -------------|------ |:-------------:|
-| eventName        | String | event name|
-| data | Object | any data|

example/example.html

@@ -21,7 +21,7 @@
       <div id="editorjs"></div>
 
       <div class="ce-example__button" id="saveButton">
-        editor.saver.save()
+        editor.save()
       </div>
     </div>
     <div class="ce-example__output">
@@ -263,7 +263,7 @@
      * Saving example
      */
     saveButton.addEventListener('click', function () {
-      editor.saver.save().then((savedData) => {
+      editor.save().then((savedData) => {
         cPreview.show(savedData, document.getElementById("output"));
       });
     });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@editorjs/editorjs",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Editor.js — Native JS, based on API and Open Source",
   "main": "dist/editor.js",
   "types": "./types/index.d.ts",

src/codex.ts

@@ -102,5 +102,31 @@ export default class EditorJS {
     Object.setPrototypeOf(this, editor.moduleInstances.API.methods);
 
     delete this.exportAPI;
+
+    const shorthands = {
+      blocks: {
+        clear: 'clear',
+        render: 'render',
+      },
+      caret: {
+        focus: 'focus',
+      },
+      events: {
+        on: 'on',
+        off: 'off',
+        emit: 'emit',
+      },
+      saver: {
+        save: 'save',
+      },
+    };
+
+    Object.entries(shorthands)
+      .forEach(([key, methods]) => {
+        Object.entries(methods)
+          .forEach(([name, alias]) => {
+            this[alias] = editor.moduleInstances.API.methods[key][name];
+          });
+      });
   }
 }

src/components/modules/api/caret.ts

@@ -17,6 +17,7 @@ export default class CaretAPI extends Module {
       setToPreviousBlock: this.setToPreviousBlock,
       setToNextBlock: this.setToNextBlock,
       setToBlock: this.setToBlock,
+      focus: this.focus,
     };
   }
 
@@ -112,4 +113,19 @@ export default class CaretAPI extends Module {
     this.Editor.Caret.setToBlock(this.Editor.BlockManager.blocks[index], position, offset);
     return true;
   }
+
+  /**
+   * Sets caret to the Editor
+   *
+   * @param {boolean} atEnd - if true, set Caret to the end of the Editor
+   *
+   * @return {boolean}
+   */
+  private focus = (atEnd: boolean = false) => {
+    if (atEnd) {
+      return this.setToLastBlock(this.Editor.Caret.positions.END);
+    }
+
+    return this.setToFirstBlock(this.Editor.Caret.positions.START);
+  }
 }

types/api/caret.d.ts

@@ -53,4 +53,13 @@ export interface Caret {
    * @return {boolean}
    */
   setToBlock(index: number, position?: 'end'|'start'|'default', offset?: number): boolean;
+
+  /**
+   * Sets caret to the Editor
+   *
+   * @param {boolean} atEnd - if true, set Caret to the end of the Editor
+   *
+   * @return {boolean}
+   */
+  focus(atEnd?: boolean): boolean;
 }