tiptap/docs/guide/node-views.md

137 lines
7.0 KiB
Markdown
Raw Normal View History

---
tableOfContents: true
---
2021-03-09 18:55:14 +08:00
# Interactive node views
2020-11-06 23:25:46 +08:00
## Introduction
2021-06-23 03:28:20 +08:00
Node views are the best thing since sliced bread, at least if you are a fan of customization (and bread). With node views you can add interactive nodes to your editor. That can literally be everything. If you can write it in JavaScript, you can use it in your editor.
Node views are amazing to improve the in-editor experience, but can also be used in a read-only instance of tiptap. They are unrelated to the HTML output by design, so you have full control about the in-editor experience *and* the output.
2020-11-28 00:25:32 +08:00
2020-11-30 22:33:20 +08:00
## Different types of node views
2021-03-11 07:47:28 +08:00
Depending on what you would like to build, node views work a little bit different and can have their verify specific capabilities, but also pitfalls. The main question is: How should your custom node look like?
2021-03-11 04:52:32 +08:00
### Editable text
2021-03-19 04:58:23 +08:00
Yes, node views can have editable text, just like a regular node. Thats simple. The cursor will exactly behave like you would expect it from a regular node. Existing commands work very well with those nodes.
2020-11-30 22:33:20 +08:00
2020-11-28 00:25:01 +08:00
```html
<div class="Prosemirror" contenteditable="true">
<p>text</p>
<node-view>text</node-view>
<p>text</p>
</div>
```
2021-03-11 04:52:32 +08:00
Thats how the [`TaskItem`](/api/nodes/task-item) node works.
### Non-editable text
2021-08-08 15:16:22 +08:00
Nodes can also have text, which is not editable. The cursor cant jump into those, but you dont want that anyway.
2021-03-11 04:52:32 +08:00
2021-03-19 04:58:23 +08:00
tiptap adds a `contenteditable="false"` to those by default.
2021-03-11 04:52:32 +08:00
2020-11-28 00:25:01 +08:00
```html
<div class="Prosemirror" contenteditable="true">
<p>text</p>
<node-view contenteditable="false">text</node-view>
<p>text</p>
</div>
```
2021-03-11 04:52:32 +08:00
Thats how you could render mentions, which shouldnt be editable. Users can add or delete them, but not delete single characters.
Statamic uses those for their Bard editor, which renders complex modules inside tiptap, which can have their own text inputs.
2021-03-10 04:54:16 +08:00
### Mixed content
You can even mix non-editable and editable text. Thats great to build complex things, and still use marks like bold and italic inside the editable content.
2021-03-09 01:33:50 +08:00
**BUT**, if there are other elements with non-editable text in your node view, the cursor can jump there. You can improve that with manually adding `contenteditable="false"` to the specific parts of your node view.
2021-03-11 04:52:32 +08:00
```html
<div class="Prosemirror" contenteditable="true">
<p>text</p>
2021-03-19 04:58:23 +08:00
<node-view>
<div contenteditable="false">
2021-03-11 04:52:32 +08:00
non-editable text
</div>
2021-03-19 04:58:23 +08:00
<div>
2021-03-11 04:52:32 +08:00
editable text
</div>
</node-view>
<p>text</p>
</div>
```
## Markup
2021-04-07 05:36:07 +08:00
But what happens if you [access the editor content](/guide/output)? If youre working with HTML, youll need to tell tiptap how your node should be serialized.
2021-03-31 03:53:29 +08:00
The editor **does not** export the rendered JavaScript node, and for a lot of use cases you wouldnt want that anyway.
Lets say you have a node view which lets users add a video player and configure the appearance (autoplay, controls …). You want the interface to do that in the editor, not in the output of the editor. The output of the editor should probably only have the video player.
I know, I know, its not that easy. Just keep in mind, that youre in full control of the rendering inside the editor and of the output.
:::warning What if you store JSON?
2021-06-23 03:28:20 +08:00
That doesnt apply to JSON. In JSON, everything is stored as an object. There is no need to configure the “translation” to and from HTML.
2021-03-31 03:53:29 +08:00
:::
### Render HTML
2021-03-31 03:53:29 +08:00
Okay, youve set up your node with an interactive node view and now you want to control the output. Even if youre node view is pretty complex, the rendered HTML can be simple:
2021-03-19 04:58:23 +08:00
```js
renderHTML({ HTMLAttributes }) {
2021-03-31 03:53:29 +08:00
return ['my-custom-node', mergeAttributes(HTMLAttributes)]
2021-03-19 04:58:23 +08:00
},
2021-03-31 03:53:29 +08:00
// Output: <my-custom-node count="1"></my-custom-node>
2021-03-19 04:58:23 +08:00
```
2021-03-31 03:53:29 +08:00
Make sure its something distinguishable, so its easier to restore the content from the HTML. If you just need something generic markup like a `<div>` consider to add a `data-type="my-custom-node"`.
### Parse HTML
2021-03-31 03:53:29 +08:00
The same applies to restoring the content. You can configure what markup you expect, that can be something completely unrelated to the node view markup. It just needs to contain all the information you want to restore.
2021-05-05 05:59:34 +08:00
Attributes are automagically restored, if you registered them through [`addAttributes`](/guide/custom-extensions#attributes).
2021-03-31 03:53:29 +08:00
2021-03-10 04:54:16 +08:00
```js
2021-03-31 03:53:29 +08:00
// Input: <my-custom-node count="1"></my-custom-node>
2021-03-10 04:54:16 +08:00
parseHTML() {
return [{
2021-03-31 03:53:29 +08:00
tag: 'my-custom-node',
2021-03-10 04:54:16 +08:00
}]
},
```
2021-03-31 03:53:29 +08:00
### Render JavaScript/Vue/React
But what if you want to render your actual JavaScript/Vue/React code? Consider using tiptap to render your output. Just set the editor to `editable: false` and no one will notice youre using an editor to render the content. :-)
<!-- ## Reference
2021-02-11 23:08:58 +08:00
### dom: ?dom.Node
> The outer DOM node that represents the document node. When not given, the default strategy is used to create a DOM node.
### contentDOM: ?dom.Node
> The DOM node that should hold the node's content. Only meaningful if the node view also defines a dom property and if its node type is not a leaf node type. When this is present, ProseMirror will take care of rendering the node's children into it. When it is not present, the node view itself is responsible for rendering (or deciding not to render) its child nodes.
### update: ?fn(node: Node, decorations: [Decoration]) → bool
> When given, this will be called when the view is updating itself. It will be given a node (possibly of a different type), and an array of active decorations (which are automatically drawn, and the node view may ignore if it isn't interested in them), and should return true if it was able to update to that node, and false otherwise. If the node view has a contentDOM property (or no dom property), updating its child nodes will be handled by ProseMirror.
### selectNode: ?fn()
> Can be used to override the way the node's selected status (as a node selection) is displayed.
### deselectNode: ?fn()
> When defining a selectNode method, you should also provide a deselectNode method to remove the effect again.
### setSelection: ?fn(anchor: number, head: number, root: dom.Document)
> This will be called to handle setting the selection inside the node. The anchor and head positions are relative to the start of the node. By default, a DOM selection will be created between the DOM positions corresponding to those positions, but if you override it you can do something else.
### stopEvent: ?fn(event: dom.Event) → bool
> Can be used to prevent the editor view from trying to handle some or all DOM events that bubble up from the node view. Events for which this returns true are not handled by the editor.
### ignoreMutation: ?fn(dom.MutationRecord) → bool
> Called when a DOM mutation or a selection change happens within the view. When the change is a selection change, the record will have a type property of "selection" (which doesn't occur for native mutation records). Return false if the editor should re-read the selection or re-parse the range around the mutation, true if it can safely be ignored.
### destroy: ?fn()
2021-03-31 03:53:29 +08:00
> Called when the node view is removed from the editor or the whole editor is destroyed. -->