volto-slate API
Contents
volto-slate
API#
The volto-slate
API provides methods to integrate the Slate editor into projects that use Plone's React-based frontend Volto.
Extensions#
An extension in volto-slate
is a function which takes Slate's Editor
object and returns its extended version
This allows a developer to modify and add several functionalities to a Slate Editor
.
For example, to define link elements as inline nodes, we override isInline
from the Editor
object.
export const isInline = (editor) => {
const { isInline } = editor;
editor.isInline = (element) => {
return element && element.type === 'link' ? true : isInline(element);
};
return editor;
};
Plugins#
Plugins are the way to extend the capabilities of volto-slate
by adding extra features to elementEditor.
See the default plugins.
Refer to How to write a Slate editor plugin for how to write your own plugin.
SlateEditor
component#
SlateEditor
is a top-level React component.
It can be directly used in widgets to create a slateJSON
field.
For example, the following snippet creates a rich text SlateEditor
component:
<FormFieldWrapper {...props} draggable={false} className="slate_wysiwyg">
<div
className="slate_wysiwyg_box"
role="textbox"
tabIndex="-1"
onClick={() => {}}
onKeyDown={() => {}}
>
<SlateEditor
className={className}
readOnly={readOnly}
id={id}
name={id}
value={value}
onChange={(newValue) => {
onChange(id, newValue);
}}
block={block}
selected={selected}
properties={properties}
placeholder={placeholder}
/>
</div>
</FormFieldWrapper>
elementEditor
#
The elementEditor is a top-level wrapper of all plugins used in volto-slate
that exposes the plugins API in the form of makeInlineElementPlugin
.
It consists of various modules:
makeInlineElementPlugin
Used to build and install a custom schema based plugin from
volto-slate
API. It expects a set of options passed as a property to your plugin.PluginEditor
Editor component for your Plugin.
ToolbarButton
Custom plugin
ToolbarButton
.
Note
You will get to know more about elementEditor
in How to write a Slate editor plugin.
Serialization#
Serialization is the conversion of Slate JSON data into common formats such as text, HTML, and Markdown.
Common serializers used in volto-slate
are serializeNodes
, serializeNodesToText
, and serializeNodesToHtml
.
Deserialization#
Deserialization is the transformation of arbitrary inputs into a Slate-compatible JSON structure.
volto-slate
uses Slate's own mechanism of deserialization using slate-hyperscript
package.
Deserialization helps control what data comes into Slate per element.
It is called before the editorElement
component for a plugin.
Following is the deserialization method for simpleLink
plugin:
export const simpleLinkDeserializer = (editor, el) => {
let parent = el;
let children = Array.from(parent.childNodes)
.map((el) => deserialize(editor, el))
.flat();
if (!children.length) children = [{ text: '' }];
const attrs = {
type: SIMPLELINK,
data: {
url: el.getAttribute('href'),
},
};
return jsx('element', attrs, children);
};
Normalization#
Normalization ensures that Slate's data is always in its standard form. It is used as a part of the extensions for a particular plugin or a Slate editor itself.
Slate's data model should adhere to constraints provided in Slate's Normalizing documentation.
However, we can customize the functionality to add our own set of conditions by extending the normalizeNode
method of the Slate editor.
For example, remove all img
nodes inside p
nodes.
const removeImgChild = (editor) => {
const { normalizeNode } = editor;
editor.normalizeNode = (entry) => {
const [node, path] = entry;
if (Element.isElement(node) && node.type === 'p') {
for (const [child, childPath] of Node.children(editor, path)) {
if (Element.isElement(child) && child.type === 'img') {
Transforms.removeNodes(editor, { at: childPath });
return;
}
}
}
normalizeNode(entry);
};
return editor;
};