diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 760d9d686..f66f8df63 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -53,8 +53,10 @@ module.exports = { sidebar: { '/api/': [ '', - '/api/editor.md', - '/api/assets.md', + ['/api/editor', 'Editor'], + ['/api/assets', 'Asset Manager'], + ['/api/block_manager', 'Block Manager'], + ['/api/commands', 'Commands'], ], '/': [ '', diff --git a/docs/api.js b/docs/api.js new file mode 100644 index 000000000..02d043a9a --- /dev/null +++ b/docs/api.js @@ -0,0 +1,39 @@ +// This script uses documentation to generate API Reference files +const path = require('path'); +const exec = require('child_process').exec; +const docRoot = __dirname; +const srcRoot = path.join(docRoot, '../src/'); +const binRoot = path.join(docRoot, '../node_modules/.bin/'); +const cmds = [ + ['editor/index.js', 'editor.md'], + ['asset_manager/index.js', 'assets.md'], + ['commands/index.js', 'commands.md'], + ['dom_components/index.js', 'components.md'], + ['panels/index.js', 'panels.md'], + ['style_manager/index.js', 'style_manager.md'], + ['storage_manager/index.js', 'storage_manager.md'], + ['device_manager/index.js', 'device_manager.md'], + ['block_manager/index.js', 'block_manager.md'], + ['selector_manager/index.js', 'selector_manager.md'], + ['css_composer/index.js', 'css_composer.md'], + ['modal_dialog/index.js', 'modal_dialog.md'], + ['rich_text_editor/index.js', 'rich_text_editor.md'], + ['keymaps/index.js', 'keymaps.md'], + ['undo_manager/index.js', 'undo_manager.md'], +].map(entry => + `${binRoot}documentation build ${srcRoot}/${entry[0]} -o ${docRoot}/api/${entry[1]} -f md --shallow --markdown-toc false`) +.join(' && '); + +console.log('Start API Reference generation...'); +exec(cmds, (error, stdout, stderr) => { + if (error) { + console.error( 'Failed to update API Reference: ', error); + return; + } + + stdout.trim().split('\n').forEach(function (line) { + console.info(line); + }); + + console.log('API Reference generation done!'); +}); diff --git a/docs/api/assets.md b/docs/api/assets.md index bb2d79233..83879ecf6 100644 --- a/docs/api/assets.md +++ b/docs/api/assets.md @@ -1,3 +1,261 @@ -# Assets + -Assets API +## AssetManager + +- [add][1] +- [get][2] +- [getAll][3] +- [getAllVisible][4] +- [remove][5] +- [getContainer][6] +- [getAssetsEl][7] +- [addType][8] +- [getType][9] +- [getTypes][10] +- [store][11] +- [load][12] + +Before using this methods you should get first the module from the editor instance, in this way: + +```js +var assetManager = editor.AssetManager; +``` + +### Parameters + +- `config` **[Object][13]** Configurations + - `config.assets` **[Array][14]<[Object][13]>** Default assets (optional, default `[]`) + - `config.uploadText` **[String][15]** Upload text (optional, default `'Drop files here or click to upload'`) + - `config.addBtnText` **[String][15]** Text for the add button (optional, default `'Add image'`) + - `config.upload` **[String][15]** Where to send upload data. Expects as return a JSON with asset/s object + as: {data: [{src:'...'}, {src:'...'}]} (optional, default `''`) + +### Examples + +```javascript +... +{ + assets: [ + {src:'path/to/image.png'}, + ... + ], + upload: 'http://dropbox/path', // Set to false to disable it + uploadText: 'Drop files here or click to upload', +} +``` + +Returns **this** + +## add + +Add new asset/s to the collection. URLs are supposed to be unique + +### Parameters + +- `asset` **([string][15] \| [Object][13] \| [Array][14]<[string][15]> | [Array][14]<[Object][13]>)** URL strings or an objects representing the resource. +- `opts` **[Object][13]?** Options (optional, default `{}`) + +### Examples + +```javascript +// In case of strings, would be interpreted as images +assetManager.add('http://img.jpg'); +assetManager.add(['http://img.jpg', './path/to/img.png']); + +// Using objects you could indicate the type and other meta informations +assetManager.add({ + src: 'http://img.jpg', + //type: 'image', //image is default + height: 300, +width: 200, +}); +assetManager.add([{ + src: 'http://img.jpg', +},{ + src: './path/to/img.png', +}]); +``` + +Returns **Model** + +## get + +Returns the asset by URL + +### Parameters + +- `src` **[string][15]** URL of the asset + +### Examples + +```javascript +var asset = assetManager.get('http://img.jpg'); +``` + +Returns **[Object][13]** Object representing the asset + +## getAll + +Return the global collection, containing all the assets + +Returns **Collection** + +## getAllVisible + +Return the visible collection, which containes assets actually rendered + +Returns **Collection** + +## remove + +Remove the asset by its URL + +### Parameters + +- `src` **[string][15]** URL of the asset + +### Examples + +```javascript +assetManager.remove('http://img.jpg'); +``` + +Returns **this** + +## store + +Store assets data to the selected storage + +### Parameters + +- `noStore` **[Boolean][16]** If true, won't store + +### Examples + +```javascript +var assets = assetManager.store(); +``` + +Returns **[Object][13]** Data to store + +## load + +Load data from the passed object. +The fetched data will be added to the collection. + +### Parameters + +- `data` **[Object][13]** Object of data to load (optional, default `{}`) + +### Examples + +```javascript +var assets = assetManager.load({ + assets: [...] +}) +``` + +Returns **[Object][13]** Loaded assets + +## getContainer + +Return the Asset Manager Container + +Returns **[HTMLElement][17]** + +## getAssetsEl + +Get assets element container + +Returns **[HTMLElement][17]** + +## render + +Render assets + +### Parameters + +- `assets` **[array][14]** Assets to render, without the argument will render + all global assets + +### Examples + +```javascript +// Render all assets +assetManager.render(); + +// Render some of the assets +const assets = assetManager.getAll(); +assetManager.render(assets.filter( + asset => asset.get('category') == 'cats' +)); +``` + +Returns **[HTMLElement][17]** + +## addType + +Add new type + +### Parameters + +- `id` **[string][15]** Type ID +- `definition` **[Object][13]** Definition of the type. Each definition contains + `model` (business logic), `view` (presentation logic) + and `isType` function which recognize the type of the + passed entity + addType('my-type', { + model: {}, + view: {}, + isType: (value) => {}, + }) + +## getType + +Get type + +### Parameters + +- `id` **[string][15]** Type ID + +Returns **[Object][13]** Type definition + +## getTypes + +Get types + +Returns **[Array][14]** + +[1]: #add + +[2]: #get + +[3]: #getall + +[4]: #getallvisible + +[5]: #remove + +[6]: #getcontainer + +[7]: #getassetsel + +[8]: #addtype + +[9]: #gettype + +[10]: #gettypes + +[11]: #store + +[12]: #load + +[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[17]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/block_manager.md b/docs/api/block_manager.md new file mode 100644 index 000000000..18492487a --- /dev/null +++ b/docs/api/block_manager.md @@ -0,0 +1,191 @@ + + +## BlockManager + +- [add][1] +- [get][2] +- [getAll][3] +- [getAllVisible][4] +- [getCategories][5] +- [getContainer][6] +- [render][7] + +Block manager helps managing various, draggable, piece of contents that could be easily reused inside templates. + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var blockManager = editor.BlockManager; +``` + +### Parameters + +- `config` **[Object][8]** Configurations + - `config.blocks` **[Array][9]<[Object][8]>** Default blocks (optional, default `[]`) + +### Examples + +```javascript +... +{ + blocks: [ + {id:'h1-block' label: 'Heading', content:'

...

'}, + ... + ], +} +... +``` + +## getConfig + +Get configuration object + +Returns **[Object][8]** + +## onLoad + +Load default blocks if the collection is empty + +## add + +Add new block to the collection. + +### Parameters + +- `id` **[string][10]** Block id +- `opts` **[Object][8]** Options + - `opts.label` **[string][10]** Name of the block + - `opts.content` **[string][10]** HTML content + - `opts.category` **([string][10] \| [Object][8])** Group the block inside a catgegory. + You should pass objects with id property, eg: + {id: 'some-uid', label: 'My category'} + The string will be converted in: + 'someid' => {id: 'someid', label: 'someid'} + - `opts.attributes` **[Object][8]** Block attributes (optional, default `{}`) + +### Examples + +```javascript +blockManager.add('h1-block', { + label: 'Heading', + content: '

Put your title here

', + category: 'Basic', + attributes: { + title: 'Insert h1 block' + } +}); +``` + +Returns **Block** Added block + +## get + +Return the block by id + +### Parameters + +- `id` **[string][10]** Block id + +### Examples + +```javascript +const block = blockManager.get('h1-block'); +console.log(JSON.stringify(block)); +// {label: 'Heading', content: '

Put your ...', ...} +``` + +## getAll + +Return all blocks + +### Examples + +```javascript +const blocks = blockManager.getAll(); +console.log(JSON.stringify(blocks)); +// [{label: 'Heading', content: '

Put your ...'}, ...] +``` + +Returns **Collection** + +## getAllVisible + +Return the visible collection, which containes blocks actually rendered + +Returns **Collection** + +## remove + +Remove a block by id + +### Parameters + +- `id` **[string][10]** Block id + +Returns **Block** Removed block + +## getCategories + +Get all available categories. +It's possible to add categories only within blocks via 'add()' method + +Returns **([Array][9] | Collection)** + +## getContainer + +Return the Blocks container element + +Returns **[HTMLElement][11]** + +## render + +Render blocks + +### Parameters + +- `blocks` **[Array][9]** Blocks to render, without the argument will render + all global blocks + +### Examples + +```javascript +// Render all blocks (inside the global collection) +blockManager.render(); + +// Render new set of blocks +const blocks = blockManager.getAll(); +blockManager.render(blocks.filter( + block => block.get('category') == 'sections' +)); +// Or a new set from an array +blockManager.render([ + {label: 'Label text', content: '
Content
'} +]); + +// Back to blocks from the global collection +blockManager.render(); +``` + +Returns **[HTMLElement][11]** Rendered element + +[1]: #add + +[2]: #get + +[3]: #getall + +[4]: #getallvisible + +[5]: #getcategories + +[6]: #getcontainer + +[7]: #render + +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[11]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/commands.md b/docs/api/commands.md new file mode 100644 index 000000000..5db7cb0f5 --- /dev/null +++ b/docs/api/commands.md @@ -0,0 +1,116 @@ + + +## Commands + +- [add][1] +- [get][2] +- [has][3] + +You can init the editor with all necessary commands via configuration + +```js +var editor = grapesjs.init({ + ... + commands: {...} // Check below for the properties + ... +}); +``` + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var commands = editor.Commands; +``` + +### Parameters + +- `config` **[Object][4]** Configurations + - `config.defaults` **[Array][5]<[Object][4]>** Array of possible commands (optional, default `[]`) + +### Examples + +```javascript +... +commands: { + defaults: [{ + id: 'helloWorld', + run: function(editor, sender){ + alert('Hello world!'); + }, + stop: function(editor, sender){ + alert('Stop!'); + }, + }], +}, +... +``` + +## add + +Add new command to the collection + +### Parameters + +- `id` **[string][6]** Command's ID +- `command` **([Object][4] \| [Function][7])** 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). + +### Examples + +```javascript +commands.add('myCommand', { + run(editor, sender) { + alert('Hello world!'); + }, + stop(editor, sender) { + }, +}); +// As a function +commands.add('myCommand2', editor => { ... }); +``` + +Returns **this** + +## get + +Get command by ID + +### Parameters + +- `id` **[string][6]** Command's ID + +### Examples + +```javascript +var myCommand = commands.get('myCommand'); +myCommand.run(); +``` + +Returns **[Object][4]** Object representing the command + +## has + +Check if command exists + +### Parameters + +- `id` **[string][6]** Command's ID + +Returns **[Boolean][8]** + +[1]: #add + +[2]: #get + +[3]: #has + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function + +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/api/components.md b/docs/api/components.md new file mode 100644 index 000000000..749a29131 --- /dev/null +++ b/docs/api/components.md @@ -0,0 +1,187 @@ + + +## DomComponents + +- [getWrapper][1] +- [getComponents][2] +- [addComponent][3] +- [clear][4] +- [load][5] +- [store][6] +- [render][7] + +With this module is possible to manage components inside the canvas. +Before using methods you should get first the module from the editor instance, in this way: + +```js +var domComponents = editor.DomComponents; +``` + +### Parameters + +- `config` **[Object][8]** Configurations + - `config.components` **([string][9] \| [Array][10]<[Object][8]>)** HTML string or an array of possible components (optional, default `[]`) + +### Examples + +```javascript +... +domComponents: { + components: '
Hello world!
', +} +// Or +domComponents: { + components: [ + { tagName: 'span', style: {color: 'red'}, content: 'Hello'}, + { style: {width: '100px', content: 'world!'}} + ], +} +... +``` + +## load + +Load components from the passed object, if the object is empty will try to fetch them +autonomously from the selected storage +The fetched data will be added to the collection + +### Parameters + +- `data` **[Object][8]** Object of data to load (optional, default `''`) + +Returns **[Object][8]** Loaded data + +## store + +Store components on the selected storage + +### Parameters + +- `noStore` **[Boolean][11]** If true, won't store + +Returns **[Object][8]** Data to store + +## getWrapper + +Returns root component inside the canvas. Something like inside HTML page +The wrapper doesn't differ from the original Component Model + +### Examples + +```javascript +// Change background of the wrapper and set some attribute +var wrapper = domComponents.getWrapper(); +wrapper.set('style', {'background-color': 'red'}); +wrapper.set('attributes', {'title': 'Hello!'}); +``` + +Returns **Component** Root Component + +## getComponents + +Returns wrapper's children collection. Once you have the collection you can +add other Components(Models) inside. Each component can have several nested +components inside and you can nest them as more as you wish. + +### Examples + +```javascript +// Let's add some component +var wrapperChildren = domComponents.getComponents(); +var comp1 = wrapperChildren.add({ + style: { 'background-color': 'red'} +}); +var comp2 = wrapperChildren.add({ + tagName: 'span', + attributes: { title: 'Hello!'} +}); +// Now let's add an other one inside first component +// First we have to get the collection inside. Each +// component has 'components' property +var comp1Children = comp1.get('components'); +// Procede as before. You could also add multiple objects +comp1Children.add([ + { style: { 'background-color': 'blue'}}, + { style: { height: '100px', width: '100px'}} +]); +// Remove comp2 +wrapperChildren.remove(comp2); +``` + +Returns **Components** Collection of components + +## addComponent + +Add new components to the wrapper's children. It's the same +as 'domComponents.getComponents().add(...)' + +### Parameters + +- `component` **([Object][8] | Component | [Array][10]<[Object][8]>)** Component/s to add + - `component.tagName` **[string][9]** Tag name (optional, default `'div'`) + - `component.type` **[string][9]** Type of the component. Available: ''(default), 'text', 'image' (optional, default `''`) + - `component.removable` **[boolean][11]** If component is removable (optional, default `true`) + - `component.draggable` **[boolean][11]** If is possible to move the component around the structure (optional, default `true`) + - `component.droppable` **[boolean][11]** If is possible to drop inside other components (optional, default `true`) + - `component.badgable` **[boolean][11]** If the badge is visible when the component is selected (optional, default `true`) + - `component.stylable` **[boolean][11]** If is possible to style component (optional, default `true`) + - `component.copyable` **[boolean][11]** If is possible to copy&paste the component (optional, default `true`) + - `component.content` **[string][9]** String inside component (optional, default `''`) + - `component.style` **[Object][8]** Style object (optional, default `{}`) + - `component.attributes` **[Object][8]** Attribute object (optional, default `{}`) + +### Examples + +```javascript +// Example of a new component with some extra property +var comp1 = domComponents.addComponent({ + tagName: 'div', + removable: true, // Can't remove it + draggable: true, // Can't move it + copyable: true, // Disable copy/past + content: 'Content text', // Text inside component + style: { color: 'red'}, + attributes: { title: 'here' } +}); +``` + +Returns **(Component | [Array][10]<Component>)** Component/s added + +## render + +Render and returns wrapper element with all components inside. +Once the wrapper is rendered, and it's what happens when you init the editor, +the all new components will be added automatically and property changes are all +updated immediately + +Returns **[HTMLElement][12]** + +## clear + +Remove all components + +Returns **this** + +[1]: #getwrapper + +[2]: #getcomponents + +[3]: #addcomponent + +[4]: #clear + +[5]: #load + +[6]: #store + +[7]: #render + +[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 + +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[12]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/css_composer.md b/docs/api/css_composer.md new file mode 100644 index 000000000..1993f9784 --- /dev/null +++ b/docs/api/css_composer.md @@ -0,0 +1,199 @@ + + +## CssComposer + +This module contains and manage CSS rules for the template inside the canvas +Before using the methods you should get first the module from the editor instance, in this way: + +```js +var cssComposer = editor.CssComposer; +``` + +### Parameters + +- `config` **[Object][1]** Configurations + - `config.rules` **([string][2] \| [Array][3]<[Object][1]>)** CSS string or an array of rule objects (optional, default `[]`) + +### Examples + +```javascript +... +CssComposer: { + rules: '.myClass{ color: red}', +} +``` + +## load + +Load data from the passed object, if the object is empty will try to fetch them +autonomously from the storage manager. +The fetched data will be added to the collection + +### Parameters + +- `data` **[Object][1]** Object of data to load + +Returns **[Object][1]** Loaded rules + +## store + +Store data to the selected storage + +### Parameters + +- `noStore` **[Boolean][4]** If true, won't store + +Returns **[Object][1]** Data to store + +## add + +Add new rule to the collection, if not yet exists with the same selectors + +### Parameters + +- `selectors` **[Array][3]<Selector>** Array of selectors +- `state` **[String][2]** Css rule state +- `width` **[String][2]** For which device this style is oriented +- `opts` **[Object][1]** Other options for the rule (optional, default `{}`) + +### Examples + +```javascript +var sm = editor.SelectorManager; +var sel1 = sm.add('myClass1'); +var sel2 = sm.add('myClass2'); +var rule = cssComposer.add([sel1, sel2], 'hover'); +rule.set('style', { + width: '100px', + color: '#fff', +}); +``` + +Returns **Model** + +## get + +Get the rule + +### Parameters + +- `selectors` **[Array][3]<Selector>** Array of selectors +- `state` **[String][2]** Css rule state +- `width` **[String][2]** For which device this style is oriented +- `ruleProps` **[Object][1]** Other rule props + +### Examples + +```javascript +var sm = editor.SelectorManager; +var sel1 = sm.add('myClass1'); +var sel2 = sm.add('myClass2'); +var rule = cssComposer.get([sel1, sel2], 'hover'); +// Update the style +rule.set('style', { + width: '300px', + color: '#000', +}); +``` + +Returns **(Model | null)** + +## getAll + +Get the collection of rules + +Returns **Collection** + +## clear + +Remove all rules + +Returns **this** + +## setIdRule + +Add/update the CSS rule with id selector + +### Parameters + +- `name` **[string][2]** Id selector name, eg. 'my-id' +- `style` **[Object][1]** Style properties and values (optional, default `{}`) +- `opts` **[Object][1]** Custom options, like `state` and `mediaText` (optional, default `{}`) + +### Examples + +```javascript +const rule = cc.setIdRule('myid', { color: 'red' }); +const ruleHover = cc.setIdRule('myid', { color: 'blue' }, { state: 'hover' }); +// This will add current CSS: +// #myid { color: red } +// #myid:hover { color: blue } +``` + +Returns **CssRule** The new/updated rule + +## getIdRule + +Get the CSS rule by id selector + +### Parameters + +- `name` **[string][2]** Id selector name, eg. 'my-id' +- `opts` **[Object][1]** Custom options, like `state` and `mediaText` (optional, default `{}`) + +### Examples + +```javascript +const rule = cc.getIdRule('myid'); +const ruleHover = cc.setIdRule('myid', { state: 'hover' }); +``` + +Returns **CssRule** + +## setClassRule + +Add/update the CSS rule with class selector + +### Parameters + +- `name` **[string][2]** Class selector name, eg. 'my-class' +- `style` **[Object][1]** Style properties and values (optional, default `{}`) +- `opts` **[Object][1]** Custom options, like `state` and `mediaText` (optional, default `{}`) + +### Examples + +```javascript +const rule = cc.setClassRule('myclass', { color: 'red' }); +const ruleHover = cc.setClassRule('myclass', { color: 'blue' }, { state: 'hover' }); +// This will add current CSS: +// .myclass { color: red } +// .myclass:hover { color: blue } +``` + +Returns **CssRule** The new/updated rule + +## getClassRule + +Get the CSS rule by class selector + +### Parameters + +- `name` **[string][2]** Class selector name, eg. 'my-class' +- `opts` **[Object][1]** Custom options, like `state` and `mediaText` (optional, default `{}`) + +### Examples + +```javascript +const rule = cc.getClassRule('myclass'); +const ruleHover = cc.getClassRule('myclass', { state: 'hover' }); +``` + +Returns **CssRule** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/api/device_manager.md b/docs/api/device_manager.md new file mode 100644 index 000000000..d7e9d00a3 --- /dev/null +++ b/docs/api/device_manager.md @@ -0,0 +1,65 @@ + + +## DeviceManager + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var deviceManager = editor.DeviceManager; +``` + +## add + +Add new device to the collection. URLs are supposed to be unique + +### Parameters + +- `name` **[string][1]** Device name +- `width` **[string][1]** Width of the device +- `opts` **[Object][2]** Custom options + +### Examples + +```javascript +deviceManager.add('Tablet', '900px'); +deviceManager.add('Tablet2', '900px', { + height: '300px', + widthMedia: '810px', // the width that will be used for the CSS media +}); +``` + +Returns **Device** Added device + +## get + +Return device by name + +### Parameters + +- `name` **[string][1]** Name of the device + +### Examples + +```javascript +var device = deviceManager.get('Tablet'); +console.log(JSON.stringify(device)); +// {name: 'Tablet', width: '900px'} +``` + +## getAll + +Return all devices + +### Examples + +```javascript +var devices = deviceManager.getAll(); +console.log(JSON.stringify(devices)); +// [{name: 'Desktop', width: ''}, ...] +``` + +Returns **Collection** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object diff --git a/docs/api/editor.md b/docs/api/editor.md index 37f0d0418..d06c7057b 100644 --- a/docs/api/editor.md +++ b/docs/api/editor.md @@ -1,3 +1,535 @@ -# Editor + -Editor API +## $ + +Editor class contains the top level API which you'll probably use to custom the editor or extend it with plugins. +You get the Editor instance on init method + +```js +var editor = grapesjs.init({...}); +``` + +# Available Events + +## Components + +- `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 new component is added by a clone command, the 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 +- `component:styleUpdate` - Triggered when the style of the component is updated, the model is passed as an argument to the callback +- `component:styleUpdate:{propertyName}` - Listen for a specific style property change, the model is passed as an argument to the callback +- `component:selected` - New component selected, the selected model is passed as an argument to the callback +- `component:deselected` - Component deselected, the deselected model is passed as an argument to the callback +- `component:toggled` - Component selection changed, toggled model is passed as an argument to the callback + +## Blocks + +- `block:add` - New block added +- `block:remove` - Block removed +- `block:drag:start` - Started dragging block, model of the block is passed as an argument +- `block:drag` - Dragging block, the block's model and the drag event are passed as arguments +- `block:drag:stop` - Dragging of the block is stopped. As agruments for the callback you get, the dropped component model (if dropped successfully) and the model of the block + +## Assets + +- `asset:add` - New asset added +- `asset:remove` - Asset removed +- `asset:upload:start` - Before the upload is started +- `asset:upload:end` - After the upload is ended +- `asset:upload:error` - On any error in upload, passes the error as an argument +- `asset:upload:response` - On upload response, passes the result as an argument + +## Keymaps + +- `keymap:add` - New keymap added. The new keyamp object is passed as an argument +- `keymap:remove` - Keymap removed. The removed keyamp object is passed as an argument +- `keymap:emit` - Some keymap emitted, in arguments you get keymapId, shortcutUsed, Event +- `keymap:emit:{keymapId}` - `keymapId` emitted, in arguments you get keymapId, shortcutUsed, Event + +## Style Manager + +- `styleManager:change` - Triggered on style property change from new selected component, the view of the property is passed as an argument to the callback +- `styleManager:change:{propertyName}` - As above but for a specific style property + +## Storages + +- `storage:start` - Before the storage request is started +- `storage:start:store` - Before the store request. The object to store is passed as an argumnet (which you can edit) +- `storage:start:load` - Before the load request. Items to load are passed as an argumnet (which you can edit) +- `storage:load` - Triggered when something was loaded from the storage, loaded object passed as an argumnet +- `storage:store` - Triggered when something is stored to the storage, stored object passed as an argumnet +- `storage:end` - After the storage request is ended +- `storage:end:store` - After the store request +- `storage:end:load` - After the load request +- `storage:error` - On any error on storage request, passes the error as an argument +- `storage:error:store` - Error on store request, passes the error as an argument +- `storage:error:load` - Error on load request, passes the error as an argument + +## Canvas + +- `canvas:dragenter` - When something is dragged inside the canvas, `DataTransfer` instance passed as an argument +- `canvas:dragover` - When something is dragging on canvas, `DataTransfer` instance passed as an argument +- `canvas:drop` - Something is dropped in canvas, `DataTransfer` instance and the dropped model are passed as arguments +- `canvas:dragend` - When a drag operation is ended, `DataTransfer` instance passed as an argument +- `canvas:dragdata` - On any dataTransfer parse, `DataTransfer` instance and the `result` are passed as arguments. + By changing `result.content` you're able to customize what is dropped + +## Selectors + +- `selector:add` - Triggers when a new selector/class is created + +## RTE + +- `rte:enable` - RTE enabled. The view, on which RTE is enabled, is passed as an argument +- `rte:disable` - RTE disabled. The view, on which RTE is disabled, is passed as an argument + +## Commands + +- `run:{commandName}` - Triggered when some command is called to run (eg. editor.runCommand('preview')) +- `stop:{commandName}` - Triggered when some command is called to stop (eg. editor.stopCommand('preview')) +- `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);`) + +## General + +- `canvasScroll` - Triggered when the canvas is scrolle +- `undo` - Undo executed +- `redo` - Redo executed +- `load` - When the editor is loaded + +### Parameters + +- `config` **[Object][1]** Configurations + - `config.container` **[string][2]** ='' Selector for the editor container, eg. '#myEditor' + - `config.components` **([string][2] \| [Array][3]<[Object][1]>)** HTML string or object of components (optional, default `''`) + - `config.style` **([string][2] \| [Array][3]<[Object][1]>)** CSS string or object of rules (optional, default `''`) + - `config.fromElement` **[Boolean][4]** If true, will fetch HTML and CSS from selected container (optional, default `false`) + - `config.undoManager` **[Boolean][4]** Enable/Disable undo manager (optional, default `true`) + - `config.autorender` **[Boolean][4]** If true renders editor on init (optional, default `true`) + - `config.noticeOnUnload` **[Boolean][4]** Enable/Disable alert message before unload the page (optional, default `true`) + - `config.height` **[string][2]** Height for the editor container (optional, default `'900px'`) + - `config.width` **[string][2]** Width for the editor container (optional, default `'100%'`) + - `config.storage` **[Object][1]** Storage manager configuration, see the relative documentation (optional, default `{}`) + - `config.styleManager` **[Object][1]** Style manager configuration, see the relative documentation (optional, default `{}`) + - `config.commands` **[Object][1]** Commands configuration, see the relative documentation (optional, default `{}`) + - `config.domComponents` **[Object][1]** Components configuration, see the relative documentation (optional, default `{}`) + - `config.panels` **[Object][1]** Panels configuration, see the relative documentation (optional, default `{}`) + - `config.showDevices` **[Object][1]** If true render a select of available devices inside style manager panel (optional, default `true`) + - `config.keepEmptyTextNodes` **[Boolean][4]** If false, removes empty text nodes when parsed (unless they contain a space) (optional, default `false`) + - `config.defaultCommand` **[string][2]** Command to execute when no other command is running (optional, default `'select-comp'`) + - `config.plugins` **[Array][3]** Array of plugins to execute on start (optional, default `[]`) + - `config.pluginsOpts` **[Object][1]** Custom options for plugins (optional, default `{}`) + +### Examples + +```javascript +var editor = grapesjs.init({ + container : '#gjs', + components: '
Hello world!
', + style: '.txt-red{color: red}', +}); +``` + +## AssetManager + +## getConfig + +Returns configuration object + +### Parameters + +- `prop` **[string][2]?** Property name + +Returns **any** Returns the configuration object or + the value of the specified property + +## getHtml + +Returns HTML built inside canvas + +### Parameters + +- `opts` + +Returns **[string][2]** HTML string + +## getCss + +Returns CSS built inside canvas + +### Parameters + +- `opts` **[Object][1]** Options (optional, default `{}`) + +Returns **[string][2]** CSS string + +## getJs + +Returns JS of all components + +Returns **[string][2]** JS string + +## getComponents + +Returns components in JSON format object + +Returns **[Object][1]** + +## setComponents + +Set components inside editor's canvas. This method overrides actual components + +### Parameters + +- `components` **([Array][3]<[Object][1]> | [Object][1] \| [string][2])** HTML string or components model + +### Examples + +```javascript +editor.setComponents('
New component
'); +// or +editor.setComponents({ + type: 'text', + classes:['cls'], + content: 'New component' +}); +``` + +Returns **this** + +## addComponents + +Add components + +### Parameters + +- `components` **([Array][3]<[Object][1]> | [Object][1] \| [string][2])** HTML string or components model +- `opts` **[Object][1]** Options + - `opts.avoidUpdateStyle` **[Boolean][4]** If the HTML string contains styles, + by default, they will be created and, if already exist, updated. When this option + is true, styles already created will not be updated. (optional, default `false`) + +### Examples + +```javascript +editor.addComponents('
New component
'); +// or +editor.addComponents({ + type: 'text', + classes:['cls'], + content: 'New component' +}); +``` + +Returns **(Model | [Array][3]<Model>)** + +## getStyle + +Returns style in JSON format object + +Returns **[Object][1]** + +## setStyle + +Set style inside editor's canvas. This method overrides actual style + +### Parameters + +- `style` **([Array][3]<[Object][1]> | [Object][1] \| [string][2])** CSS string or style model + +### Examples + +```javascript +editor.setStyle('.cls{color: red}'); +//or +editor.setStyle({ + selectors: ['cls'] + style: { color: 'red' } +}); +``` + +Returns **this** + +## getSelected + +Returns the last selected component, if there is one + +Returns **Model** + +## getSelectedAll + +Returns an array of all selected components + +Returns **[Array][3]** + +## getSelectedToStyle + +Get a stylable entity from the selected component. +If you select a component without classes the entity is the Component +itself and all changes will go inside its 'style' attribute. Otherwise, +if the selected component has one or more classes, the function will +return the corresponding CSS Rule + +Returns **Model** + +## select + +Select a component + +### Parameters + +- `el` **(Component | [HTMLElement][5])** Component to select + +### Examples + +```javascript +// Select dropped block +editor.on('block:drag:stop', function(model) { + editor.select(model); +}); +``` + +Returns **this** + +## selectAdd + +Add component to selection + +### Parameters + +- `el` **(Component | [HTMLElement][5] \| [Array][3])** Component to select + +### Examples + +```javascript +editor.selectAdd(model); +``` + +Returns **this** + +## selectRemove + +Remove component from selection + +### Parameters + +- `el` **(Component | [HTMLElement][5] \| [Array][3])** Component to select + +### Examples + +```javascript +editor.selectRemove(model); +``` + +Returns **this** + +## selectToggle + +Toggle component selection + +### Parameters + +- `el` **(Component | [HTMLElement][5] \| [Array][3])** Component to select + +### Examples + +```javascript +editor.selectToggle(model); +``` + +Returns **this** + +## setDevice + +Set device to the editor. If the device exists it will +change the canvas to the proper width + +### Parameters + +- `name` **[string][2]** Name of the device + +### Examples + +```javascript +editor.setDevice('Tablet'); +``` + +Returns **this** + +## getDevice + +Return the actual active device + +### Examples + +```javascript +var device = editor.getDevice(); +console.log(device); +// 'Tablet' +``` + +Returns **[string][2]** Device name + +## runCommand + +Execute command + +### Parameters + +- `id` **[string][2]** Command ID +- `options` **[Object][1]** Custom options (optional, default `{}`) + +### Examples + +```javascript +editor.runCommand('myCommand', {someValue: 1}); +``` + +Returns **any** The return is defined by the command + +## stopCommand + +Stop the command if stop method was provided + +### Parameters + +- `id` **[string][2]** Command ID +- `options` **[Object][1]** Custom options (optional, default `{}`) + +### Examples + +```javascript +editor.stopCommand('myCommand', {someValue: 1}); +``` + +Returns **any** The return is defined by the command + +## store + +Store data to the current storage + +### Parameters + +- `clb` **[Function][6]** Callback function + +Returns **[Object][1]** Stored data + +## load + +Load data from the current storage + +### Parameters + +- `clb` **[Function][6]** Callback function + +Returns **[Object][1]** Stored data + +## getContainer + +Returns container element. The one which was indicated as 'container' +on init method + +Returns **[HTMLElement][5]** + +## getDirtyCount + +Return the count of changes made to the content and not yet stored. +This count resets at any `store()` + +Returns **[number][7]** + +## setCustomRte + +Replace the built-in Rich Text Editor with a custom one. + +### Parameters + +- `obj` **[Object][1]** Custom RTE Interface + +### Examples + +```javascript +editor.setCustomRte({ + // Function for enabling custom RTE + // el is the HTMLElement of the double clicked Text Component + // rte is the same instance you have returned the first time you call + // enable(). This is useful if need to check if the RTE is already enabled so + // ion this case you'll need to return the RTE and the end of the function + enable: function(el, rte) { + rte = new MyCustomRte(el, {}); // this depends on the Custom RTE API + ... + return rte; // return the RTE instance + }, + + // Disable the editor, called for example when you unfocus the Text Component + disable: function(el, rte) { + rte.blur(); // this depends on the Custom RTE API + } + +// Called when the Text Component is focused again. If you returned the RTE instance +// from the enable function, the enable won't be called again instead will call focus, +// in this case to avoid double binding of the editor + focus: function (el, rte) { + rte.focus(); // this depends on the Custom RTE API + } +}); +``` + +## on + +Attach event + +### Parameters + +- `event` **[string][2]** Event name +- `callback` **[Function][6]** Callback function + +Returns **this** + +## off + +Detach event + +### Parameters + +- `event` **[string][2]** Event name +- `callback` **[Function][6]** Callback function + +Returns **this** + +## trigger + +Trigger event + +### Parameters + +- `event` **[string][2]** Event to trigger + +Returns **this** + +## destroy + +Destroy the editor + +## render + +Render editor + +Returns **[HTMLElement][5]** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[5]: https://developer.mozilla.org/docs/Web/HTML/Element + +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function + +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number diff --git a/docs/api/keymaps.md b/docs/api/keymaps.md new file mode 100644 index 000000000..e5887df02 --- /dev/null +++ b/docs/api/keymaps.md @@ -0,0 +1,99 @@ + + +## isString + +This module allows to create shortcuts for functions and commands (via command id) + +You can access the module in this way + +```js +const keymaps = editor.Keymaps; +``` + +## getConfig + +Get module configurations + +Returns **[Object][1]** Configuration object + +## add + +Add new keymap + +### Parameters + +- `id` **[string][2]** Keymap id +- `keys` **[string][2]** Keymap keys, eg. `ctrl+a`, `⌘+z, ctrl+z` +- `handler` **([Function][3] \| [string][2])** Keymap handler, might be a function + +### Examples + +```javascript +// 'ns' is just a custom namespace +keymaps.add('ns:my-keymap', '⌘+j, ⌘+u, ctrl+j, alt+u', editor => { + console.log('do stuff'); +}); +// or +keymaps.add('ns:my-keymap', '⌘+s, ctrl+s', 'some-gjs-command'); + +// listen to events +editor.on('keymap:emit', (id, shortcut, e) => { + // ... +}) +``` + +Returns **[Object][1]** Added keymap + or just a command id as a string + +## get + +Get the keymap by id + +### Parameters + +- `id` **[string][2]** Keymap id + +### Examples + +```javascript +keymaps.get('ns:my-keymap'); +// -> {keys, handler}; +``` + +Returns **[Object][1]** Keymap object + +## getAll + +Get all keymaps + +### Examples + +```javascript +keymaps.getAll(); +// -> {id1: {}, id2: {}}; +``` + +Returns **[Object][1]** + +## remove + +Remove the keymap by id + +### Parameters + +- `id` **[string][2]** Keymap id + +### Examples + +```javascript +keymaps.remove('ns:my-keymap'); +// -> {keys, handler}; +``` + +Returns **[Object][1]** Removed keymap + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function diff --git a/docs/api/modal_dialog.md b/docs/api/modal_dialog.md new file mode 100644 index 000000000..c286a76eb --- /dev/null +++ b/docs/api/modal_dialog.md @@ -0,0 +1,99 @@ + + +## Modal + +- [open][1] +- [close][2] +- [isOpen][3] +- [setTitle][4] +- [getTitle][5] +- [setContent][6] +- [getContent][7] + +Before using the methods you should get first the module from the editor instance, in this way: + +```js +var modal = editor.Modal; +``` + +## open + +Open the modal window + +Returns **this** + +## close + +Close the modal window + +Returns **this** + +## isOpen + +Checks if the modal window is open + +Returns **[Boolean][8]** + +## setTitle + +Set the title to the modal window + +### Parameters + +- `title` **[string][9]** Title + +### Examples + +```javascript +modal.setTitle('New title'); +``` + +Returns **this** + +## getTitle + +Returns the title of the modal window + +Returns **[string][9]** + +## setContent + +Set the content of the modal window + +### Parameters + +- `content` **([string][9] \| [HTMLElement][10])** Content + +### Examples + +```javascript +modal.setContent('
Some HTML content
'); +``` + +Returns **this** + +## getContent + +Get the content of the modal window + +Returns **[string][9]** + +[1]: #open + +[2]: #close + +[3]: #isopen + +[4]: #settitle + +[5]: #gettitle + +[6]: #setcontent + +[7]: #getcontent + +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[10]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/panels.md b/docs/api/panels.md new file mode 100644 index 000000000..bf66467b5 --- /dev/null +++ b/docs/api/panels.md @@ -0,0 +1,240 @@ + + +## Panels + +- [addPanel][1] +- [addButton][2] +- [removeButton][3] +- [getButton][4] +- [getPanel][5] +- [getPanels][6] +- [render][7] + +This module manages panels and buttons inside the editor. +You can init the editor with all panels and buttons necessary via configuration + +```js +var editor = grapesjs.init({ + ... + panels: {...} // Check below for the possible properties + ... +}); +``` + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var panelManager = editor.Panels; +``` + +### Parameters + +- `config` **[Object][8]** Configurations + - `config.defaults` **[Array][9]<[Object][8]>** Array of possible panels (optional, default `[]`) + +### Examples + +```javascript +... +panels: { + defaults: [{ + id: 'main-toolbar', + buttons: [{ + id: 'btn-id', + className: 'some', + attributes: { + title: 'MyTitle' + } + }], + }], +} +... +``` + +## init + +Initialize module. Automatically called with a new instance of the editor + +### Parameters + +- `config` **[Object][8]** Configurations + +## getPanels + +Returns the collection of panels + +Returns **Collection** Collection of panel + +## getPanelsEl + +Returns panels element + +Returns **[HTMLElement][10]** + +## addPanel + +Add new panel to the collection + +### Parameters + +- `panel` **([Object][8] | Panel)** Object with right properties or an instance of Panel + +### Examples + +```javascript +var newPanel = panelManager.addPanel({ + id: 'myNewPanel', + visible : true, + buttons : [...], +}); +``` + +Returns **Panel** Added panel. Useful in case passed argument was an Object + +## removePanel + +Remove a panel from the collection + +### Parameters + +- `panel` **([Object][8] | Panel | [String][11])** Object with right properties or an instance of Panel or Painel id + +### Examples + +```javascript +const newPanel = panelManager.removePanel({ + id: 'myNewPanel', + visible : true, + buttons : [...], +}); + +const newPanel = panelManager.removePanel('myNewPanel'); +``` + +Returns **Panel** Removed panel. Useful in case passed argument was an Object + +## getPanel + +Get panel by ID + +### Parameters + +- `id` **[string][11]** Id string + +### Examples + +```javascript +var myPanel = panelManager.getPanel('myNewPanel'); +``` + +Returns **(Panel | null)** + +## addButton + +Add button to the panel + +### Parameters + +- `panelId` **[string][11]** Panel's ID +- `button` **([Object][8] | Button)** Button object or instance of Button + +### Examples + +```javascript +var newButton = panelManager.addButton('myNewPanel',{ + id: 'myNewButton', + className: 'someClass', + command: 'someCommand', + attributes: { title: 'Some title'}, + active: false, +}); +// It's also possible to pass the command as an object +// with .run and .stop methods +... +command: { + run: function(editor) { + ... + }, + stop: function(editor) { + ... + } +}, +// Or simply like a function which will be evaluated as a single .run command +... +command: function(editor) { + ... +} +``` + +Returns **(Button | null)** Added button. Useful in case passed button was an Object + +## removeButton + +Remove button from the panel + +### Parameters + +- `panelId` **[string][11]** Panel's ID +- `button` **([Object][8] | Button | [String][11])** Button object or instance of Button or button id + +### Examples + +```javascript +const removedButton = panelManager.removeButton('myNewPanel',{ + id: 'myNewButton', + className: 'someClass', + command: 'someCommand', + attributes: { title: 'Some title'}, + active: false, +}); + +// It's also possible to use the button id +const removedButton = panelManager.removeButton('myNewPanel','myNewButton'); +``` + +Returns **(Button | null)** Removed button. + +## getButton + +Get button from the panel + +### Parameters + +- `panelId` **[string][11]** Panel's ID +- `id` **[string][11]** Button's ID + +### Examples + +```javascript +var button = panelManager.getButton('myPanel','myButton'); +``` + +Returns **(Button | null)** + +## render + +Render panels and buttons + +Returns **[HTMLElement][10]** + +[1]: #addpanel + +[2]: #addbutton + +[3]: #removebutton + +[4]: #getbutton + +[5]: #getpanel + +[6]: #getpanels + +[7]: #render + +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[10]: https://developer.mozilla.org/docs/Web/HTML/Element + +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String diff --git a/docs/api/rich_text_editor.md b/docs/api/rich_text_editor.md new file mode 100644 index 000000000..edfc0bd92 --- /dev/null +++ b/docs/api/rich_text_editor.md @@ -0,0 +1,115 @@ + + +## RichTextEditor + +This module allows to customize the toolbar of the Rich Text Editor and use commands from the HTML Editing APIs. +For more info about HTML Editing APIs check here: +[https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand][1] + +It's highly recommended to keep this toolbar as small as possible, especially from styling commands (eg. 'fontSize') +and leave this task to the Style Manager. + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var rte = editor.RichTextEditor; +``` + +## add + +Add a new action to the built-in RTE toolbar + +### Parameters + +- `name` **[string][2]** Action name +- `action` **[Object][3]** Action options (optional, default `{}`) + +### Examples + +```javascript +rte.add('bold', { + icon: 'B', + attributes: {title: 'Bold',} + result: rte => rte.exec('bold') +}); +rte.add('link', { + icon: document.getElementById('t'), + attributes: {title: 'Link',} + // Example on it's easy to wrap a selected content + result: rte => rte.insertHTML(`${rte.selection()}`) +}); +// An example with fontSize +rte.add('fontSize', { + icon: ``, + // Bind the 'result' on 'change' listener + event: 'change', + result: (rte, action) => rte.exec('fontSize', action.btn.firstChild.value), + // Callback on any input change (mousedown, keydown, etc..) + update: (rte, action) => { + const value = rte.doc.queryCommandValue(action.name); + if (value != 'false') { // value is a string + action.btn.firstChild.value = value; + } + } + }) +``` + +## get + +Get the action by its name + +### Parameters + +- `name` **[string][2]** Action name + +### Examples + +```javascript +const action = rte.get('bold'); +// {name: 'bold', ...} +``` + +Returns **[Object][3]** + +## getAll + +Get all actions + +Returns **[Array][4]** + +## remove + +Remove the action from the toolbar + +### Parameters + +- `name` **[string][2]** + +### Examples + +```javascript +const action = rte.remove('bold'); +// {name: 'bold', ...} +``` + +Returns **[Object][3]** Removed action + +## getToolbarEl + +Get the toolbar element + +Returns **[HTMLElement][5]** + +[1]: https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[5]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/selector_manager.md b/docs/api/selector_manager.md new file mode 100644 index 000000000..73425838d --- /dev/null +++ b/docs/api/selector_manager.md @@ -0,0 +1,132 @@ + + +## SelectorManager + +Selectors in GrapesJS are used in CSS Composer inside Rules and in Components as classes. To get better this concept let's take +a look at this code: + +```css +span > #send-btn.btn{ + ... +} +``` + +```html + + + +``` + +In this scenario we get: +span -> selector of type `tag` +send-btn -> selector of type `id` +btn -> selector of type `class` + +So, for example, being `btn` the same class entity it'll be easier to refactor and track things. + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var selectorManager = editor.SelectorManager; +``` + +### Parameters + +- `config` **[Object][1]** Configurations + - `config.selectors` **[Array][2]<[Object][1]>** Default selectors (optional, default `[]`) + - `config.states` **[Array][2]<[Object][1]>** Default states (optional, default `[]`) + - `config.label` **[String][3]** Classes label (optional, default `'Classes'`) + - `config.statesLabel` **[String][3]** The empty state label (optional, default `'- State -'`) + +### Examples + +```javascript +... +{ + selectors: [ + {name:'myselector1'}, + ... + ], + states: [{ + name: 'hover', label: 'Hover' + },{ + name: 'active', label: 'Click' + }], + statesLabel: '- Selecte State -', +} +``` + +Returns **this** + +## add + +Add a new selector to collection if it's not already exists. Class type is a default one + +### Parameters + +- `name` **[String][3]** Selector name +- `opts` **[Object][1]** Selector options (optional, default `{}`) + - `opts.label` **[String][3]** Label for the selector, if it's not provided the label will be the same as the name (optional, default `''`) + - `opts.type` **[String][3]** Type of the selector. At the moment, only 'class' (1) is available (optional, default `1`) + +### Examples + +```javascript +var selector = selectorManager.add('selectorName'); +// Same as +var selector = selectorManager.add('selectorName', { + type: 1, + label: 'selectorName' +}); +``` + +Returns **Model** + +## addClass + +Add class selectors + +### Parameters + +- `classes` **([Array][2] \| [string][3])** Array or string of classes + +### Examples + +```javascript +sm.addClass('class1'); +sm.addClass('class1 class2'); +sm.addClass(['class1', 'class2']); +// -> [SelectorObject, ...] +``` + +Returns **[Array][2]** Array of added selectors + +## get + +Get the selector by its name + +### Parameters + +- `name` **[String][3]** Selector name +- `type` (optional, default `Selector.TYPE_CLASS`) +- `tyoe` **[String][3]** Selector type + +### Examples + +```javascript +var selector = selectorManager.get('selectorName'); +``` + +Returns **(Model | null)** + +## getAll + +Get all selectors + +Returns **Collection** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String diff --git a/docs/api/storage_manager.md b/docs/api/storage_manager.md new file mode 100644 index 000000000..7f9400a92 --- /dev/null +++ b/docs/api/storage_manager.md @@ -0,0 +1,169 @@ + + +## index + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var storageManager = editor.StorageManager; +``` + +## getConfig + +Get configuration object + +Returns **[Object][1]** + +## isAutosave + +Checks if autosave is enabled + +Returns **[Boolean][2]** + +## setAutosave + +Set autosave value + +### Parameters + +- `v` **[Boolean][2]** + +Returns **this** + +## getStepsBeforeSave + +Returns number of steps required before trigger autosave + +Returns **[number][3]** + +## setStepsBeforeSave + +Set steps required before trigger autosave + +### Parameters + +- `v` **[number][3]** + +Returns **this** + +## add + +Add new storage + +### Parameters + +- `id` **[string][4]** Storage ID +- `storage` **[Object][1]** Storage wrapper + - `storage.load` **[Function][5]** Load method + - `storage.store` **[Function][5]** Store method + +### Examples + +```javascript +storageManager.add('local2', { + load: function(keys, clb, clbErr) { + var res = {}; + for (var i = 0, len = keys.length; i < len; i++){ + var v = localStorage.getItem(keys[i]); + if(v) res[keys[i]] = v; + } + clb(res); // might be called inside some async method + // In case of errors... + // clbErr('Went something wrong'); + }, + store: function(data, clb, clbErr) { + for(var key in data) + localStorage.setItem(key, data[key]); + clb(); // might be called inside some async method + } +}); +``` + +Returns **this** + +## get + +Returns storage by id + +### Parameters + +- `id` **[string][4]** Storage ID + +Returns **([Object][1] | null)** + +## getStorages + +Returns all storages + +Returns **[Array][6]** + +## getCurrent + +Returns current storage type + +Returns **[string][4]** + +## setCurrent + +Set current storage type + +### Parameters + +- `id` **[string][4]** Storage ID + +Returns **this** + +## store + +Store key-value resources in the current storage + +### Parameters + +- `data` **[Object][1]** Data in key-value format, eg. {item1: value1, item2: value2} +- `clb` **[Function][5]** Callback function + +### Examples + +```javascript +storageManager.store({item1: value1, item2: value2}); +``` + +Returns **([Object][1] | null)** + +## load + +Load resource from the current storage by keys + +### Parameters + +- `keys` **([string][4] \| [Array][6]<[string][4]>)** Keys to load +- `clb` **[Function][5]** Callback function + +### Examples + +```javascript +storageManager.load(['item1', 'item2'], res => { + // res -> {item1: value1, item2: value2} +}); +storageManager.load('item1', res => { +// res -> {item1: value1} +}); +``` + +## getCurrentStorage + +Get current storage + +Returns **Storage** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function + +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/docs/api/style_manager.md b/docs/api/style_manager.md new file mode 100644 index 000000000..75ccc1267 --- /dev/null +++ b/docs/api/style_manager.md @@ -0,0 +1,304 @@ + + +## StyleManager + +With Style Manager you basically build categories (called sectors) of CSS properties which could +be used to custom components and classes. +You can init the editor with all sectors and properties via configuration + +```js +var editor = grapesjs.init({ + ... + styleManager: {...} // Check below for the possible properties + ... +}); +``` + +Before using methods you should get first the module from the editor instance, in this way: + +```js +var styleManager = editor.StyleManager; +``` + +### Parameters + +- `config` **[Object][1]** Configurations + - `config.sectors` **[Array][2]<[Object][1]>** Array of possible sectors (optional, default `[]`) + +### Examples + +```javascript +... +styleManager: { + sectors: [{ + id: 'dim', + name: 'Dimension', + properties: [{ + name: 'Width', + property: 'width', + type: 'integer', + units: ['px', '%'], + defaults: 'auto', + min: 0, +}], + }], +} +... +``` + +## init + +Initialize module. Automatically called with a new instance of the editor + +### Parameters + +- `config` **[Object][1]** Configurations + +## addSector + +Add new sector to the collection. If the sector with the same id already exists, +that one will be returned + +### Parameters + +- `id` **[string][3]** Sector id +- `sector` **[Object][1]** Object representing sector + - `sector.name` **[string][3]** Sector's label (optional, default `''`) + - `sector.open` **[Boolean][4]** Indicates if the sector should be opened (optional, default `true`) + - `sector.properties` **[Array][2]<[Object][1]>** Array of properties (optional, default `[]`) + +### Examples + +```javascript +var sector = styleManager.addSector('mySector',{ + name: 'My sector', + open: true, + properties: [{ name: 'My property'}] +}); +``` + +Returns **Sector** Added Sector + +## getSector + +Get sector by id + +### Parameters + +- `id` **[string][3]** Sector id + +### Examples + +```javascript +var sector = styleManager.getSector('mySector'); +``` + +Returns **(Sector | null)** + +## removeSector + +Remove a sector by id + +### Parameters + +- `id` **[string][3]** Sector id + +### Examples + +```javascript +const removed = styleManager.removeSector('mySector'); +``` + +Returns **Sector** Removed sector + +## getSectors + +Get all sectors + +Returns **Sectors** Collection of sectors + +## addProperty + +Add property to the sector identified by id + +### Parameters + +- `sectorId` **[string][3]** Sector id +- `property` **[Object][1]** Property object + - `property.name` **[string][3]** Name of the property (optional, default `''`) + - `property.property` **[string][3]** CSS property, eg. `min-height` (optional, default `''`) + - `property.type` **[string][3]** Type of the property: integer | radio | select | color | file | composite | stack (optional, default `''`) + - `property.units` **[Array][2]<[string][3]>** Unit of measure available, eg. ['px','%','em']. Only for integer type (optional, default `[]`) + - `property.unit` **[string][3]** Default selected unit from `units`. Only for integer type (optional, default `''`) + - `property.min` **[number][5]** Min possible value. Only for integer type (optional, default `null`) + - `property.max` **[number][5]** Max possible value. Only for integer type (optional, default `null`) + - `property.defaults` **[string][3]** Default value (optional, default `''`) + - `property.info` **[string][3]** Some description (optional, default `''`) + - `property.icon` **[string][3]** Class name. If exists no text will be displayed (optional, default `''`) + - `property.preview` **[Boolean][4]** Show layers preview. Only for stack type (optional, default `false`) + - `property.functionName` **[string][3]** Indicates if value need to be wrapped in some function, for istance `transform: rotate(90deg)` (optional, default `''`) + - `property.properties` **[Array][2]<[Object][1]>** Nested properties for composite and stack type (optional, default `[]`) + - `property.layers` **[Array][2]<[Object][1]>** Layers for stack properties (optional, default `[]`) + - `property.list` **[Array][2]<[Object][1]>** List of possible options for radio and select types (optional, default `[]`) + +### Examples + +```javascript +var property = styleManager.addProperty('mySector',{ + name: 'Minimum height', + property: 'min-height', + type: 'select', + defaults: '100px', + list: [{ + value: '100px', + name: '100', + },{ + value: '200px', + name: '200', + }], +}); +``` + +Returns **(Property | null)** Added Property or `null` in case sector doesn't exist + +## getProperty + +Get property by its CSS name and sector id + +### Parameters + +- `sectorId` **[string][3]** Sector id +- `name` **[string][3]** CSS property name, eg. 'min-height' + +### Examples + +```javascript +var property = styleManager.getProperty('mySector','min-height'); +``` + +Returns **(Property | null)** + +## removeProperty + +Remove a property from the sector + +### Parameters + +- `sectorId` **[string][3]** Sector id +- `name` **[string][3]** CSS property name, eg. 'min-height' + +### Examples + +```javascript +const property = styleManager.removeProperty('mySector', 'min-height'); +``` + +Returns **Property** Removed property + +## getProperties + +Get properties of the sector + +### Parameters + +- `sectorId` **[string][3]** Sector id + +### Examples + +```javascript +var properties = styleManager.getProperties('mySector'); +``` + +Returns **Properties** Collection of properties + +## getModelToStyle + +Get what to style inside Style Manager. If you select the component +without classes the entity is the Component itself and all changes will +go inside its 'style' property. Otherwise, if the selected component has +one or more classes, the function will return the corresponding CSS Rule + +### Parameters + +- `model` **Model** + +Returns **Model** + +## addType + +Add new property type + +### Parameters + +- `id` **[string][3]** Type ID +- `definition` **[Object][1]** Definition of the type. Each definition contains + `model` (business logic), `view` (presentation logic) + and `isType` function which recognize the type of the + passed entity + addType('my-type', { + model: {}, + view: {}, + isType: (value) => { + if (value && value.type == 'my-type') { + return value; + } + }, + }) + +## getType + +Get type + +### Parameters + +- `id` **[string][3]** Type ID + +Returns **[Object][1]** Type definition + +## getTypes + +Get all types + +Returns **[Array][2]** + +## createType + +Create new property from type + +### Parameters + +- `id` **[string][3]** Type ID +- `options` **[Object][1]** Options (optional, default `{}`) + - `options.model` **[Object][1]** Custom model object (optional, default `{}`) + - `options.view` **[Object][1]** Custom view object (optional, default `{}`) + +### Examples + +```javascript +const propView = styleManager.createType('integer', { + model: {units: ['px', 'rem']} +}); +propView.render(); +propView.model.on('change:value', ...); +someContainer.appendChild(propView.el); +``` + +Returns **PropertyView** + +## render + +Render sectors and properties + +Returns **[HTMLElement][6]** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number + +[6]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/undo_manager.md b/docs/api/undo_manager.md new file mode 100644 index 000000000..aa3af40e6 --- /dev/null +++ b/docs/api/undo_manager.md @@ -0,0 +1,194 @@ + + +## UndoManager + +This module allows to manage the stack of changes applied in canvas + +You can access the module in this way + +```js +const um = editor.UndoManager; +``` + +## getConfig + +Get module configurations + +### Examples + +```javascript +const config = um.getConfig(); +// { ... } +``` + +Returns **[Object][1]** Configuration object + +## add + +Add an entity (Model/Collection) to track +Note: New Components and CSSRules will be added automatically + +### Parameters + +- `entity` **(Model | Collection)** Entity to track + +### Examples + +```javascript +um.add(someModelOrCollection); +``` + +Returns **this** + +## remove + +Remove and stop tracking the entity (Model/Collection) + +### Parameters + +- `entity` **(Model | Collection)** Entity to remove + +### Examples + +```javascript +um.remove(someModelOrCollection); +``` + +Returns **this** + +## removeAll + +Remove all entities + +### Examples + +```javascript +um.removeAll(); +``` + +Returns **this** + +## start + +Start/resume tracking changes + +### Examples + +```javascript +um.start(); +``` + +Returns **this** + +## stop + +Stop tracking changes + +### Examples + +```javascript +um.stop(); +``` + +Returns **this** + +## undo + +Undo last change + +### Examples + +```javascript +um.undo(); +``` + +Returns **this** + +## undoAll + +Undo all changes + +### Examples + +```javascript +um.undoAll(); +``` + +Returns **this** + +## redo + +Redo last change + +### Examples + +```javascript +um.redo(); +``` + +Returns **this** + +## redoAll + +Redo all changes + +### Examples + +```javascript +um.redoAll(); +``` + +Returns **this** + +## hasUndo + +Checks if exists an available undo + +### Examples + +```javascript +um.hasUndo(); +``` + +Returns **[Boolean][2]** + +## hasRedo + +Checks if exists an available redo + +### Examples + +```javascript +um.hasRedo(); +``` + +Returns **[Boolean][2]** + +## getStack + +Get stack of changes + +### Examples + +```javascript +const stack = um.getStack(); +stack.each(item => ...); +``` + +Returns **Collection** + +## clear + +Clear the stack + +### Examples + +```javascript +um.clear(); +``` + +Returns **this** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/package.json b/package.json index 02606daa4..d6f096a5d 100644 --- a/package.json +++ b/package.json @@ -90,6 +90,7 @@ } }, "scripts": { + "docs:api": "node docs/api.js", "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs", "lint": "eslint src",