diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index c2c011fda..c8b70d89b 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -65,6 +65,7 @@ module.exports = { ['/api/components', 'DOM Components'], ['/api/component', ' - Component'], ['/api/panels', 'Panels'], + ['/api/pages', 'Pages'], ['/api/style_manager', 'Style Manager'], ['/api/storage_manager', 'Storage Manager'], ['/api/device_manager', 'Device Manager'], diff --git a/docs/api.js b/docs/api.js index 541d0647b..6db02e247 100644 --- a/docs/api.js +++ b/docs/api.js @@ -23,6 +23,7 @@ const cmds = [ ['undo_manager/index.js', 'undo_manager.md'], ['canvas/index.js', 'canvas.md'], ['i18n/index.js', 'i18n.md'], + ['pages/index.js', 'pages.md'], ].map(entry => `${binRoot}documentation build ${srcRoot}/${entry[0]} -o ${docRoot}/api/${entry[1]} -f md --shallow --markdown-toc false`) .join(' && '); diff --git a/docs/api/canvas.md b/docs/api/canvas.md index d43da98a8..e03426cf9 100644 --- a/docs/api/canvas.md +++ b/docs/api/canvas.md @@ -24,36 +24,35 @@ const canvas = editor.Canvas; - [getWindow][5] - [getDocument][6] - [getBody][7] -- [getWrapperEl][8] -- [setCustomBadgeLabel][9] -- [hasFocus][10] -- [scrollTo][11] -- [setZoom][12] -- [getZoom][13] +- [setCustomBadgeLabel][8] +- [hasFocus][9] +- [scrollTo][10] +- [setZoom][11] +- [getZoom][12] ## getConfig Get the configuration object -Returns **[Object][14]** +Returns **[Object][13]** ## getElement Get the canvas element -Returns **[HTMLElement][15]** +Returns **[HTMLElement][14]** ## getFrameEl Get the iframe element of the canvas -Returns **[HTMLIFrameElement][16]** +Returns **[HTMLIFrameElement][15]** ## getWindow Get the window instance of the iframe element -Returns **[Window][17]** +Returns **[Window][16]** ## getDocument @@ -65,13 +64,7 @@ Returns **HTMLDocument** Get the body of the iframe element -Returns **[HTMLBodyElement][18]** - -## getWrapperEl - -Get the wrapper element containing all the components - -Returns **[HTMLElement][15]** +Returns **[HTMLBodyElement][17]** ## setCustomBadgeLabel @@ -79,7 +72,7 @@ Set custom badge naming strategy ### Parameters -- `f` **[Function][19]** +- `f` **[Function][18]** ### Examples @@ -93,13 +86,13 @@ canvas.setCustomBadgeLabel(function(component){ Get canvas rectangular data -Returns **[Object][14]** +Returns **[Object][13]** ## hasFocus Check if the canvas is focused -Returns **[Boolean][20]** +Returns **[Boolean][19]** ## scrollTo @@ -110,9 +103,9 @@ passed to it. For instance, you can scroll smoothly by using ### Parameters -- `el` **([HTMLElement][15] | Component)** -- `opts` **[Object][14]** Options, same as options for `scrollIntoView` (optional, default `{}`) - - `opts.force` **[Boolean][20]** Force the scroll, even if the element is already visible (optional, default `false`) +- `el` **([HTMLElement][14] | Component)** +- `opts` **[Object][13]** 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`) ### Examples @@ -130,7 +123,7 @@ Set zoom value ### Parameters -- `value` **[Number][21]** The zoom value, from 0 to 100 +- `value` **[Number][20]** The zoom value, from 0 to 100 Returns **this** @@ -138,7 +131,7 @@ Returns **this** Get zoom value -Returns **[Number][21]** +Returns **[Number][20]** ## addFrame @@ -146,7 +139,7 @@ Add new frame to the canvas ### Parameters -- `props` **[Object][14]** Frame properties (optional, default `{}`) +- `props` **[Object][13]** Frame properties (optional, default `{}`) - `opts` (optional, default `{}`) ### Examples @@ -186,30 +179,28 @@ Returns **Frame** [7]: #getbody -[8]: #getwrapperel - -[9]: #setcustombadgelabel +[8]: #setcustombadgelabel -[10]: #hasfocus +[9]: #hasfocus -[11]: #scrollto +[10]: #scrollto -[12]: #setzoom +[11]: #setzoom -[13]: #getzoom +[12]: #getzoom -[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[15]: https://developer.mozilla.org/docs/Web/HTML/Element +[14]: https://developer.mozilla.org/docs/Web/HTML/Element -[16]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement +[15]: https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement -[17]: https://developer.mozilla.org/docs/Web/API/Window +[16]: https://developer.mozilla.org/docs/Web/API/Window -[18]: https://developer.mozilla.org/docs/Web/HTML/Element/body +[17]: https://developer.mozilla.org/docs/Web/HTML/Element/body -[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function -[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number diff --git a/docs/api/component.md b/docs/api/component.md index 349dad368..b23816d4e 100644 --- a/docs/api/component.md +++ b/docs/api/component.md @@ -255,6 +255,25 @@ component.addAttributes({ 'data-key': 'value' }); Returns **this** +## removeAttributes + +Remove attributes from the component + +### Parameters + +- `attrs` **([String][1] \| [Array][4]<[String][1]>)** Array of attributes to remove (optional, default `[]`) +- `opts` (optional, default `{}`) +- `options` **[Object][2]** Options for the model update + +### Examples + +```javascript +component.removeAttributes('some-attr'); +component.removeAttributes(['some-attr1', 'some-attr2']); +``` + +Returns **this** + ## getStyle Get the style of the component @@ -282,6 +301,10 @@ Returns **[Object][2]** Return all component's attributes +### Parameters + +- `opts` (optional, default `{}`) + Returns **[Object][2]** ## addClass @@ -354,7 +377,7 @@ Add new component children ### Parameters - `components` **([Component][9] \| [String][1])** Component to add -- `opts` **[Object][2]** Options, same as in `model.add()`(from backbone) (optional, default `{}`) +- `opts` **[Object][2]** Options for the append action (optional, default `{}`) ### Examples @@ -366,6 +389,8 @@ someComponent.get('components').length // -> 2 // You can pass components directly otherComponent.append(otherComponent2); otherComponent.append([otherComponent3, otherComponent4]); +// append at specific index (eg. at the beginning) +someComponent.append(otherComponent, { at: 0 }); ``` Returns **[Array][4]** Array of appended components @@ -378,6 +403,7 @@ current collection is returned ### Parameters - `components` **([Component][9] \| [String][1])?** Components to set +- `opts` **[Object][2]** Options, same as in `Component.append()` (optional, default `{}`) ### Examples diff --git a/docs/api/css_composer.md b/docs/api/css_composer.md index 81003d764..108abe425 100644 --- a/docs/api/css_composer.md +++ b/docs/api/css_composer.md @@ -115,6 +115,10 @@ Returns **Collection** Remove all rules +### Parameters + +- `opts` (optional, default `{}`) + Returns **this** ## setRule diff --git a/docs/api/editor.md b/docs/api/editor.md index ff1d4ca68..3388b3782 100644 --- a/docs/api/editor.md +++ b/docs/api/editor.md @@ -27,6 +27,7 @@ editor.on('EVENT-NAME', (some, argument) => { - `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:remove:before` - Triggered before the remove of the component, the model, remove function (if aborted via options, with this function you can complete the remove) and options (use options.abort = true to prevent remove), are passed as arguments to the callback - `component:clone` - Triggered when a component is cloned, the new model is passed as an argument to the callback - `component:update` - Triggered when a component is updated (moved, styled, etc.), the model is passed as an argument to the callback - `component:update:{propertyName}` - Listen any property change, the model is passed as an argument to the callback @@ -151,7 +152,8 @@ Returns HTML built inside canvas ### Parameters -- `opts` +- `opts` **[Object][3]** Options (optional, default `{}`) + - `opts.cleanId` **[Boolean][4]** Remove unnecessary IDs (eg. those created automatically) (optional, default `false`) Returns **[string][2]** HTML string diff --git a/docs/api/pages.md b/docs/api/pages.md new file mode 100644 index 000000000..08ec2e499 --- /dev/null +++ b/docs/api/pages.md @@ -0,0 +1,167 @@ + + +## PageManager + +You can customize the initial state of the module from the editor initialization + +```js +const editor = grapesjs.init({ + .... + pageManager: { + pages: [ + { + id: 'page-id', + styles: `.my-class { color: red }`, // or a JSON of styles + component: '
My element
', // or a JSON of components + } + ] + }, +}) +``` + +Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance + +```js +const pageManager = editor.Pages; +``` + +- [add][1] +- [get][2] +- [getAll][3] +- [getMain][4] +- [remove][5] +- [select][6] +- [getSelected][7] + +## add + +Add new page + +### Parameters + +- `props` **[Object][8]** Page properties +- `opts` **[Object][8]?** Options (optional, default `{}`) + +### Examples + +```javascript +const newPage = pageManager.add({ + id: 'new-page-id', // without an explicit ID, a random one will be created + styles: `.my-class { color: red }`, // or a JSON of styles + component: '
My element
', // or a JSON of components +}); +``` + +Returns **Page** + +## remove + +Remove page + +### Parameters + +- `page` **([String][9] | Page)** Page or page id +- `opts` (optional, default `{}`) + +### Examples + +```javascript +const removedPage = pageManager.remove('page-id'); +// or by passing the page +const somePage = pageManager.get('page-id'); +pageManager.remove(somePage); +``` + +Returns **Page** + +## get + +Get page by id + +### Parameters + +- `id` **[String][9]** Page id + +### Examples + +```javascript +const somePage = pageManager.get('page-id'); +``` + +Returns **Page** + +## getMain + +Get main page (the first one available) + +### Examples + +```javascript +const mainPage = pageManager.getMain(); +``` + +Returns **Page** + +## getAll + +Get all pages + +### Examples + +```javascript +const arrayOfPages = pageManager.getAll(); +``` + +Returns **[Array][10]<Page>** + +## select + +Change the selected page. This will switch the page rendered in canvas + +### Parameters + +- `page` **([String][9] | Page)** Page or page id +- `opts` (optional, default `{}`) + +### Examples + +```javascript +pageManager.select('page-id'); +// or by passing the page +const somePage = pageManager.get('page-id'); +pageManager.select(somePage); +``` + +Returns **this** + +## getSelected + +Get the selected page + +### Examples + +```javascript +const selectedPage = pageManager.getSelected(); +``` + +Returns **Page** + +[1]: #add + +[2]: #get + +[3]: #getall + +[4]: #getmain + +[5]: #remove + +[6]: #select + +[7]: #getselected + +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/docs/api/undo_manager.md b/docs/api/undo_manager.md index 9ee446b25..a2e5928a3 100644 --- a/docs/api/undo_manager.md +++ b/docs/api/undo_manager.md @@ -186,6 +186,18 @@ um.hasRedo(); Returns **[Boolean][16]** +## isRegistered + +Check if the entity (Model/Collection) to tracked +Note: New Components and CSSRules will be added automatically + +### Parameters + +- `obj` +- `entity` **(Model | Collection)** Entity to track + +Returns **[Boolean][16]** + ## getStack Get stack of changes diff --git a/src/pages/index.js b/src/pages/index.js index 6ada06f39..385574fdf 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -132,7 +132,7 @@ export default () => { /** * Add new page * @param {Object} props Page properties - * @param {Object} [options] Options + * @param {Object} [opts] Options * @returns {Page} * @example * const newPage = pageManager.add({ @@ -163,14 +163,14 @@ export default () => { * const somePage = pageManager.get('page-id'); * pageManager.remove(somePage); */ - remove(pg, opts = {}) { + remove(page, opts = {}) { const { em } = this; - const page = isString(pg) ? this.get(pg) : pg; + const pg = isString(page) ? this.get(page) : page; const rm = () => { - page && this.pages.remove(page, opts); - return page; + pg && this.pages.remove(pg, opts); + return pg; }; - !opts.silent && em.trigger(evPageRemoveBefore, page, rm, opts); + !opts.silent && em.trigger(evPageRemoveBefore, pg, rm, opts); return !opts.abort && rm(); }, @@ -223,11 +223,11 @@ export default () => { * const somePage = pageManager.get('page-id'); * pageManager.select(somePage); */ - select(pg, opts = {}) { - const page = isString(pg) ? this.get(pg) : pg; - if (page) { - this.em.trigger(evPageSelectBefore, page, opts); - this.model.set('selected', page, opts); + select(page, opts = {}) { + const pg = isString(page) ? this.get(page) : page; + if (pg) { + this.em.trigger(evPageSelectBefore, pg, opts); + this.model.set('selected', pg, opts); } return this; },