mirror of https://github.com/artf/grapesjs.git
Artur Arseniev
8 years ago
14 changed files with 194 additions and 322 deletions
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -0,0 +1,130 @@ |
|||
--- |
|||
title: Commands |
|||
--- |
|||
|
|||
# Commands |
|||
|
|||
A basic command in GrapesJS it's a simple function, but you will see in this guide how powerfull they can be. The main goal of the Command module is to centralize functions and be easily reused across the editor. Another big advantage of using commands is the ability to track them, extend or even interrupt beside some conditions. |
|||
|
|||
::: warning |
|||
This guide is referring to GrapesJS v0.14.59 or higher |
|||
::: |
|||
|
|||
[[toc]] |
|||
|
|||
|
|||
## Basic configuration |
|||
|
|||
You can create your commands already from the initialization by passing them in the `commands.defaults` options: |
|||
|
|||
```js |
|||
const editor = grapesjs.init({ |
|||
... |
|||
commands: { |
|||
defaults: [ |
|||
{ |
|||
// id and run are mandatory in this case |
|||
id: 'my-command-id', |
|||
run() { |
|||
alert('This is my command'); |
|||
}, |
|||
}, { |
|||
id: '...', |
|||
// ... |
|||
} |
|||
], |
|||
} |
|||
}); |
|||
``` |
|||
|
|||
For all other available options check directly the [configuration source file](https://github.com/artf/grapesjs/blob/dev/src/commands/config/config.js). |
|||
|
|||
Most commonly commands are created dynamicly post initialization, in that case you'll need to use the [Commands API](api/commands.html) (eg. this is what you need if you create a plugin) |
|||
|
|||
```js |
|||
const commands = editor.Commands; |
|||
commands.add('my-command-id', editor => { |
|||
alert('This is my command'); |
|||
}); |
|||
|
|||
// or it would be the same... |
|||
commands.add('my-command-id', { |
|||
run(editor) { |
|||
alert('This is my command'); |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
As you see the definiton is quite easy, you just add an ID and the callback function. The [Editor](api/editor.html) instance is passed as the first argument to the callback so you can access any other module or API method. |
|||
|
|||
Now if you want to call that command you should just run this |
|||
|
|||
```js |
|||
editor.runCommand('my-command-id'); |
|||
``` |
|||
|
|||
You could also pass options if you need |
|||
|
|||
```js |
|||
editor.runCommand('my-command-id', { some: 'option' }); |
|||
``` |
|||
|
|||
Then you can get the same object as a third argument of the callback. |
|||
|
|||
```js |
|||
commands.add('my-command-id', (editor, sender, options = {}) => { |
|||
alert(`This is my command ${options.some}`); |
|||
}); |
|||
``` |
|||
|
|||
The second argument, `sender`, just indicates who requested the command, in our case will be always the `editor` |
|||
|
|||
|
|||
Until now there is nothing exiting except a common entry point for functions, but we'll see later its real advantages. |
|||
|
|||
|
|||
|
|||
|
|||
## Default commands |
|||
|
|||
GrapesJS comes along with some default set of commands and you can get a list of all currently availlable commands via `editor.Commands.getAll()`. This will give you an object of all available commands, so, for example, also those added via plugins. You can recognize default commands by their namespace `core:*`, we also recommend to use namepsaces in your own custom commands, but let's get a look more in detail here: |
|||
|
|||
* [`core:canvas-clear`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/CanvasClear.js) - Clear all the content from the canvas (HTML and CSS) |
|||
<!-- * `core:canvas-move` --> |
|||
<!-- * `core:component-drag` --> |
|||
<!-- * `core:component-style-clear` --> |
|||
* [`core:component-delete`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentDelete.js) - Delete a component |
|||
* [`core:component-enter`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentEnter.js) - Select the first children component of the selected one |
|||
* [`core:component-exit`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentExit.js) - Select the parent component of the current selected one |
|||
* [`core:component-next`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentNext.js) - Select the next sibling component |
|||
* [`core:component-prev`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ComponentPrev.js) - Select the previous sibling component |
|||
* [`core:component-outline`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/SwitchVisibility.js) - Enable outline border on components |
|||
* [`core:component-offset`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ShowOffset.js) - Enable components offset (margins, paddings) |
|||
* [`core:component-select`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/SelectComponent.js) - Enable the process of selecting components in the canvas |
|||
* [`core:copy`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/CopyComponent.js) - Copy the current selected component |
|||
* [`core:paste`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/PasteComponent.js) - Paste copied component |
|||
* [`core:preview`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/Preview.js) - Show the preview of the template in canvas |
|||
* [`core:fullscreen`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/Fullscreen.js) - Set the editor fullscreen |
|||
* [`core:open-code`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/ExportTemplate.js) - Open a default panel with the template code |
|||
* [`core:open-layers`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenLayers.js) - Open a default panel with layers |
|||
* [`core:open-styles`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenStyleManager.js) - Open a default panel with the style manager |
|||
* [`core:open-traits`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenTraitManager.js) - Open a default panel with the trait manager |
|||
* [`core:open-blocks`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenBlocks.js) - Open a default panel with the blocks |
|||
* [`core:open-assets`](https://github.com/artf/grapesjs/blob/dev/src/commands/view/OpenAssets.js) - Open a default panel with the assets |
|||
* `core:undo` - Call undo operation |
|||
* `core:redo` - Call redo operation |
|||
|
|||
tlb-clone |
|||
tlb-delete |
|||
tlb-move |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
## Statefull commands |
|||
|
|||
|
|||
|
|||
|
|||
## Events |
|||
@ -1,31 +1,10 @@ |
|||
module.exports = { |
|||
ESCAPE_KEY: 27, |
|||
|
|||
export default { |
|||
stylePrefix: 'com-', |
|||
|
|||
// Default array of commands
|
|||
defaults: [], |
|||
|
|||
// If true, stateful commands (with `run` and `stop` methods) can't be runned multiple times.
|
|||
// So, if the command is already active, running it again will not execute the `run` method
|
|||
strict: 1, |
|||
|
|||
// Editor model
|
|||
// @deprecated
|
|||
em: null, |
|||
|
|||
// If true center new first-level components
|
|||
// @deprecated
|
|||
firstCentered: true, |
|||
|
|||
// If true the new component will created with 'height', else 'min-height'
|
|||
// @deprecated
|
|||
newFixedH: false, |
|||
|
|||
// Minimum height (in px) of new component
|
|||
// @deprecated
|
|||
minComponentH: 50, |
|||
|
|||
// Minimum width (in px) of component on creation
|
|||
// @deprecated
|
|||
minComponentW: 50 |
|||
strict: 1 |
|||
}; |
|||
|
|||
@ -1,232 +0,0 @@ |
|||
import _ from 'underscore'; |
|||
import Backbone from 'backbone'; |
|||
const SelectPosition = require('./SelectPosition'); |
|||
const $ = Backbone.$; |
|||
|
|||
module.exports = _.extend({}, SelectPosition, { |
|||
init(opt) { |
|||
_.bindAll(this, 'startDraw', 'draw', 'endDraw', 'rollback'); |
|||
this.config = opt || {}; |
|||
this.hType = this.config.newFixedH ? 'height' : 'min-height'; |
|||
this.allowDraw = 1; |
|||
}, |
|||
|
|||
/** |
|||
* Start with enabling to select position and listening to start drawing |
|||
* @private |
|||
* */ |
|||
enable(...args) { |
|||
SelectPosition.enable.apply(this, args); |
|||
this.$wr.css('cursor', 'crosshair'); |
|||
if (this.allowDraw) this.$wr.on('mousedown', this.startDraw); |
|||
this.ghost = this.canvas.getGhostEl(); |
|||
}, |
|||
|
|||
/** |
|||
* Start drawing component |
|||
* @param {Object} e Event |
|||
* @private |
|||
* */ |
|||
startDraw(e) { |
|||
e.preventDefault(); |
|||
this.stopSelectPosition(); |
|||
this.ghost.style.display = 'block'; |
|||
this.frameOff = this.getOffsetDim(); |
|||
this.startPos = { |
|||
top: e.pageY + this.frameOff.top, |
|||
left: e.pageX + this.frameOff.left |
|||
}; |
|||
this.isDragged = false; |
|||
this.tempComponent = { style: {} }; |
|||
this.beforeDraw(this.tempComponent); |
|||
this.updateSize(this.startPos.top, this.startPos.left, 0, 0); |
|||
this.toggleEvents(1); |
|||
}, |
|||
|
|||
/** |
|||
* Enable/Disable events |
|||
* @param {Boolean} enable |
|||
*/ |
|||
toggleEvents(enable) { |
|||
var method = enable ? 'on' : 'off'; |
|||
this.$wr[method]('mousemove', this.draw); |
|||
this.$wr[method]('mouseup', this.endDraw); |
|||
this.$canvas[method]('mousemove', this.draw); |
|||
$(document)[method]('mouseup', this.endDraw); |
|||
$(document)[method]('keypress', this.rollback); |
|||
}, |
|||
|
|||
/** |
|||
* While drawing the component |
|||
* @param {Object} e Event |
|||
* @private |
|||
* */ |
|||
draw(e) { |
|||
this.isDragged = true; |
|||
this.updateComponentSize(e); |
|||
}, |
|||
|
|||
/** |
|||
* End drawing component |
|||
* @param {Object} e Event |
|||
* @private |
|||
* */ |
|||
endDraw(e) { |
|||
this.toggleEvents(); |
|||
var model = {}; |
|||
// Only if the mouse was moved
|
|||
if (this.isDragged) { |
|||
this.updateComponentSize(e); |
|||
this.setRequirements(this.tempComponent); |
|||
var lp = this.sorter.lastPos; |
|||
model = this.create( |
|||
this.sorter.target, |
|||
this.tempComponent, |
|||
lp.index, |
|||
lp.method |
|||
); |
|||
this.sorter.prevTarget = null; |
|||
} |
|||
this.ghost.style.display = 'none'; |
|||
this.startSelectPosition(); |
|||
this.afterDraw(model); |
|||
}, |
|||
|
|||
/** |
|||
* Create new component inside the target |
|||
* @param {Object} target Tha target collection |
|||
* @param {Object} component New component to create |
|||
* @param {number} index Index inside the collection, 0 if no children inside |
|||
* @param {string} method Before or after of the children |
|||
* @param {Object} opts Options |
|||
*/ |
|||
create(target, component, index, method, opts) { |
|||
index = method === 'after' ? index + 1 : index; |
|||
var opt = opts || {}; |
|||
var $trg = $(target); |
|||
var trgModel = $trg.data('model'); |
|||
var trgCollection = $trg.data('collection'); |
|||
var droppable = trgModel ? trgModel.get('droppable') : 1; |
|||
opt.at = index; |
|||
if (trgCollection && droppable) return trgCollection.add(component, opt); |
|||
else console.warn('Invalid target position'); |
|||
}, |
|||
|
|||
/** |
|||
* Check and set basic requirements for the component |
|||
* @param {Object} component New component to be created |
|||
* @return {Object} Component updated |
|||
* @private |
|||
* */ |
|||
setRequirements(component) { |
|||
var c = this.config; |
|||
var compStl = component.style; |
|||
// Check min width
|
|||
if (compStl.width.replace(/\D/g, '') < c.minComponentW) |
|||
compStl.width = c.minComponentW + 'px'; |
|||
// Check min height
|
|||
if (compStl[this.hType].replace(/\D/g, '') < c.minComponentH) |
|||
compStl[this.hType] = c.minComponentH + 'px'; |
|||
// Set overflow in case of fixed height
|
|||
if (c.newFixedH) compStl.overflow = 'auto'; |
|||
if (!this.absoluteMode) { |
|||
delete compStl.left; |
|||
delete compStl.top; |
|||
} else compStl.position = 'absolute'; |
|||
var lp = this.sorter.lastPos; |
|||
|
|||
if (this.nearFloat(lp.index, lp.method, this.sorter.lastDims)) |
|||
compStl.float = 'left'; |
|||
|
|||
if ( |
|||
this.config.firstCentered && |
|||
this.getCanvasWrapper() == this.sorter.target |
|||
) { |
|||
compStl.margin = '0 auto'; |
|||
} |
|||
|
|||
return component; |
|||
}, |
|||
|
|||
/** |
|||
* Update new component size while drawing |
|||
* @param {Object} e Event |
|||
* @private |
|||
* */ |
|||
updateComponentSize(e) { |
|||
var y = e.pageY + this.frameOff.top; |
|||
var x = e.pageX + this.frameOff.left; |
|||
var start = this.startPos; |
|||
var top = start.top; |
|||
var left = start.left; |
|||
var height = y - top; |
|||
var width = x - left; |
|||
if (x < left) { |
|||
left = x; |
|||
width = start.left - x; |
|||
} |
|||
if (y < top) { |
|||
top = y; |
|||
height = start.top - y; |
|||
} |
|||
this.updateSize(top, left, width, height); |
|||
}, |
|||
|
|||
/** |
|||
* Update size |
|||
* @private |
|||
*/ |
|||
updateSize(top, left, width, height) { |
|||
var u = 'px'; |
|||
var ghStl = this.ghost.style; |
|||
var compStl = this.tempComponent.style; |
|||
ghStl.top = compStl.top = top + u; |
|||
ghStl.left = compStl.left = left + u; |
|||
ghStl.width = compStl.width = width + u; |
|||
ghStl[this.hType] = compStl[this.hType] = height + u; |
|||
}, |
|||
|
|||
/** |
|||
* Used to bring the previous situation before event started |
|||
* @param {Object} e Event |
|||
* @param {Boolean} forse Indicates if rollback in anycase |
|||
* @private |
|||
* */ |
|||
rollback(e, force) { |
|||
var key = e.which || e.keyCode; |
|||
if (key == this.config.ESCAPE_KEY || force) { |
|||
this.isDragged = false; |
|||
this.endDraw(); |
|||
} |
|||
return; |
|||
}, |
|||
|
|||
/** |
|||
* This event is triggered at the beginning of a draw operation |
|||
* @param {Object} component Object component before creation |
|||
* @private |
|||
* */ |
|||
beforeDraw(component) { |
|||
component.editable = false; //set this component editable
|
|||
}, |
|||
|
|||
/** |
|||
* This event is triggered at the end of a draw operation |
|||
* @param {Object} model Component model created |
|||
* @private |
|||
* */ |
|||
afterDraw(model) {}, |
|||
|
|||
run(editor, sender, opts) { |
|||
this.editor = editor; |
|||
this.sender = sender; |
|||
this.$wr = this.$wrapper; |
|||
this.enable(); |
|||
}, |
|||
|
|||
stop() { |
|||
this.stopSelectPosition(); |
|||
this.$wrapper.css('cursor', ''); |
|||
this.$wrapper.unbind(); |
|||
} |
|||
}); |
|||
@ -1,13 +0,0 @@ |
|||
module.exports = { |
|||
run(editor) { |
|||
const sel = editor.getSelected(); |
|||
let comp = sel && sel.parent(); |
|||
|
|||
// Recurse through the parent() chain until a selectable parent is found
|
|||
while (comp && !comp.get('selectable')) { |
|||
comp = comp.parent(); |
|||
} |
|||
|
|||
comp && editor.select(comp); |
|||
} |
|||
}; |
|||
Loading…
Reference in new issue