editable.js
What is it about?
A JavaScript API that defines a friendly and browser-consistent content editable interface.
Check out the demo.
It features a formatting toolbar and the default insert, split and merge behavior that allow to add and remove content blocks like paragraphs easily.
Editable is built for block level elements containing only phrasing content. This normally means p
, h1
-h6
, blockquote
etc. elements. This allows editable to be lean and mean since it is only concerned with formatting and not with layouting.
We made editable.js to support our vision of online document editing. Have a look at livingdocs.io.
Installation
Via npm:
npm install --save @livingdocs/editable.js
You can either require('@livingdocs/editable.js')
or find a prebuilt file in the npm bundle dist/editable.js
.
Events Overview
- focus
Fired when an editable element gets focus. - blur
Fired when an editable element loses focus. - selection
Fired when the user selects some text inside an editable element. - cursor
Fired when the cursor position changes. - change
Fired when the user has made a change. - spellcheckUpdated
Fired when the spellcheckService has updated the spellcheck highlights. - clipboard
Fired for copy
, cut
and paste
events. - insert
Fired when the user presses ENTER
at the beginning or end of an editable (For example you can insert a new paragraph after the element if this happens). - split
Fired when the user presses ENTER
in the middle of an element. - merge
Fired when the user pressed FORWARD DELETE
at the end or BACKSPACE
at the beginning of an element. - switch
Fired when the user pressed an ARROW KEY
at the top or bottom so that you may want to set the cursor into the preceding or following element. - newline
Fired when the user presses SHIFT+ENTER
to insert a newline.
How to use
To make an element editable:
const editable = new Editable()
editable.add($elem)
Example for Selection Changes
In a selection
event you get the editable element that triggered the event as well as a selection object. Through the selection object you can get information about the selection like coordinates or the text it contains and you can manipulate the selection.
In the following example we are going to show a toolbar on top of the selection whenever the user has selected something inside of an editable element.
editable.selection((editableElement, selection) => {
if (!selection) return toolbar.hide()
const coords = selection.getCoordinates()
const top = coords.top - toolbar.outerHeight()
const left = coords.left + (coords.width / 2) - (toolbar.outerWidth() / 2)
toolbar.css({top, left}).show()
})
Dive Deeper
We haven't got around to make this documentation comprehensive enough. In the meantime you can find the API methods in src/core.js and the default implementation in src/default-behavior.js.
To find out what you can do with the the editable.js cursor
and selection
objects see src/cursor.js and src/selection.js.
Development
Setup:
npm install
Tasks:
npm start
npm run test:karma
npm run test:watch
npm run test:all
npm run lint
npm run build
License
editable.js is licensed under the MIT License.