## RichTextEditor
This module allows to customize the built-in toolbar of the Rich Text Editor and use commands from the [HTML Editing APIs][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
You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][2]
```js
const editor = grapesjs.init({
richTextEditor: {
// options
}
})
```
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance.
```js
const rte = editor.RichTextEditor;
```
## Available Events
* `rte:enable` RTE enabled. The view, on which RTE is enabled, and the RTE instance are passed as arguments.
```javascript
editor.on('rte:enable', (view, rte) => { ... });
```
* `rte:disable` RTE disabled. The view, on which RTE is disabled, and the RTE instance are passed as arguments.
```javascript
editor.on('rte:disable', (view, rte) => { ... });
```
* `rte:custom` Custom RTE event. Object with enabled status, container, and actions is passed as an argument.
```javascript
editor.on('rte:custom', ({ enabled, container, actions }) => { ... });
```
## Methods
* [add][3]
* [get][4]
* [run][5]
* [getAll][6]
* [remove][7]
* [getToolbarEl][8]
## getConfig
Get configuration object
Returns **[Object][9]**
## add
Add a new action to the built-in RTE toolbar
### Parameters
* `name` **[string][10]** Action name
* `action` **[Object][9]** 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 how to wrap 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;
}
}
})
// An example with state
const isValidAnchor = (rte) => {
// a utility function to help determine if the selected is a valid anchor node
const anchor = rte.selection().anchorNode;
const parentNode = anchor && anchor.parentNode;
const nextSibling = anchor && anchor.nextSibling;
return (parentNode && parentNode.nodeName == 'A') || (nextSibling && nextSibling.nodeName == 'A')
}
rte.add('toggleAnchor', {
icon: `⫘`,
state: (rte, doc) => {
if (rte && rte.selection()) {
// `btnState` is a integer, -1 for disabled, 0 for inactive, 1 for active
return isValidAnchor(rte) ? btnState.ACTIVE : btnState.INACTIVE;
} else {
return btnState.INACTIVE;
}
},
result: (rte, action) => {
if (isValidAnchor(rte)) {
rte.exec('unlink');
} else {
rte.insertHTML(`${rte.selection()}`);
}
}
})
```
## get
Get the action by its name
### Parameters
* `name` **[string][10]** Action name
### Examples
```javascript
const action = rte.get('bold');
// {name: 'bold', ...}
```
Returns **[Object][9]**
## getAll
Get all actions
Returns **[Array][11]**
## remove
Remove the action from the toolbar
### Parameters
* `name` **[string][10]**
### Examples
```javascript
const action = rte.remove('bold');
// {name: 'bold', ...}
```
Returns **[Object][9]** Removed action
## run
Run action command.
### Parameters
* `action` **([string][10] | RichTextEditorAction)** Action to run
### Examples
```javascript
const action = rte.get('bold');
rte.run(action) // or rte.run('bold')
```
## getToolbarEl
Get the toolbar element
Returns **[HTMLElement][12]**
[1]: https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand
[2]: https://github.com/GrapesJS/grapesjs/blob/master/src/rich_text_editor/config/config.ts
[3]: #add
[4]: #get
[5]: #run
[6]: #getall
[7]: #remove
[8]: #gettoolbarel
[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[12]: https://developer.mozilla.org/docs/Web/HTML/Element