Extensions

embed

Node takes options 1.04 kB gzipped

Anything with an embed page, in a frame.

The frame is the dangerous part of a document, so the allowlist is not optional: a `src` is checked when a command sets it, when HTML is parsed, and again when the node renders — because a document loaded from JSON skipped the first two, and that is how every real application loads documents. A frame that fails the check at render time is withheld and the wrapper stays, so the document keeps its data and fetches nothing.

Every frame is sandboxed. Scripts and same-origin are allowed because most embed pages stop working without them; navigating the top page is not.

1 · Install

One package for every extension · there is no @matrajs/embed 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, embed } from '@matrajs/core'

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

3 · Use it

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

editor.commands.insertEmbed('https://example.com/media')
editor.focus()

Wired to a button, with the pressed state kept in step:

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

button.addEventListener('click', () => {
  editor.commands.insertEmbed('https://example.com/media')
  editor.focus()
})

const read = () => button.setAttribute('aria-pressed', String(editor.isActive('embed')))
editor.on('selectionChange', read)
editor.on('change', read)
read()

Options

embed 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 { embedCSS } from '@matrajs/core'

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

In the document

• Reads div[data-embed]iframe[src] when HTML is pasted or loaded.
• Writes div in getHTML() and renderToHTML().

← All 83 extensions

Edit this page on GitHub