Guide for using plugins without UI

[Mangatt]

It would be nice to have guide/docs for using plugins without provided UI. I guess that we are not only one who have specific UX requirements and who would like to take advantage of just parts of this project.

Funding

• You can sponsor this specific effort via a Polar.sh pledge below
• We receive the pledge once the issue is completed & verified

[12joan]

I use Plate with a fully custom UI in my app (https://untitlednote.xyz), and it's pretty simple if you steer clear of the more complex plugins (like tables and mentions).

For the components, you can follow the instructions here: https://platejs.org/docs/plugin-components#defining-components

For building toolbars, here are the main concepts you'll need to be familiar with:

• How to access the editor instance (see https://platejs.org/docs/accessing-editor)
  • useEditorState is best for simplicity
  • a combination of useEditorRef and useEditorSelector is best for performance
• someNode - check if an element type is active in the selection
• toggleNodeType - toggle an element type for the selection
• isMarkActive - check if a mark is active in the selection
• toggleMark - toggle a mark for the selection
• Plugin-specific toggle transforms (for plugins that require them), for example:
  • toggleList
  • toggleCodeBlock

The docs for these functions are available here (https://platejs.org/docs/api/core), but I recommend searching Plate's source code for examples of them.

[Mangatt]

Thank you very much, @12joan, this is very helpful.

Nevertheless, I still think that guide would be very helpful, going through source code with trial/error method is quite time consuming and will not never produce nearly as good results as using this repo as intended by it's authors.

Btw, someNode is undocumented, is it safe to use? Can you give me some hints about options parameter?

[12joan]

You're welcome. I understand your point about a guide, and perhaps we'll get around to writing one at some point.

Regrettably, the API documentation for both Plate and Slate has a tendency to be out of date or lack important context about how functions should be used. In Plate's case, this is because every single function in Plate is technically part of Plate's public API, and there are over 2000 of them. We try our best, but we can't cover everything.

I'm not sure how someNode slipped past our efforts to document these functions, but it is one of the most widely used queries and can be safely relied upon. Most of its options come from Slate's EditorNodesOptions type, except the match option, which comes from Plate's ENodeMatchOptions.

But like I said, an easier way to understand someNode is to see how it's used in Plate's code. Most usages have the following form, which is the most idiomatic way to check for an active node type in the selection.

someNode(editor, {
  match: { type: getPluginType(editor, ELEMENT_TABLE) },
})

Checking the source code in this way is exactly what I do in my work as a Plate consultant, and I've found that it produces consistently good results. I wouldn't describe it as trial and error.

Incidentally, if you ever find yourself wanting to know more about Slate's functions, its best documentation is its tests. The documentation for Slate's liftNodes transform, for example, is vague and not very helpful, and its source code is difficult to understand. But its tests contain 7 examples of how liftNodes affects a document's structure, from which you can deduce what "lifting a node" actually means.