Allow custom serialization in a plugin

[zbeyens]

At the moment, the serialization process just takes a snapshot of renderElement / renderLeaf for each plugin. However, sometimes the desired HTML is not the same than the rendered React element.

Proposition:

• keep the current process as the default serialization
• add a serialize field in the plugin interface, following the same principle than deserialize field.
• if serialize function is provided, it will be used instead of the default serialization.

[danlunde]

took a stab at adding this functionality as it's something we could use ourselves. thoughts or feedback?

[zbeyens]

Will be released in a few days, thanks a lot!

[danlunde]

better documentation would be helpful for sure, but here's a bit of direction that hopefully can help out

that link was broken for me this should work: https://github.com/udecode/slate-plugins/blob/master/packages/slate-plugins/src/serializers/serialize-html/__tests__/with-serialize.spec.ts

you want to add the serialize property with the plugin so that serialize.element or serialize.leaf will take the place of renderElement or renderLeaf respectively when called with serializeHTMLFromNodes

const plugins = [
  {
    ...ImagePlugin(),
    serialize: {
      element: // a react component or function that will ultimately return a react component, examples below
  },
  // more plugins...
]
serializeHTMLFromNodes({ plugins })

now in the test I cheated a little by not checking that the element.type matched the type this plugin is affecting since the test was only testing one plugin and one element. so you'll want to account for that or use the getRenderElement helper method which would also take care of that

also, when serialize.element is called, it provides RenderElementProps which includes element, attributes, and children

the simplest way to serialize an image

serialize: {
  element: ({ element }) => {
    if (element.type === 'img') {
      return <img src={element.url} />
    }
  }
}

using getRenderElement

serialize: {
  element: getRenderElement({ type: 'img', component: MyImageComponent })
}

and MyImageComponent would ideally be the react component you want to serialize that gets the following props element, attributes, children, and additionally htmlAttributes and any optional rootProps that are passed with getRenderElement https://github.com/udecode/slate-plugins/blob/master/packages/slate-plugins/src/common/utils/getRenderElement.tsx#L18-L43

I didn't test any of this code, but hopefully you get the gist

[geordidearns]

@danlunde Wow, thank you 🔥 - I will definitely give this a try tomorrow. Make a lot more sense now calling the serializeHTMLFromNodes after the plugins. I tried to write my own small serializer based on some discussions I saw in the repo regarding it - but failed on the nested part when I took a break 😅

Ahh the getRenderElement takes care of the dom element type? That's nice i'll take a look a bit deeper into the code. Appreciate the help!

[danlunde]

yes, getRenderElement renders the component only when the node element type matches the type passed into getRenderElement

also, in my example I neglected to pass the nodes in the serializeHTMLFromNodes function. in the test case this was simplified to

nodes: [
  {
    type: 'img',
    url: 'https://i.kym-cdn.com/photos/images/original/001/358/546/3fa.jpg',
    children: [],
  },
]

but from the editor you'll want to pass the nodes, likely editor.children along with the plugin. also, the plugins can be the same collection of plugins you provide <EditablePlugins>

serializeHTMLFromNodes({ plugins, nodes: editor.children })

[geordidearns]

hey @danlunde 👋 Sorry for all the Q's just trying to piece everything together 😅

I managed to get it serializing into plain HTML, but I'm curious if I can pass in default styles to the elements at the time of serialization. perhaps with getRenderElement? I saw in this example:

serialize: { element: getRenderElement({ type: 'img', component: MyImageComponent }) }

I could render a custom components - and the one above that:

serialize: { element: ({ element }) => { if (element.type === 'img') { return <img src={element.url} /> } } }

Could i in theory pass inline styles those components? for example <img src={element.url} style="background-color:pink;" /> or is this pattern not suggested for something like this? I currently don't use the getRenderElement so i'm assuming its the reason its being serialized as plain html elements. Want to spice up the html a little 🔥 😂

Thanks again for the help! 🙏

[danlunde]

absolutely, you can render pretty much whatever you want including styles (though I believe you need to pass a javascript object) or even nested jsx

serialize: { element: ({ element }) => { if (element.type === 'img') { return (<div><img src={element.url} style={{ backgroundColor: 'pink' }} /><span className="caption">{element.alt}</span></div>) } } }

getRenderElement is a handy method that says "render this component when the node matches this element type". most slate-plugins uses getRenderElement for its renderElement property implementation, and utilizes the component and rootProps properties it inherits from the plugin defaults. but there's no requirement to utilize that method

in essence, just as renderElement renders a component for view within the slate editor, serialize.element does the same thing but overrides renderElement in the context of serializeHTMLFromNodes