@ithaka/bonsai/documentation/pages/components/text-editor.md

ITHAKA core styling

---
title: Text Editor
description: Rich text editor that emits a 'save' event for the application to handle. Based off of QuillJS
sass: ./scss/_texteditor.scss
js: ./js/bonsai.texteditor.js
---

## How to Use

```html_example
<div id="editor-basic" data-text-editor></div>
```

### Attributes
`data-text-editor` - Places an editor at that position on the page.  
`data-editor-hidden` - Hides the editor, toolbar and save button by default.  
`data-editor-placeholder` - Supplies a custom placeholder text when the editor is empty. "Type something" will be used by default.
`data-help-link` - Displays a help button in the text editor toolbar that links to the url provided.

### JavaScript

#### BonsaiTextEditor.editorFactory
A single invocation of the following JS command will initialize all elements on the page containing the `data-text-editor` attribute.
```
const editors = BonsaiTextEditor.editorFactory();
```

#### BonsaiTextEditor.getEditorById
To get a specific editor from the collection that were instantiated.
```
const editor2 = BonsaiTextEditor.getEditorById(editors, "editor2");
```
 - `editors` - Array of editors that were created by `BonsaiTextEditor.editorFactory`.
 - `"editor2"` - String matching the ID for the editor you wish to locate.

#### toggle
To toggle the editor's visibility.
```
const editor2 = BonsaiTextEditor.getEditorById(editors, "editor2");
editor2.toggle();
```

#### insertEditorContent
To inject HTML into the editor.
```
const editor2 = BonsaiTextEditor.getEditorById(editors, "editor2");
editor2.insertEditorContent(initialText);
```
- `initialText` - HTML string to load into the editor.
<br><br>

### Events

#### save 
The save event can be captured by looking for the following event on the editor element.
```
$("#editor").on("save.bonsai-text-editor", (event, data, html) => {});
```
 - `data` - This is a Quill 'Delta' object pulled from the contents.
   - https://quilljs.com/docs/api/#getcontents  
   - https://quilljs.com/docs/delta/
 - `html` - HTML rendered by the Quill editor that we can display outside the editor to be truly WYSIWYG
 
<hr>

## More Examples

### Custom placeholder text with save event listener

```html_example
<div id="editor" data-text-editor data-editor-placeholder="I'm custom placeholder text"></div>
```

#### JavaScript
```
$("#editor").on("save.bonsai-text-editor", (event, data, html) => {
  alert("Saving editor content." + html);
});
```

<hr> 

### Click to edit with save event listener

```html_example
<div>
    <div id="editor2" data-text-editor data-editor-hidden></div>
    <div id="rendered-content">
        <div id="prebaked-note"><p><strong>Hi there!</strong> Wow. Much notetaking. Very prebaked note.</p></div>
        <button id="edit-button" class="button">Edit</button>
    </div>
</div>
```

#### JavaScript
```
const editor2 = BonsaiTextEditor.getEditorById(editors, "editor2");

$("#editor2").on("save.bonsai-text-editor", (event, data, html) => {
    $("#prebaked-note").html(html);
    $("#rendered-content").toggle();
    editor2.toggle();
});

$("#editor2").on("cancel.bonsai-text-editor", (event) => {
    $("#rendered-content").toggle();
    editor2.toggle();
});

if (editor2 !== undefined) {
    $("#edit-button").on("click", () => {
        editor2.insertEditorContent($("#prebaked-note").html());
        editor2.toggle();
        $("#rendered-content").toggle();
    });
}
```

### Display a custom help link

```html_example
<div>
    <div id="editor4" data-text-editor data-help-link="https://www.google.com"></div>
</div>
```

<hr>

## Accessibility 
1. Attach documentation that details how to interact with the text editor using only keyboard commands on the page the editor is implemented. This can be linked to.
1. All editor controls (e.g., bold, italics, etc.) need to be keyboard navigable and have a clear focus state.
1. If changing the default styling, ensure to maintain a contrast ratio of 4.5:1.
 
## Guidelines
1. Include a mechanism to allow users to save and edit their text.
1. Provide helpful placeholder text that helps the user determine the  purpose of the editor.

## Keyboard Shortcuts

Below are the shortcuts to quickly format the text within the editor.  
<strong>The Mac shortcuts are given below. For windows, please use the `ctrl` key in place of `cmd`. </strong>

`cmd + B` - Bold  
`cmd + I` - Italics  
`cmd + U` - Underline  
`alt + cmd + O` - Ordered list  
`alt + cmd + U` - Unordered list  
`alt + cmd + L` - Insert link  
`alt + cmd + 1` - Small font size  
`alt + cmd + 2` - Normal font  
`alt + cmd + 3` - Large font  
`alt + cmd + 4` - Extra large font