diff --git a/docs/api/canvas.md b/docs/api/canvas.md index 419834e67..af16875b5 100644 --- a/docs/api/canvas.md +++ b/docs/api/canvas.md @@ -66,54 +66,31 @@ editor.on('canvas:spot:remove', ({ spot }) => { }); ``` -* `canvas:viewport` Canvas viewport updated (eg. zoom or coordinates). +* `canvas:coords` Canvas coordinates updated. ```javascript -editor.on('canvas:viewport', () => { - const { Canvas } = editor; - console.log('Canvas, zoom:', Canvas.getZoom(), 'coords:', Canvas.getCoords()); +editor.on('canvas:coords', () => { + console.log('Canvas coordinates updated:', editor.Canvas.getCoords()); }); ``` -* `canvas:viewport:start` Canvas viewport update started (eg. zooming or panning) - -```javascript -editor.on('canvas:viewport:start', () => { - console.log('viewport update started') -}); -``` - -* `canvas:viewport:end` Canvas viewport update ended. This event is debounced on 300ms from the `canvas:viewport:start`. +* `canvas:zoom` Canvas zoom updated. ```javascript -editor.on('canvas:viewport:end', () => { - console.log('viewport updated ended') +editor.on('canvas:zoom', () => { + console.log('Canvas zoom updated:', editor.Canvas.getZoom()); }); ``` -* `canvas:zoom` Canvas zoom updated. +* `canvas:pointer` Canvas pointer updated. ```javascript -editor.on('canvas:zoom', () => { - console.log('New canvas zoom:', editor.Canvas.getZoom()); +editor.on('canvas:pointer', () => { + console.log('Canvas pointer updated:', editor.Canvas.getPointer()); }); ``` -## Methods - -* [getConfig][2] -* [getElement][3] -* [getFrameEl][4] -* [getWindow][5] -* [getDocument][6] -* [getBody][7] -* [setCustomBadgeLabel][8] -* [hasFocus][9] -* [scrollTo][10] -* [setZoom][11] -* [getZoom][12] -* [getCoords][13] -* [setCoords][14] +* ToScreenOption [Component]: component.html @@ -123,25 +100,25 @@ editor.on('canvas:zoom', () => { Get configuration object -Returns **[Object][15]** +Returns **[Object][2]** ## getElement Get the canvas element -Returns **[HTMLElement][16]** +Returns **[HTMLElement][3]** ## getFrameEl Get the main frame element of the canvas -Returns **[HTMLIFrameElement][17]** +Returns **[HTMLIFrameElement][4]** ## getWindow Get the main frame window instance -Returns **[Window][18]** +Returns **[Window][5]** ## getDocument @@ -153,7 +130,7 @@ Returns **HTMLDocument** Get the main frame body element -Returns **[HTMLBodyElement][19]** +Returns **[HTMLBodyElement][6]** ## setCustomBadgeLabel @@ -161,7 +138,7 @@ Set custom badge naming strategy ### Parameters -* `f` **[Function][20]** +* `f` **[Function][7]** ### Examples @@ -175,13 +152,13 @@ canvas.setCustomBadgeLabel(function(component){ Get canvas rectangular data -Returns **[Object][15]** +Returns **[Object][2]** ## hasFocus Check if the canvas is focused -Returns **[Boolean][21]** +Returns **[Boolean][8]** ## scrollTo @@ -192,10 +169,10 @@ passed to it. For instance, you can scroll smoothly by using ### Parameters -* `el` **([HTMLElement][16] | [Component])** -* `opts` **[Object][15]** Options, same as options for `scrollIntoView` (optional, default `{}`) +* `el` **([HTMLElement][3] | [Component])** +* `opts` **[Object][2]** Options, same as options for `scrollIntoView` (optional, default `{}`) - * `opts.force` **[Boolean][21]** Force the scroll, even if the element is already visible (optional, default `false`) + * `opts.force` **[Boolean][8]** Force the scroll, even if the element is already visible (optional, default `false`) ### Examples @@ -213,7 +190,7 @@ Set canvas zoom value ### Parameters -* `value` **[Number][22]** The zoom value, from 0 to 100 +* `value` **[Number][9]** The zoom value, from 0 to 100 ### Examples @@ -234,7 +211,7 @@ canvas.setZoom(50); // set zoom to 50% const zoom = canvas.getZoom(); // 50 ``` -Returns **[Number][22]** +Returns **[Number][9]** ## setCoords @@ -242,8 +219,8 @@ Set canvas position coordinates ### Parameters -* `x` **[Number][22]** Horizontal position -* `y` **[Number][22]** Vertical position +* `x` **[Number][9]** Horizontal position +* `y` **[Number][9]** Vertical position * `opts` **ToWorldOption** (optional, default `{}`) ### Examples @@ -266,7 +243,7 @@ const coords = canvas.getCoords(); // { x: 100, y: 100 } ``` -Returns **[Object][15]** Object containing coordinates +Returns **[Object][2]** Object containing coordinates ## addFrame @@ -274,7 +251,7 @@ Add new frame to the canvas ### Parameters -* `props` **[Object][15]** Frame properties (optional, default `{}`) +* `props` **[Object][2]** Frame properties (optional, default `{}`) * `opts` (optional, default `{}`) ### Examples @@ -304,50 +281,149 @@ Returns **[Frame]** Get the last created Component from a drag & drop to the canvas. -Returns **([Component] | [undefined][23])** +Returns **([Component] | [undefined][10])** -[1]: https://github.com/GrapesJS/grapesjs/blob/master/src/canvas/config/config.ts +## addSpot + +Add or update canvas spot. + +### Parameters + +* `props` **[Object][2]** Canvas spot properties. +* `opts` **AddOptions** (optional, default `{}`) + +### Examples + +```javascript +// Add new canvas spot +const spot = canvas.addSpot({ + type: 'select', // 'select' is one of the built-in spots + component: editor.getSelected(), +}); + +// Add custom canvas spot +const spot = canvas.addSpot({ + type: 'my-custom-spot', + component: editor.getSelected(), +}); +// Update the same spot by reusing its ID +canvas.addSpot({ + id: spot.id, + component: anotherComponent, +}); +``` + +Returns **[CanvasSpot]** + +## getSpots + +Get canvas spots. + +### Parameters + +* `spotProps` **[Object][2]?** Canvas spot properties for filtering the result. With no properties, all available spots will be returned. (optional, default `{}`) + +### Examples -[2]: #getconfig +```javascript +canvas.addSpot({ type: 'select', component: cmp1 }); +canvas.addSpot({ type: 'select', component: cmp2 }); +canvas.addSpot({ type: 'target', component: cmp3 }); + +// Get all spots +const allSpots = canvas.getSpots(); +allSpots.length; // 3 + +// Get all 'select' spots +const allSelectSpots = canvas.getSpots({ type: 'select' }); +allSelectSpots.length; // 2 +``` + +Returns **[Array][11]<[CanvasSpot]>** + +## removeSpots + +Remove canvas spots. + +### Parameters + +* `spotProps` **([Object][2] | [Array][11]<[CanvasSpot]>)?** Canvas spot properties for filtering spots to remove or an array of spots to remove. With no properties, all available spots will be removed. (optional, default `{}`) + +### Examples -[3]: #getelement +```javascript +canvas.addSpot({ type: 'select', component: cmp1 }); +canvas.addSpot({ type: 'select', component: cmp2 }); +canvas.addSpot({ type: 'target', component: cmp3 }); -[4]: #getframeel +// Remove all 'select' spots +canvas.removeSpots({ type: 'select' }); -[5]: #getwindow +// Remove spots by an array of canvas spots +const filteredSpots = canvas.getSpots().filter(spot => myCustomCondition); +canvas.removeSpots(filteredSpots); -[6]: #getdocument +// Remove all spots +canvas.removeSpots(); +``` -[7]: #getbody +Returns **[Array][11]<[CanvasSpot]>** -[8]: #setcustombadgelabel +## hasCustomSpot -[9]: #hasfocus +Check if the built-in canvas spot has a declared custom rendering. -[10]: #scrollto +### Parameters -[11]: #setzoom +* `type` **[String][12]** Built-in canvas spot type -[12]: #getzoom +### Examples + +```javascript +grapesjs.init({ + // ... + canvas: { + // avoid rendering the built-in 'target' canvas spot + customSpots: { target: true } + } +}); +// ... +canvas.hasCustomSpot('select'); // false +canvas.hasCustomSpot('target'); // true +``` + +Returns **[Boolean][8]** + +## getWorldRectToScreen + +Transform a box rect from the world coordinate system to the screen one. + +### Parameters + +* `boxRect` **[Object][2]** + +Returns **[Object][2]** + +[1]: https://github.com/GrapesJS/grapesjs/blob/master/src/canvas/config/config.ts -[13]: #getcoords +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[14]: #setcoords +[3]: https://developer.mozilla.org/docs/Web/HTML/Element -[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[4]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement -[16]: https://developer.mozilla.org/docs/Web/HTML/Element +[5]: https://developer.mozilla.org/docs/Web/API/Window -[17]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement +[6]: https://developer.mozilla.org/docs/Web/HTML/Element/body -[18]: https://developer.mozilla.org/docs/Web/API/Window +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function -[19]: https://developer.mozilla.org/docs/Web/HTML/Element/body +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined -[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String diff --git a/docs/api/components.md b/docs/api/components.md index d6d154a94..1b5564288 100644 --- a/docs/api/components.md +++ b/docs/api/components.md @@ -201,6 +201,23 @@ Return the array of all types Returns **[Array][11]** +## isComponent + +Check if the object is a \[Component]. + +### Parameters + +* `obj` **[Object][10]** + +### Examples + +```javascript +cmp.isComponent(editor.getSelected()); // true +cmp.isComponent({}); // false +``` + +Returns **[Boolean][13]** + ## canMove Check if a component can be moved inside another one.