mirror of
https://github.com/ianstormtaylor/slate.git
synced 2025-08-30 02:19:52 +02:00
add data model guide, update docs
This commit is contained in:
Ian Storm Taylor
@@ -1,20 +0,0 @@
|
||||
|
||||
# Plugins
|
||||
|
||||
In Slate, all custom logic added to the editor is done via plugins. Plugins have complete control over the schema, the behaviors, and the rendering of the components of the editor. Slate encourages you to break up code into small, reusable modules that can be shared with others, and easily reasoned about.
|
||||
|
||||
_To learn more, check out the [Using Plugins guide](../walkthroughs/using-plugins.md), or the [Plugins reference](../reference/slate-react/plugins.md)._
|
||||
|
||||
|
||||
### The Core Plugin
|
||||
|
||||
The "core" plugin that ships with Slate is where the default editing behavior is kept. It performs actions like splitting the current block when `enter` is pressed, or inserting a string of text when the user pastes from their clipboard. But it stops short of anything opinionated, leaving that for userland plugins to add.
|
||||
|
||||
_To learn more, check out the [Core Plugin reference](../reference/slate-react/core-plugin.md)._
|
||||
|
||||
|
||||
### The Editor Plugin
|
||||
|
||||
Plugins are so central to Slate's architecture, that the properties of the [`<Editor>`](../reference/slate-react/editor.md) that allow you to add custom functionality (eg. `onKeyDown` or `onPaste`) are actually implemented as a plugin too. All of those properties actually just create an implicitly, top-priority plugin that gets added at the beginning of the editor's plugin stack. But you'd never even know it!
|
||||
|
||||
_To learn more, check out the [`<Editor>` component reference](../reference/slate-react/editor.md)._
|
||||
@@ -1,24 +0,0 @@
|
||||
|
||||
# Statelessness & Immutability
|
||||
|
||||
All of the data in Slate is immutable, thanks to [Immutable.js](https://facebook.github.io/immutable-js/). This makes it much easier to reason about complex editing logic, and it makes maintaining a history of changes for undo/redo much simpler.
|
||||
|
||||
_To learn more, check out the [`State` model reference](../reference/slate/state.md)._
|
||||
|
||||
|
||||
### The `onChange` Handler
|
||||
|
||||
Because of Slate's immutability, you don't actually "set" itself a new state when something changes.
|
||||
|
||||
Instead, the new state is propagated to the Slate editor's parent component, who decides what to do with it. Usually, you'll simply give the new state right back to the editor via React's `this.setState()` method, similarly to other internal component state. But that's up to you!
|
||||
|
||||
_To learn more, check out the [`<Editor>` component reference](../reference/slate-react/editor.md)._
|
||||
|
||||
|
||||
### Changes
|
||||
|
||||
All of the changes in Slate are applied via [`Changes`](../reference/slate/change.md). This makes it possible to enforce some of the constraints that Slate needs to enforce, like requiring that [all leaf nodes be text nodes](./the-document-model.md#leaf-text-nodes). This also makes it possible to implement collaborative editing, where information about changes must be serialized and sent over the network to other editors.
|
||||
|
||||
You should never update the `selection` or `document` of an editor other than by using the [`change()`](../reference/slate/state.md#change) method of a `State`.
|
||||
|
||||
_To learn more, check out the [`Change` model reference](../reference/slate/change.md)._
|
||||
@@ -1,34 +0,0 @@
|
||||
|
||||
# The Document Model
|
||||
|
||||
A big difference between Slate and other rich-text editors is that Slate is built on top of a nested, recursive document model—much like the DOM itself. This means you can build complex components like tables or nested block quotes, just like you can with the regular DOM.
|
||||
|
||||
|
||||
### Node Hierarchy
|
||||
|
||||
Each Slate document is made up of [`Document`](../reference/slate/document.md), [`Block`](../reference/slate/block.md), [`Inline`](../reference/slate/inline.md) and [`Text`](../reference/slate/text.md) nodes—again, very similar to the DOM.
|
||||
|
||||
The top-level node of a Slate document is the `Document` node. The `Document` then has child `Block` node children.
|
||||
|
||||
After that, nesting can occur to any depth. `Block` nodes can contain other `Block` nodes, or they can contain `Inline` or `Text` nodes. And `Inline` nodes can contain other `Inline` nodes or simply `Text` nodes.
|
||||
|
||||
Each `Document`, `Block` and `Inline` node implements a [`Node`](../reference/slate/node.md) interface, to make working with the nested tree easier.
|
||||
|
||||
|
||||
### Characters & Marks
|
||||
|
||||
As the leaves of the tree, `Text` nodes contain both the text content of the document as well as all of the text-level formatting, like **bold** and _italic_. In Slate, that formatting is referred to as [`Marks`](../reference/slate/mark.md), and `Marks` are applied to individual [`Characters`](../reference/slate/character.md).
|
||||
|
||||
|
||||
### Void Nodes
|
||||
|
||||
Just like the DOM, Slate's `Block` and `Inline` nodes can be "void" nodes, meaning that they have no content inside of them. When the `isVoid` flag of a node is enabled, it will be specially rendered, to preserve the editing experience that a user expects, without any extra work.
|
||||
|
||||
Note that even though the node is "void", it will still have an empty text node inside of it. Because of...
|
||||
|
||||
|
||||
### Leaf Text Nodes
|
||||
|
||||
One constraint of Slate documents is that the leaf nodes are always `Text` nodes. No `Block` or `Inline` node will ever have no children. It will always have at least an empty text node. (However, you can _render_ text-less nodes, see the [Void Nodes](#void-nodes) section above!)
|
||||
|
||||
This constraint means that [`Ranges`](../reference/slate/range.md) can always refer to text nodes, and many text-node-level operations are always "safe" regardless of the tree's structure.
|
||||
@@ -1,25 +0,0 @@
|
||||
|
||||
# The Selection Model
|
||||
|
||||
Slate keeps track of the user's selection in the editor in an immutable data store called a [`Range`](../reference/slate/range.md). By doing this, it lets Slate manipulate the selection with changes, but still update it in the DOM on `render`.
|
||||
|
||||
|
||||
### Always References Text
|
||||
|
||||
One of the constraints of the Slate document model is that [leaf nodes are always text nodes](./the-document-model.md#leaf-text-nodes). This constraint exists to make selection logic simpler.
|
||||
|
||||
A selection always refers to text nodes. Such that even if you set a selection relative to a non-text node, Slate will automatically correct it for you.
|
||||
|
||||
This makes selections easier to reason about, while still giving us the benefits of a recursive document tree, and it makes for a lot less boilerplate.
|
||||
|
||||
|
||||
### Leaf Blocks
|
||||
|
||||
When a selection is used to compute a set of [`Block`](../reference/slate/block.md) nodes, by convention those nodes are always the leaf-most `Block` nodes (ie. the lowest `Block` nodes in the tree at their location). This is important, because the nested document model allows for nested `Block` nodes.
|
||||
|
||||
This convention makes it much simpler to implement selection and changeation logic, since the user's actions are very often supposed to effect the leaf blocks.
|
||||
|
||||
|
||||
### Trunk Inlines
|
||||
|
||||
Unline `Block` nodes, when a selection is used to compute a set of [`Inline`](../reference/slate/inline.md) nodes, the trunk-most nodes are used (ie. the highest `Inline` nodes in the tree at their location). This is done for the same reason, that most user actions are supposed to act at the highest level of inline nodes.
|
||||
Reference in New Issue
Block a user