# Components
With this module is possible to manage components inside the canvas. You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object (opens new window)
const editor = grapesjs.init({
domComponents: {
// options
}
})
Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.
// Listen to events
editor.on('component:create', () => { ... });
// Use the API
const cmp = editor.Components;
cmp.addType(...);
# Available Events
component:create
- Component is created (only the model, is not yet mounted in the canvas), called after the init() methodcomponent:mount
- Component is mounted to an element and rendered in canvascomponent:add
- Triggered when a new component is added to the editor, the model is passed as an argument to the callbackcomponent:remove
- Triggered when a component is removed, the model is passed as an argument to the callbackcomponent: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 callbackcomponent:clone
- Triggered when a component is cloned, the new model is passed as an argument to the callbackcomponent:update
- Triggered when a component is updated (moved, styled, etc.), the model is passed as an argument to the callbackcomponent:update:{propertyName}
- Listen any property change, the model is passed as an argument to the callbackcomponent:styleUpdate
- Triggered when the style of the component is updated, the model is passed as an argument to the callbackcomponent:styleUpdate:{propertyName}
- Listen for a specific style property change, the model is passed as an argument to the callbackcomponent:selected
- New component selected, the selected model is passed as an argument to the callbackcomponent:deselected
- Component deselected, the deselected model is passed as an argument to the callbackcomponent:toggled
- Component selection changed, toggled model is passed as an argument to the callbackcomponent:type:add
- New component type added, the new type is passed as an argument to the callbackcomponent:type:update
- Component type updated, the updated type is passed as an argument to the callbackcomponent:drag:start
- Component drag started. Passed an object, to the callback, containing thetarget
(component to drag),parent
(parent of the component) andindex
(component index in the parent)component:drag
- During component drag. Passed the same object as incomponent:drag:start
event, but in this case,parent
andindex
are updated by the current pointercomponent:drag:end
- Component drag ended. Passed the same object as incomponent:drag:start
event, but in this case,parent
andindex
are updated by the final pointercomponent:resize
- During component resize.
# Methods
# getWrapper
Returns root component inside the canvas. Something like <body>
inside HTML page
The wrapper doesn't differ from the original Component Model
# Examples
// Change background of the wrapper and set some attribute
var wrapper = cmp.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
// Let's add some component
var wrapperChildren = cmp.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 'cmp.getComponents().add(...)'
# Parameters
component
(Object (opens new window) | Component | Array (opens new window)<Object (opens new window)>) Component/s to addcomponent.tagName
string (opens new window) Tag name (optional, default'div'
)component.type
string (opens new window) Type of the component. Available: ''(default), 'text', 'image' (optional, default''
)component.removable
boolean (opens new window) If component is removable (optional, defaulttrue
)component.draggable
boolean (opens new window) If is possible to move the component around the structure (optional, defaulttrue
)component.droppable
boolean (opens new window) If is possible to drop inside other components (optional, defaulttrue
)component.badgable
boolean (opens new window) If the badge is visible when the component is selected (optional, defaulttrue
)component.stylable
boolean (opens new window) If is possible to style component (optional, defaulttrue
)component.copyable
boolean (opens new window) If is possible to copy&paste the component (optional, defaulttrue
)component.content
string (opens new window) String inside component (optional, default''
)component.style
Object (opens new window) Style object (optional, default{}
)component.attributes
Object (opens new window) Attribute object (optional, default{}
)
opt
Object (opens new window) the options object to be used by the [Components.add]getComponents method (optional, default{}
)
# Examples
// Example of a new component with some extra property
var comp1 = cmp.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 (opens new window)<Component>) Component/s added
# clear
Remove all components
# Parameters
opts
(optional, default{}
)
Returns this
# addType
Add new component type. Read more about this in Define New Component (opens new window)
# Parameters
type
string (opens new window) Component IDmethods
Object (opens new window) Component methods
Returns this
# getType
Get component type. Read more about this in Define New Component (opens new window)
# Parameters
type
string (opens new window) Component ID
Returns Object (opens new window) Component type definition, eg. { model: ..., view: ... }
# removeType
Remove component type
# Parameters
id
string (opens new window)type
string (opens new window) Component ID
Returns (Object (opens new window) | undefined (opens new window)) Removed component type, undefined otherwise
# getTypes
Return the array of all types
Returns Array (opens new window)
# isComponent
Check if the object is a [Component].
# Parameters
# Examples
cmp.isComponent(editor.getSelected()); // true
cmp.isComponent({}); // false
Returns Boolean (opens new window)
# addSymbol
Add a new symbol from a component. If the passed component is not a symbol, it will be converted to an instance and will return the main symbol. If the passed component is already an instance, a new instance will be created and returned. If the passed component is the main symbol, a new instance will be created and returned.
# Parameters
component
Component Component from which create a symbol.
# Examples
const symbol = cmp.addSymbol(editor.getSelected());
// cmp.getSymbolInfo(symbol).isSymbol === true;
Returns Component
# getSymbols
Get the array of main symbols.
# Examples
const symbols = cmp.getSymbols();
// [Component, Component, ...]
// Removing the main symbol will detach all the relative instances.
symbols[0].remove();
Returns Array (opens new window)<Component>
# detachSymbol
Detach symbol instance from the main one. The passed symbol instance will become a regular component.
# Parameters
component
Component The component symbol to detach.
# Examples
const cmpInstance = editor.getSelected();
// cmp.getSymbolInfo(cmpInstance).isInstance === true;
cmp.detachSymbol(cmpInstance);
// cmp.getSymbolInfo(cmpInstance).isInstance === false;
# getSymbolInfo
Get info about the symbol.
# Parameters
component
Component Component symbol from which to get the info.opts
{withChanges: string (opens new window)?} (optional, default{}
)
# Examples
cmp.getSymbolInfo(editor.getSelected());
// > { isSymbol: true, isMain: false, isInstance: true, ... }
Returns Object (opens new window) Object containing symbol info.
# canMove
Check if a component can be moved inside another one.
# Parameters
target
Component The target component is the one that is supposed to receive the source one.source
(Component | String (opens new window)) The source can be another component, a component definition or an HTML string.index
Number (opens new window)? Index position, if not specified, the check will be performed against appending the source to the target.
# Examples
const rootComponent = editor.getWrapper();
const someComponent = editor.getSelected();
// Check with two components
editor.Components.canMove(rootComponent, someComponent);
// Check with component definition
editor.Components.canMove(rootComponent, { tagName: 'a', draggable: false });
// Check with HTML string
editor.Components.canMove(rootComponent, '<form>...</form>');
Returns Object (opens new window) Object containing the result
(Boolean), source
, target
(as Components), and a reason
(Number) with these meanings:* 0
- Invalid source. This is a default value and should be ignored in case the result
is true.
1
- Source doesn't accept target as destination.2
- Target doesn't accept source.