remove gridsome
This commit is contained in:
Philipp Kühn
29
docs/guide/node-views/examples.md
Normal file
29
docs/guide/node-views/examples.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
tableOfContents: true
|
||||
---
|
||||
|
||||
# Examples
|
||||
|
||||
## toc
|
||||
|
||||
## Introduction
|
||||
Node views enable you to fully customize your nodes. We are collecting a few different examples here. Feel free to copy them and start building on them.
|
||||
|
||||
Keep in mind that those are just examples to get you started, not officially supported extensions. We don’t have tests for them, and don’t plan to maintain them with the same attention as we do with official extensions.
|
||||
|
||||
## Drag handles
|
||||
Drag handles aren’t that easy to add. We are still on the lookout what’s the best way to add them. Official support will come at some point, but there’s no timeline yet.
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/DragHandle"></tiptap-demo>
|
||||
|
||||
## Table of contents
|
||||
This one loops through the editor content, gives all headings an ID and renders a Table of Contents with Vue.
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/TableOfContents"></tiptap-demo>
|
||||
|
||||
## Drawing in the editor
|
||||
The drawing example shows a SVG that enables you to draw inside the editor.
|
||||
|
||||
<tiptap-demo name="Examples/Drawing"></tiptap-demo>
|
||||
|
||||
It’s not working very well with the Collaboration extension. It’s sending all data on every change, which can get pretty huge with Y.js. If you plan to use those two in combination, you need to improve it or your WebSocket backend will melt.
|
||||
125
docs/guide/node-views/js.md
Normal file
125
docs/guide/node-views/js.md
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
tableOfContents: true
|
||||
---
|
||||
|
||||
# Node views with JavaScript
|
||||
|
||||
## toc
|
||||
|
||||
## Introduction
|
||||
Using frameworks like Vue or React can feel too complex, if you’re used to work without those two. Good news: You can use Vanilla JavaScript in your node views. There is just a little bit you need to know, but let’s go through this one by one.
|
||||
|
||||
## Render a node view with JavaScript
|
||||
Here is what you need to do to render a node view inside your editor:
|
||||
|
||||
1. [Create a node extension](/guide/custom-extensions)
|
||||
2. Register a new node view with `addNodeView()`
|
||||
3. Write your render function
|
||||
4. [Configure tiptap to use your new node extension](/guide/configuration)
|
||||
|
||||
This is how your node extension could look like:
|
||||
|
||||
```js
|
||||
import { Node } from '@tiptap/core'
|
||||
import Component from './Component.vue'
|
||||
|
||||
export default Node.create({
|
||||
// configuration …
|
||||
|
||||
addNodeView() {
|
||||
return ({ editor, node, getPos, HTMLAttributes, decorations, extension }) => {
|
||||
const dom = document.createElement('div')
|
||||
|
||||
dom.innerHTML = 'Hello, I’m a node view!'
|
||||
|
||||
return {
|
||||
dom,
|
||||
}
|
||||
}
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Got it? Let’s see it in action. Feel free to copy the below example to get started.
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/JavaScript"></tiptap-demo>
|
||||
|
||||
That node view even interacts with the editor. Time to see how that is wired up.
|
||||
|
||||
## Access node attributes
|
||||
The editor passes a few helpful things to your render function. One of them is the the `node` prop. This one enables you to access node attributes in your node view. Let’s say you have [added an attribute](/guide/custom-extensions#attributes) named `count` to your node extension. You could access the attribute like this:
|
||||
|
||||
```js
|
||||
addNodeView() {
|
||||
return ({ node }) => {
|
||||
console.log(node.attrs.count)
|
||||
|
||||
// …
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Update node attributes
|
||||
You can even update node attributes from your node view, with the help of the `getPos` prop passed to your render function. Dispatch a new transaction with an object of the updated attributes:
|
||||
|
||||
```js
|
||||
addNodeView() {
|
||||
return ({ editor, node, getPos }) => {
|
||||
const { view } = editor
|
||||
|
||||
// Create a button …
|
||||
const button = document.createElement('button')
|
||||
button.innerHTML = `This button has been clicked ${node.attrs.count} times.`
|
||||
|
||||
// … and when it’s clicked …
|
||||
button.addEventListener('click', () => {
|
||||
if (typeof getPos === 'function') {
|
||||
// … dispatch a transaction, for the current position in the document …
|
||||
view.dispatch(view.state.tr.setNodeMarkup(getPos(), undefined, {
|
||||
count: node.attrs.count + 1,
|
||||
}))
|
||||
|
||||
// … and set the focus back to the editor.
|
||||
editor.commands.focus()
|
||||
}
|
||||
})
|
||||
|
||||
// …
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Does seem a little bit too complex? Consider using [React](/guide/node-views/react) or [Vue](/guide/node-views/vue), if you have one of those in your project anyway. It get’s a little bit easier with those two.
|
||||
|
||||
## Adding a content editable
|
||||
To add editable content to your node view, you need to pass a `contentDOM`, a container element for the content. Here is a simplified version of a node view with non-editable and editable text content:
|
||||
|
||||
```js
|
||||
// Create a container for the node view
|
||||
const dom = document.createElement('div')
|
||||
|
||||
// Give other elements containing text `contentEditable = false`
|
||||
const label = document.createElement('span')
|
||||
label.innerHTML = 'Node view'
|
||||
label.contentEditable = false
|
||||
|
||||
// Create a container for the content
|
||||
const content = document.createElement('div')
|
||||
|
||||
// Append all elements to the node view container
|
||||
dom.append(label, content)
|
||||
|
||||
return {
|
||||
// Pass the node view container …
|
||||
dom,
|
||||
// … and the content container:
|
||||
contentDOM: content,
|
||||
}
|
||||
```
|
||||
|
||||
Got it? You’re free to do anything you like, as long as you return a container for the node view and another one for the content. Here is the above example in action:
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/JavaScriptContent"></tiptap-demo>
|
||||
|
||||
Keep in mind that this content is rendered by tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
|
||||
118
docs/guide/node-views/react.md
Normal file
118
docs/guide/node-views/react.md
Normal file
@@ -0,0 +1,118 @@
|
||||
---
|
||||
tableOfContents: true
|
||||
---
|
||||
|
||||
# Node views with React
|
||||
|
||||
## toc
|
||||
|
||||
## Introduction
|
||||
Using Vanilla JavaScript can feel complex if you are used to work in React. Good news: You can use regular React components in your node views, too. There is just a little bit you need to know, but let’s go through this one by one.
|
||||
|
||||
## Render a React component
|
||||
Here is what you need to do to render React components inside your editor:
|
||||
|
||||
1. [Create a node extension](/guide/custom-extensions)
|
||||
2. Create a React component
|
||||
3. Pass that component to the provided `ReactNodeViewRenderer`
|
||||
4. Register it with `addNodeView()`
|
||||
5. [Configure tiptap to use your new node extension](/guide/configuration)
|
||||
|
||||
This is how your node extension could look like:
|
||||
|
||||
```js
|
||||
import { Node } from '@tiptap/core'
|
||||
import { ReactNodeViewRenderer } from '@tiptap/react'
|
||||
import Component from './Component.jsx'
|
||||
|
||||
export default Node.create({
|
||||
// configuration …
|
||||
|
||||
addNodeView() {
|
||||
return ReactNodeViewRenderer(Component)
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
There is a little bit of magic required to make this work. But don’t worry, we provide a wrapper component you can use to get started easily. Don’t forget to add it to your custom React component, like shown below:
|
||||
|
||||
```html
|
||||
<NodeViewWrapper className="react-component">
|
||||
React Component
|
||||
</NodeViewWrapper>
|
||||
```
|
||||
|
||||
Got it? Let’s see it in action. Feel free to copy the below example to get started.
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/ReactComponent"></tiptap-demo>
|
||||
|
||||
That component doesn’t interact with the editor, though. Time to wire it up.
|
||||
|
||||
## Access node attributes
|
||||
The `ReactNodeViewRenderer` which you use in your node extension, passes a few very helpful props to your custom React component. One of them is the `node` prop. Let’s say you have [added an attribute](/guide/custom-extensions#attributes) named `count` to your node extension (like we did in the above example) you could access it like this:
|
||||
|
||||
```js
|
||||
props.node.attrs.count
|
||||
```
|
||||
|
||||
## Update node attributes
|
||||
You can even update node attributes from your node, with the help of the `updateAttributes` prop passed to your component. Pass an object with updated attributes to the `updateAttributes` prop:
|
||||
|
||||
```js
|
||||
export default props => {
|
||||
const increase = () => {
|
||||
props.updateAttributes({
|
||||
count: props.node.attrs.count + 1,
|
||||
})
|
||||
}
|
||||
|
||||
// …
|
||||
}
|
||||
```
|
||||
|
||||
And yes, all of that is reactive, too. A pretty seemless communication, isn’t it?
|
||||
|
||||
## Adding a content editable
|
||||
There is another component called `NodeViewContent` which helps you adding editable content to your node view. Here is an example:
|
||||
|
||||
```jsx
|
||||
import React from 'react'
|
||||
import { NodeViewWrapper, NodeViewContent } from '@tiptap/react'
|
||||
|
||||
export default () => {
|
||||
return (
|
||||
<NodeViewWrapper className="react-component-with-content">
|
||||
<span className="label" contentEditable={false}>React Component</span>
|
||||
|
||||
<NodeViewContent className="content" />
|
||||
</NodeViewWrapper>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
You don’t need to add those `className` attributes, feel free to remove them or pass other class names. Try it out in the following example:
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/ReactComponentContent"></tiptap-demo>
|
||||
|
||||
Keep in mind that this content is rendered by tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
|
||||
|
||||
The `NodeViewWrapper` and `NodeViewContent` components render a `<div>` HTML tag (`<span>` for inline nodes), but you can change that. For example `<NodeViewContent as="p">` should render a paragraph. One limitation though: That tag must not change during runtime.
|
||||
|
||||
## All available props
|
||||
Here is the full list of what props you can expect:
|
||||
|
||||
| Prop | Description |
|
||||
| ------------------ | --------------------------------------------------------------- |
|
||||
| `editor` | The editor instance |
|
||||
| `node` | The current node |
|
||||
| `decorations` | An array of decorations |
|
||||
| `selected` | `true` when there is a `NodeSelection` at the current node view |
|
||||
| `extension` | Access to the node extension, for example to get options |
|
||||
| `getPos` | Get the document position of the current node |
|
||||
| `updateAttributes` | Update attributes of the current node |
|
||||
| `deleteNode` | Delete the current node |
|
||||
|
||||
## Dragging
|
||||
To make your node views draggable, set `draggable: true` in the extension and add `data-drag-handle` to the DOM element that should function as the drag handle.
|
||||
|
||||
<!-- <tiptap-demo name="GuideNodeViews/DragHandle"></tiptap-demo> -->
|
||||
205
docs/guide/node-views/vue.md
Normal file
205
docs/guide/node-views/vue.md
Normal file
@@ -0,0 +1,205 @@
|
||||
---
|
||||
tableOfContents: true
|
||||
---
|
||||
|
||||
# Node views with Vue
|
||||
|
||||
## toc
|
||||
|
||||
## Introduction
|
||||
Using Vanilla JavaScript can feel complex if you are used to work in Vue. Good news: You can use regular Vue components in your node views, too. There is just a little bit you need to know, but let’s go through this one by one.
|
||||
|
||||
## Render a Vue component
|
||||
Here is what you need to do to render Vue components inside your editor:
|
||||
|
||||
1. [Create a node extension](/guide/custom-extensions)
|
||||
2. Create a Vue component
|
||||
3. Pass that component to the provided `VueNodeViewRenderer`
|
||||
4. Register it with `addNodeView()`
|
||||
5. [Configure tiptap to use your new node extension](/guide/configuration)
|
||||
|
||||
This is how your node extension could look like:
|
||||
|
||||
```js
|
||||
import { Node } from '@tiptap/core'
|
||||
import { VueNodeViewRenderer } from '@tiptap/vue-2'
|
||||
import Component from './Component.vue'
|
||||
|
||||
export default Node.create({
|
||||
// configuration …
|
||||
|
||||
addNodeView() {
|
||||
return VueNodeViewRenderer(Component)
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
There is a little bit of magic required to make this work. But don’t worry, we provide a wrapper component you can use to get started easily. Don’t forget to add it to your custom Vue component, like shown below:
|
||||
|
||||
```html
|
||||
<template>
|
||||
<node-view-wrapper>
|
||||
Vue Component
|
||||
</node-view-wrapper>
|
||||
</template>
|
||||
```
|
||||
|
||||
Got it? Let’s see it in action. Feel free to copy the below example to get started.
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/VueComponent"></tiptap-demo>
|
||||
|
||||
That component doesn’t interact with the editor, though. Time to wire it up.
|
||||
|
||||
## Access node attributes
|
||||
The `VueNodeViewRenderer` which you use in your node extension, passes a few very helpful props to your custom Vue component. One of them is the `node` prop. Add this snippet to your Vue component to directly access the node:
|
||||
|
||||
```js
|
||||
props: {
|
||||
node: {
|
||||
type: Object,
|
||||
required: true,
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
That enables you to access node attributes in your Vue component. Let’s say you have [added an attribute](/guide/custom-extensions#attributes) named `count` to your node extension (like we did in the above example) you could access it like this:
|
||||
|
||||
```js
|
||||
this.node.attrs.count
|
||||
```
|
||||
|
||||
## Update node attributes
|
||||
You can even update node attributes from your node, with the help of the `updateAttributes` prop passed to your component. Just add this snippet to your component:
|
||||
|
||||
```js
|
||||
props: {
|
||||
updateAttributes: {
|
||||
type: Function,
|
||||
required: true,
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
Pass an object with updated attributes to the function:
|
||||
|
||||
```js
|
||||
this.updateAttributes({
|
||||
count: this.node.attrs.count + 1,
|
||||
})
|
||||
```
|
||||
|
||||
And yes, all of that is reactive, too. A pretty seemless communication, isn’t it?
|
||||
|
||||
## Adding a content editable
|
||||
There is another component called `NodeViewContent` which helps you adding editable content to your node view. Here is an example:
|
||||
|
||||
```html
|
||||
<template>
|
||||
<node-view-wrapper class="dom">
|
||||
<node-view-content class="content-dom" />
|
||||
</node-view-wrapper>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { NodeViewWrapper, NodeViewContent } from '@tiptap/vue-2'
|
||||
|
||||
export default {
|
||||
components: {
|
||||
NodeViewWrapper,
|
||||
NodeViewContent,
|
||||
},
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
You don’t need to add those `class` attributes, feel free to remove them or pass other class names. Try it out in the following example:
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/VueComponentContent"></tiptap-demo>
|
||||
|
||||
Keep in mind that this content is rendered by tiptap. That means you need to tell what kind of content is allowed, for example with `content: 'inline*'` in your node extension (that’s what we use in the above example).
|
||||
|
||||
The `NodeViewWrapper` and `NodeViewContent` components render a `<div>` HTML tag (`<span>` for inline nodes), but you can change that. For example `<node-view-content as="p">` should render a paragraph. One limitation though: That tag must not change during runtime.
|
||||
|
||||
## All available props
|
||||
For advanced use cases, we pass a few more props to the component. Here is the full list of what props you can expect:
|
||||
|
||||
```html
|
||||
<template>
|
||||
<node-view-wrapper />
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { NodeViewWrapper } from '@tiptap/vue-2'
|
||||
|
||||
export default {
|
||||
components: {
|
||||
NodeViewWrapper,
|
||||
},
|
||||
|
||||
props: {
|
||||
// the editor instance
|
||||
editor: {
|
||||
type: Object,
|
||||
},
|
||||
|
||||
// the current node
|
||||
node: {
|
||||
type: Object,
|
||||
},
|
||||
|
||||
// an array of decorations
|
||||
decorations: {
|
||||
type: Array,
|
||||
},
|
||||
|
||||
// `true` when there is a `NodeSelection` at the current node view
|
||||
selected: {
|
||||
type: Boolean,
|
||||
},
|
||||
|
||||
// access to the node extension, for example to get options
|
||||
extension: {
|
||||
type: Object,
|
||||
},
|
||||
|
||||
// get the document position of the current node
|
||||
getPos: {
|
||||
type: Function,
|
||||
},
|
||||
|
||||
// update attributes of the current node
|
||||
updateAttributes: {
|
||||
type: Function,
|
||||
},
|
||||
|
||||
// delete the current node
|
||||
deleteNode: {
|
||||
type: Function,
|
||||
},
|
||||
},
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
If you just want to have all (and to have TypeScript support) you can import all props like that:
|
||||
|
||||
```js
|
||||
// Vue 3
|
||||
import { defineComponent } from 'vue'
|
||||
import { nodeViewProps } from '@tiptap/vue-3'
|
||||
export default defineComponent({
|
||||
props: nodeViewProps,
|
||||
})
|
||||
|
||||
// Vue 2
|
||||
import Vue from 'vue'
|
||||
import { nodeViewProps } from '@tiptap/vue-2'
|
||||
export default Vue.extend({
|
||||
props: nodeViewProps,
|
||||
})
|
||||
```
|
||||
|
||||
## Dragging
|
||||
To make your node views draggable, set `draggable: true` in the extension and add `data-drag-handle` to the DOM element that should function as the drag handle.
|
||||
|
||||
<tiptap-demo name="GuideNodeViews/DragHandle"></tiptap-demo>
|
||||
Reference in New Issue
Block a user