grapesjs/docs/api/editor.md

Editor

Editor contains the top level API which you'll probably use to customize the editor or extend it with plugins. You get the Editor instance on init method and you can pass options via its Configuration Object

const editor = grapesjs.init({
   // options
});

Available Events

You can make use of available events in this way

editor.on('EVENT-NAME', (some, argument) => {
   // do something
})

Components

• 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

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:update:target - The target (Component or CSSRule) is changed
• 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 - New selector is add. Passes the new selector as an argument
• selector:remove - Selector removed. Passes the removed selector as an argument
• selector:update - Selector updated. Passes the updated selector as an argument
• selector:state - State changed. Passes the new state value as an argument

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

Modal

• modal:open - Modal is opened
• modal:close - Modal is closed

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);)
• run - Triggered on run of any command. The id and the result are passed as arguments to the callback
• stop - Triggered on stop of any command. The id and the result are passed as arguments to the callback

Devices

Check the Devices module.

Parser

Check the Parser module.

Pages

Check the Pages module.

General

• canvasScroll - Canvas is scrolled
• update - The structure of the template is updated (its HTML/CSS)
• undo - Undo executed
• redo - Redo executed
• load - Editor is loaded

getConfig

Returns configuration object

Parameters

• prop string? Property name

Returns any Returns the configuration object or the value of the specified property

getHtml

Returns HTML built inside canvas

Parameters

• opts Object Options (optional, default {})

  • opts.component Component? Return the HTML of a specific Component
  • opts.cleanId Boolean Remove unnecessary IDs (eg. those created automatically) (optional, default false)

Returns string HTML string

getCss

Returns CSS built inside canvas

Parameters

• opts Object Options (optional, default {})

  • opts.component Component? Return the CSS of a specific Component
  • opts.json Boolean Return an array of CssRules instead of the CSS string (optional, default false)
  • opts.avoidProtected Boolean Don't include protected CSS (optional, default false)

Returns (String | Array<CssRule>) CSS string or array of CssRules

getJs

Returns JS of all components

Parameters

• opts Object Options (optional, default {})

  • opts.component Component? Get the JS of a specific component

Returns String JS string

getComponents

Return the complete tree of components. Use getWrapper to include also the wrapper

Returns Components

getWrapper

Return the wrapper and its all components

Returns Component

setComponents

Set components inside editor's canvas. This method overrides actual components

Parameters

• components (Array<Object> | Object | string) HTML string or components model
• opt Object the options object to be used by the [setComponents]em#setComponents method (optional, default {})

Examples

editor.setComponents('<div class="cls">New component</div>');
// or
editor.setComponents({
 type: 'text',
  classes:['cls'],
  content: 'New component'
});

Returns this

addComponents

Add components

Parameters

• components (Array<Object> | Object | string) HTML string or components model

• opts Object Options

  • opts.avoidUpdateStyle Boolean 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

editor.addComponents('<div class="cls">New component</div>');
// or
editor.addComponents({
 type: 'text',
  classes:['cls'],
  content: 'New component'
});

Returns Array<Component>

getStyle

Returns style in JSON format object

Returns Object

setStyle

Set style inside editor's canvas. This method overrides actual style

Parameters

• style (Array<Object> | Object | string) CSS string or style model
• opt (optional, default {})

Examples

editor.setStyle('.cls{color: red}');
//or
editor.setStyle({
  selectors: ['cls']
  style: { color: 'red' }
});

Returns this

addStyle

Add styles to the editor

Parameters

• style (Array<Object> | Object | string) CSS string or style model
• opts (optional, default {})

Examples

editor.addStyle('.cls{color: red}');

Returns Array<CssRule> Array of created CssRule instances

getSelected

Returns the last selected component, if there is one

Returns Model

getSelectedAll

Returns an array of all selected components

Returns Array

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) Component to select

• opts Object? Options

  • opts.scroll Boolean? Scroll canvas to the selected element

Examples

// Select dropped block
editor.on('block:drag:stop', function(model) {
 editor.select(model);
});

Returns this

selectAdd

Add component to selection

Parameters

• el (Component | HTMLElement | Array) Component to select

Examples

editor.selectAdd(model);

Returns this

selectRemove

Remove component from selection

Parameters

• el (Component | HTMLElement | Array) Component to select

Examples

editor.selectRemove(model);

Returns this

selectToggle

Toggle component selection

Parameters

• el (Component | HTMLElement | Array) Component to select

Examples

editor.selectToggle(model);

Returns this

getEditing

Returns, if active, the Component enabled in rich text editing mode.

Examples

const textComp = editor.getEditing();
if (textComp) {
 console.log('HTML: ', textComp.toHTML());
}

Returns (Component | null)

setDevice

Set device to the editor. If the device exists it will change the canvas to the proper width

Parameters

• name string Name of the device

Examples

editor.setDevice('Tablet');

Returns this

getDevice

Return the actual active device

Examples

var device = editor.getDevice();
console.log(device);
// 'Tablet'

Returns string Device name

runCommand

Execute command

Parameters

• id string Command ID
• options Object Custom options (optional, default {})

Examples

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 Command ID
• options Object Custom options (optional, default {})

Examples

editor.stopCommand('myCommand', {someValue: 1});

Returns any The return is defined by the command

store

Store data to the current storage

Parameters

• clb Function Callback function

Returns Object Stored data

storeData

Get the JSON data object, which could be stored and loaded back with editor.loadData(json)

Examples

console.log(editor.storeData());
// { pages: [...], styles: [...], ... }

Returns Object

load

Load data from the current storage

Parameters

• clb Function Callback function

Returns Object Stored data

loadData

Load data from the JSON data object

Parameters

• data Object Data to load

Examples

editor.loadData({ pages: [...], styles: [...], ... })

Returns Object Loaded object

getContainer

Returns container element. The one which was indicated as 'container' on init method

Returns HTMLElement

getDirtyCount

Return the count of changes made to the content and not yet stored. This count resets at any store()

Returns number

refresh

Update editor dimension offsets

This method could be useful when you update, for example, some position of the editor element (eg. canvas, panels, etc.) with CSS, where without refresh you'll get misleading position of tools

Parameters

• opts

• options Object? Options

  • options.tools Boolean Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default false)

setCustomRte

Replace the built-in Rich Text Editor with a custom one.

Parameters

• obj Object Custom RTE Interface

Examples

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
 }
});

setCustomParserCss

Replace the default CSS parser with a custom one. The parser function receives a CSS string as a parameter and expects an array of CSSRule objects as a result. If you need to remove the custom parser, pass null as the argument

Parameters

• parser (Function | null) Parser function

Examples

editor.setCustomParserCss(css => {
 const result = [];
 // ... parse the CSS string
 result.push({
   selectors: '.someclass, div .otherclass',
   style: { color: 'red' }
 })
 // ...
 return result;
});

Returns this

setDragMode

Change the global drag mode of components. To get more about this feature read: https://github.com/artf/grapesjs/issues/1936

Parameters

• value String Drag mode, options: 'absolute' | 'translate'

Returns this

log

Trigger event log message

Parameters

• msg any Message to log

• opts Object Custom options (optional, default {})

  • opts.ns String Namespace of the log (eg. to use in plugins) (optional, default '')
  • opts.level String Level of the log, debug, info, warning, error (optional, default 'debug')

Examples

editor.log('Something done!', { ns: 'from-plugin-x', level: 'info' });
// This will trigger following events
// `log`, `log:info`, `log-from-plugin-x`, `log-from-plugin-x:info`
// Callbacks of those events will always receive the message and
// options, as arguments, eg:
// editor.on('log:info', (msg, opts) => console.info(msg, opts))

Returns this

t

Translate label

Parameters

• args ...any

• key String Label to translate

• opts Object? Options for the translation

  • opts.params Object? Params for the translation
  • opts.noWarn Boolean? Avoid warnings in case of missing resources

Examples

editor.t('msg');
// use params
editor.t('msg2', { params: { test: 'hello' } });
// custom local
editor.t('msg2', { params: { test: 'hello' }, l: 'it' });

Returns String

on

Attach event

Parameters

• event string Event name
• callback Function Callback function

Returns this

once

Attach event and detach it after the first run

Parameters

• event string Event name
• callback Function Callback function

Returns this

off

Detach event

Parameters

• event string Event name
• callback Function Callback function

Returns this

trigger

Trigger event

Parameters

• event string Event to trigger

Returns this

destroy

Destroy the editor

render

Render editor

Returns HTMLElement

html

Print safe HTML by using ES6 tagged template strings.

Parameters

• literals Array<String>
• substs Array<String>

Examples

const unsafeStr = '<script>....</script>';
const safeStr = '<b>Hello</b>';
// Use `$${var}` to avoid escaping
const strHtml = editor.html`Escaped ${unsafeStr}, unescaped $${safeStr}`;

Returns String