From 692f7b474f695fd8c40cbf03d24d8b3c285c2a90 Mon Sep 17 00:00:00 2001 From: Brian Bucknam Date: Tue, 19 Sep 2017 08:13:36 -0700 Subject: [PATCH] Add more details about slate-html-serializer (#1139) * Add more details about slate-html-serializer * Update index.md --- docs/reference/slate-html-serializer/index.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/reference/slate-html-serializer/index.md b/docs/reference/slate-html-serializer/index.md index 72a72a57c..a22341619 100644 --- a/docs/reference/slate-html-serializer/index.md +++ b/docs/reference/slate-html-serializer/index.md @@ -35,7 +35,9 @@ For an example of the HTML serializer in action, check out the [`paste-html` exa ```js new Html({ - rules: Array + rules: Array, + defaultBlock: String|Object|Block, + parseHtml: Function, }) ``` @@ -54,6 +56,8 @@ A set of properties to use for blocks which do not match any rule. Can be a stri 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 [parse5](https://www.npmjs.com/package/parse5) package and pass `parse5.parseFragment` as the `parseHtml` option. +This parse function should return the `` node of the DOM. + ## Methods ### `Html.deserialize` @@ -66,7 +70,7 @@ If you pass `toJSON: true` as an option, the return value will be a JSON object ### `Html.serialize` `Html.serialize(state: State, [options: Object]) => String || Array` -Serialize a `state` into an HTML string. How the string is serialized will be determined by the rules that the HTML serializer was constructed with. +Serialize a `state` 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. @@ -85,7 +89,7 @@ Each rule must define two properties: ``` -#### `rule.deserialize` +### `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 state, 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. @@ -121,9 +125,13 @@ The object should be one of: ``` -#### `rule.serialize` +### `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 `kind: '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 `kind: 'string'` text (replacing line feed characters with `
`), and to deserialize text inversely. To avoid this default handling simply provide your own `deserialize` and `serialize` rules for text.