# 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() method
  • component:mount - Component is mounted to an element and rendered in canvas
  • component:add - Triggered when a new component is added to the editor, the model is passed as an argument to the callback
  • component:remove - Triggered when a component is removed, the model is passed as an argument to the callback
  • component:remove:before - Triggered before the remove of the component, the model, remove function (if aborted via options, with this function you can complete the remove) and options (use options.abort = true to prevent remove), are passed as arguments to the callback
  • component:clone - Triggered when a component is cloned, the new model is passed as an argument to the callback
  • component:update - Triggered when a component is updated (moved, styled, etc.), the model is passed as an argument to the callback
  • component:update:{propertyName} - Listen any property change, the model is passed as an argument to the callback
  • 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
  • component:type:add - New component type added, the new type is passed as an argument to the callback
  • component:type:update - Component type updated, the updated type is passed as an argument to the callback
  • component:drag:start - Component drag started. Passed an object, to the callback, containing the target (component to drag), parent (parent of the component) and index (component index in the parent)
  • component:drag - During component drag. Passed the same object as in component:drag:start event, but in this case, parent and index are updated by the current pointer
  • component:drag:end - Component drag ended. Passed the same object as in component:drag:start event, but in this case, parent and index are updated by the final pointer

# Methods

# 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

Returns Object (opens new window) Loaded data

# store

Store components on the selected storage

# Parameters

Returns Object (opens new window) Data to store

# 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

# 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

# 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 (opens new window)

# 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

Returns this

# getType

Get component type. Read more about this in Define New Component (opens new window)

# Parameters

Returns Object (opens new window) Component type definition, eg. { model: ..., view: ... }

# removeType

Remove component type

# Parameters

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)