Extensions

locked

Behaviour takes options 0.8 kB gzipped

Blocks that refuse to change.

A contract with clauses nobody may edit and blanks they may; a form letter whose greeting is fixed; a template where the headings stay and the prose beneath them is yours. Every editor makes the whole document editable or none of it, and the gap between those is what this fills.

The lock is an attribute, so it travels with the document, and the guard is a change filter rather than a read-only view: a keystroke, a paste, a drop, a drag and a command that would alter a locked node are all refused the same way, because all of them are changes. Nothing that leaves a locked node exactly as it was is refused — typing beside it, moving it, moving something past it — because nodes are immutable and an untouched node keeps its identity: every locked node of the old document has to be present, as the same object, in the new one. Top-level blocks nothing touched are the same objects too, so their locked nodes come out of a cache and the check costs the blocks that changed.

The lock itself is the one edit a locked node accepts, and undo of a lock is another, so `lock`, `unlock` and history all pass. `setContent` replaces the document rather than editing it and passes too.

1 · Install

One package for every extension · there is no @matrajs/locked to install.

npm i @matrajs/core

2 · Add it to the editor

Import it and put it in the extensions array. That array is the whole feature list: what is not in it is not in your bundle and not in the document's schema.

import { createEditor, document, paragraph, text, locked } from '@matrajs/core'

const editor = createEditor({
  extensions: [document, paragraph, text, locked({ … })],
  element: document.querySelector('#editor'),
})

3 · Use it

Run a command, and give focus back · a click on a button takes it away.

editor.commands.toggleLock()
editor.focus()

Wired to a button:

const button = document.querySelector('#toggleLock')

button.addEventListener('click', () => {
  editor.commands.toggleLock()
  editor.focus()
})

Options

locked is a function · call it with an options object.

Commands

Every one returns true if it changed the document and false if it could not · a command that does not apply where the caret is says so rather than throwing.

Styling

This one needs CSS to look right, and ships the minimum as a string rather than a file · nothing loads unless you load it, and you can ignore it and write your own.

import { lockedCSS } from '@matrajs/core'

const style = document.createElement('style')
style.textContent = lockedCSS
document.head.append(style)

← All 83 extensions

Edit this page on GitHub