mirror/slate
1
0
Fork 0
mirror of https://github.com/ianstormtaylor/slate.git synced 2025-08-28 01:19:52 +02:00
Code Issues Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Ian Storm Taylor
2017-09-10 15:29:42 -07:00
parent 10e4216d00
commit 133831ee4e
17 changed files with 293 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/walkthroughs/installing-slate.md
View File

@@ -24,54 +24,62 @@ Slate exposes a set of modules that you'll use to build your editor. The most im
import { Editor } from 'slate'
```
In addition to rendering the editor, you need to give Slate a "initial state" to render as content.
To keep things simple, we'll use the `Raw` serializer that ships with Slate to create a new initial state that just contains a single paragraph block with some text in it:
In addition to rendering the editor, you need to give Slate a "initial state" to render as content. We'll use the `State` model that ships with Slate to create a new initial state that just contains a single paragraph block with some text in it:
```js
// Import the "raw" serializer that ships with Slate.
import { Editor, Raw } from 'slate'
// Import the `State` model.
import { Editor, State } from 'slate'
// Create our initial state...
const initialState = Raw.deserialize({
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
text: 'A line of text in a paragraph.'
}
]
}
]
}, { terse: true })
const initialState = State.fromJSON({
document: {
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
ranges: [
{
text: 'A line of text in a paragraph.'
}
]
}
]
}
]
}
})
```
The `terse: true` option there isn't important for now, but if you're curious about it you can check out the [`Raw` serializer reference](../reference/serializers/raw.md).
And now that we've our initial state, we define our `App` and pass it into Slate's `Editor` component, like so:
```js
// Import React!
import React from 'react'
import { Editor, Raw } from 'slate'
import { Editor, State } from 'slate'
const initialState = Raw.deserialize({
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
text: 'A line of text in a paragraph.'
}
]
}
]
}, { terse: true })
const initialState = State.fromJSON({
document: {
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
ranges: [
{
text: 'A line of text in a paragraph.'
}
]
}
]
}
]
}
})
// Define our app...
class App extends React.Component {
@@ -99,7 +107,7 @@ class App extends React.Component {
}
```
You'll notice that the `onChange` handler passed into the `Editor` component just updates the app's state with the newest editor state. That way, when it re-renders the editor, the new state is reflected with your changes.
You'll notice that the `onChange` handler passed into the `Editor` component just updates the app's state with the newest changed state. That way, when it re-renders the editor, the new state is reflected with your changes.
And that's it!
@@ -109,22 +117,3 @@ That's the most basic example of Slate. If you render that onto the page, you sh
<p align="center"><strong>Next:</strong><br/><a href="./adding-event-handlers.md">Adding Event Handlers</a></p>
<br/>

6
docs/walkthroughs/saving-and-loading-html-content.md
View File

@@ -5,9 +5,7 @@
# Saving and Loading HTML Content
In the previous guide, we looked at how to serialize the Slate editor's content and save it for later. But we only covered the [`Plain`](../reference/serializers/plain.md) and [`Raw`](../reference/serializers/raw.md) serialization techniques.
What if you want to save the content as HTML? It's a slightly more involved process, but this guide will show you how to do it.
In the previous guide, we looked at how to serialize the Slate editor's content and save it for later. What if you want to save the content as HTML? It's a slightly more involved process, but this guide will show you how to do it.
Let's start with a basic editor:
@@ -66,8 +64,6 @@ const rules = [
]
```
If you've worked with the [`Raw`](../reference/serializers/raw.md) serializer before, the return value of the `deserialize` should look familiar! It's just the same raw JSON format.
The `el` argument that the `deserialize` function receives is just a DOM element. And the `next` argument is a function that will deserialize any element(s) we pass it, which is how you recurse through each node's children.
A quick note on `el.tagName` -- in browser environments, Slate uses the native `DOMParser` to parse HTML, which returns uppercase tag names. In server-side or node environments, we recommend [providing parse5](https://docs.slatejs.org/reference/serializers/html.html#parsehtml) to parse HTML; however, parse5 returns lowercase tag names due to some subtle complexities in specifications. Consequentially, we recommend using case-insensitive tag comparisons, so your code just works everywhere without having to worry about the parser implementation.

147
docs/walkthroughs/saving-to-a-database.md
View File

@@ -9,17 +9,36 @@ Now that you've learned the basics of how to add functionality to the Slate edit
In this guide, we'll show you how to add logic to save your Slate content to a database for storage and retrieval later.
Let's start with a basic, plain text rendering editor:
Let's start with a basic editor:
```js
import { Editor, Plain } from 'slate'
import { Editor, State } from 'slate'
const initialContent = 'The initial string of content!'
const initialState = State.fromJSON({
document: {
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
ranges: [
{
text: 'A line of text in a paragraph.'
}
]
}
]
}
]
}
})
class App extends React.Component {
state = {
state: Plain.deserialize(initialContent)
state: initialState
}
onChange = ({ state }) => {
@@ -38,26 +57,43 @@ class App extends React.Component {
}
```
That will render a basic Slate editor on your page, and when you type things will change. But if you refresh the page, everything will be reverted back to its original stage.
That will render a basic Slate editor on your page, and when you type things will change. But if you refresh the page, everything will be reverted back to its original state—nothing saves!
What we need to do is save the changes you make somewhere. For this example, we'll just be using [Local Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage), but it will give you an idea for where you'd need to add your own database hooks.
So, in our `onChange` handler, we need to save the `state`. But the `state` argument that `onChange` receives is an immutable object, so we can't just save it as-is. We need to serialize it to a format we understand first.
In this case, we're already using the [`Plain`](../reference/serializers/plain.md) serializer to create our initial state, so let's use it to serialize our saved state as well, like so:
So, in our `onChange` handler, we need to save the `state`. But the `state` argument that `onChange` receives is an immutable object, so we can't just save it as-is. We need to serialize it to a format we understand first, like JSON!
```js
const initialContent = 'The initial string of content!'
const initialState = State.fromJSON({
document: {
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
ranges: [
{
text: 'A line of text in a paragraph.'
}
]
}
]
}
]
}
})
class App extends React.Component {
state = {
state: Plain.deserialize(initialContent)
state: initialState
}
onChange = ({ state }) => {
// Save the state to Local Storage.
const content = Plain.serialize(state)
const content = JSON.stringify(state.toJSON())
localStorage.setItem('content', content)
this.setState({ state })
@@ -75,25 +111,42 @@ class App extends React.Component {
}
```
Now whenever you edit the page, if you look in Local Storage, you should see the content string changing.
Now whenever you edit the page, if you look in Local Storage, you should see the `content` value changing.
But... if you refresh the page, everything is still reset. That's because we need to make sure the initial state is pulled from that same Local Storage location, like so:
```js
// Update the initial content to be pulled from Local Storage if it exists.
const initialContent = (
localStorage.getItem('content') ||
'The initial string of content!'
)
const existingState = JSON.parse(localStorage.getItem('content'))
const initialState = State.fromJSON(existingState || {
document: {
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
ranges: [
{
text: 'A line of text in a paragraph.'
}
]
}
]
}
]
}
})
class App extends React.Component {
state = {
state: Plain.deserialize(initialContent)
state: initialState
}
onChange = ({ state }) => {
const content = Plain.serialize(state)
const content = JSON.stringify(state.toJSON())
localStorage.setItem('content', content)
this.setState({ state })
@@ -116,20 +169,38 @@ Now you should be able to save changes across refreshes!
However, if you inspect the change handler, you'll notice that it's actually saving the Local Storage value on _every_ change to the editor, even when only the selection changes! This is because `onChange` is called for _every_ change. For Local Storage this doesn't really matter, but if you're saving things to a database via HTTP request this would result in a lot of unnecessary requests. You can fix this by checking against the previous `document` value.
```js
const initialContent = (
localStorage.getItem('content') ||
'The initial string of content!'
)
const existingState = JSON.parse(localStorage.getItem('content'))
const initialState = State.fromJSON(existingState || {
document: {
nodes: [
{
kind: 'block',
type: 'paragraph',
nodes: [
{
kind: 'text',
ranges: [
{
text: 'A line of text in a paragraph.'
}
]
}
]
}
]
}
})
class App extends React.Component {
state = {
state: Plain.deserialize(initialContent)
state: initialState
}
onChange = ({ state }) => {
// Check to see if the document has changed before saving.
if (state.document != this.state.state.document) {
const content = Plain.serialize(state)
const content = JSON.stringify(state.toJSON())
localStorage.setItem('content', content)
}
@@ -150,32 +221,26 @@ class App extends React.Component {
Now you're content will be saved only when the content itself changes!
Success. But we're only saving plain text strings here. If you're working with rich text, you'll need to serialize the `state` object differently. Instead, you can use the `Raw` serializer, and save things in Local Storage as JSON strings, like so:
Success—you've got JSON in your database.
But what if you want something other than JSON? Well, you'd need to serialize your state differently. For example, if you want to save your content as plain text instead of JSON, you can use the `Plain` serializer that ships with Slate, like so:
```js
const initialContent = (
JSON.parse(localStorage.getItem('content')) ||
{
nodes: [
{
kind: 'block',
type: 'paragraph'
}
]
}
)
// Switch to using the Plain serializer.
import { Editor, Plain } from 'slate'
const existingState = localStorage.getItem('content')
const initialState = Plain.deserialize(existingState || 'A string of plain text.')
class App extends React.Component {
state = {
state: Raw.deserialize(initialContent, {terse: true})
state: initialState
}
onChange = ({ state }) => {
if (state.document != this.state.state.document) {
// Switch to using the Raw serializer.
const content = JSON.stringify(Raw.serialize(state))
const content = Plain.serialize(state)
localStorage.setItem('content', content)
}
@@ -194,9 +259,9 @@ class App extends React.Component {
}
```
That works! Now you can preserve any formatting that the user added.
That works! Now you're working with plain text.
However, sometimes you may not want to use the raw JSON representation that Slate understands, and you may want something slightly more standardized, like good old fashioned HTML. In that case, check out the next guide...
However, sometimes you may want something a bit more custom, and a bit more complex... good old fashioned HTML. In that case, check out the next guide...
<br/>