doc-dev-guides

slate-html-serializer

import Html from 'slate-html-serializer'

The HTML serializer lets you parse and stringify arbitrary HTML content, based on your specific schema's use case. You must pass a series of rules to define how your Slate schema should be serialized to and from HTML.

For an example of the HTML serializer in action, check out the paste-html example.

Example

<p>The Slate editor gives you <em>complete</em> control over the logic you can add.</p>
<p>In its simplest form, when representing plain text, Slate is a glorified <code>&laquo;textarea&raquo;</code>. But you can augment it to be much more than that.</p>
<p>Check out <a href="http://slatejs.org">http://slatejs.org</a> for examples!</p>

Properties

new Html({
  rules: Array,
  defaultBlock: String | Object | Block,
  parseHtml: Function,
})

rules

Array

An array of rules to initialize the HTML serializer with, defining your schema.

defaultBlock

String|Object|Block

A set of properties to use for blocks which do not match any rule. Can be a string such as 'paragraph' or an object with a type attribute such as { type: 'paragraph' }, or even a Block.

parseHtml

Function

A function to parse an HTML string and return a DOM object. Defaults to using the native DOMParser in browser environments that support it. For older browsers or server-side rendering, you can include the jsdom package and pass JSDOM.fragment as the parseHtml option.

This parse function should return the <body> node of the DOM.

Methods

Html.deserialize

Html.deserialize(html: String, [options: Object]) => Value

Deserialize an HTML string into a Value. How the string is deserialized will be determined by the rules that the HTML serializer was constructed with.

If you pass toJSON: true as an option, the return value will be a JSON object instead of a Value object.

Html.serialize

Html.serialize(value: Value, [options: Object]) => String || Array

Serialize a value into an HTML string. How the string is serialized will be determined by the rules that the HTML serializer was constructed with.

If you pass render: false as an option, the return value will instead be an iterable list of the top-level React elements, to be rendered as children in your own React component.

Rules

To initialize an HTML serializer, you must pass it an array of rules, defining your schema. Each rule defines how to deserialize and serialize a node or mark, by implementing two functions.

Each rule must define two properties:

{
  deserialize: Function,
  serialize: Function
}

rule.deserialize

rule.deserialize(el: Element, next: Function) => Object || Void

The deserialize function receives a DOM element and should return a plain Javascript object representing the deserialized value, or nothing if the rule in question doesn't know how to deserialize the object, in which case the next rule in the stack will be attempted.

The object should be one of:

{
  object: 'block',
  type: String,
  data: Object,
  nodes: next(...)
}

{
  object: 'inline',
  type: String,
  data: Object,
  nodes: next(...)
}

{
  object: 'mark',
  type: String,
  data: Object,
  nodes: next(...)
}

{
  object: 'text',
  leaves: Array
}

rule.serialize

rule.serialize(object: Node || Mark || String, children: String || Element || Array) => Element || Void

The serialize function should return a React element representing the serialized HTML, or nothing if the rule in question doesn't know how to serialize the object, in which case the next rule in the stack will be attempted.

The function will be called with either a Node, a Mark, or a special String immutable object, with a object: 'string' property and a text property containing the text string.

Default Text Rule

The HTML serializer includes a default rule to handle "normal text". That is, a final rule exists to serialize object: 'string' text (replacing line feed characters with <br>), and to deserialize text inversely. To avoid this default handling simply provide your own deserialize and serialize rules for text.

PrevioussetEventTransferNextslate-hyperscript

Last updated