mirror/slate
1
0
Fork 0
mirror of https://github.com/ianstormtaylor/slate.git synced 2025-09-02 03:32:36 +02:00
Code Issues Releases Wiki Activity

Rename "state" to "value" everywhere (#1313)

Browse Source 
* rename state to value in slate core, as deprecation

* rename all references to state to value in slate core

* migrate slate-base64-serializer

* migrate slate-html-serializer

* migrate slate-hyperscript

* migrate slate-plain-serializer

* migrate slate-prop-types

* migrate slate-simulator

* fix change.setState compat

* deprecate references to state in slate-react

* remove all references to state in slate-react

* remove `value` and `schema` from props to all components

* fix default renderPlaceholder

* fix tests

* update examples

* update walkthroughs

* update guides

* update reference
This commit is contained in:
Ian Storm Taylor
2017-10-27 13:39:06 -07:00
committed by GitHub
parent 44addc8140
commit adb2678732
576 changed files with 3672 additions and 3718 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/walkthroughs/adding-event-handlers.md
View File

@@ -7,7 +7,7 @@
Okay, so you've got Slate installed and rendered on the page, and when you type in it, you can see the changes reflected. But you want to do more than just type a plaintext string.
What makes Slate great is how easy it is to customize. Just like other React components you're used to, Slate allows you to pass in handlers that are triggered on certain events. You've already seen on the `onChange` handler can be used to store the changed editor state, but let's try add something more...
What makes Slate great is how easy it is to customize. Just like other React components you're used to, Slate allows you to pass in handlers that are triggered on certain events. You've already seen on the `onChange` handler can be used to store the changed editor value, but let's try add something more...
We'll show you how to use the `onKeyDown` handler to change the editor's content when the user presses a button.
@@ -17,17 +17,17 @@ So we start with our app from earlier:
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)
@@ -42,11 +42,11 @@ And now we'll add an `onKeyDown` handler:
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
// Define a new handler which prints the key that was pressed.
@@ -57,7 +57,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
/>
@@ -77,11 +77,11 @@ Our `onKeyDown` handler might look like this:
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -91,7 +91,7 @@ class App extends React.Component {
// Prevent the ampersand character from being inserted.
event.preventDefault()
// Change the state by inserting "and" at the cursor's position.
// Change the value by inserting "and" at the cursor's position.
change.insertText('and')
return true
}
@@ -99,7 +99,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
/>
@@ -111,7 +111,7 @@ class App extends React.Component {
With that added, try typing `&`, and you should see it automatically become `and` instead!
That gives you a sense for what you can do with Slate's event handlers. Each one will be called with the `event` object, and the current `state` of the editor. And if you return a new `state`, the editor will be updated. Simple!
That gives you a sense for what you can do with Slate's event handlers. Each one will be called with the `event` object, and a `change` object that lets you perform changes to the editor's value. Simple!
<br/>
<p align="center"><strong>Next:</strong><br/><a href="./defining-custom-block-nodes.md">Defining Custom Block Nodes</a></p>

32
docs/walkthroughs/applying-custom-formatting.md
View File

@@ -15,17 +15,17 @@ So we start with our app from earlier:
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
if (event.key != '`' || !event.metaKey) return
event.preventDefault()
const isCode = change.state.blocks.some(block => block.type == 'code')
const isCode = change.value.blocks.some(block => block.type == 'code')
change.setBlock(isCode ? 'paragraph' : 'code')
return true
@@ -34,7 +34,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
renderNode={this.renderNode}
@@ -57,11 +57,11 @@ And now, we'll edit the `onKeyDown` handler to make it so that when you press `
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -77,7 +77,7 @@ class App extends React.Component {
}
// When "`" is pressed, keep our existing code block logic.
case '`': {
const isCode = change.state.blocks.some(block => block.type == 'code')
const isCode = change.value.blocks.some(block => block.type == 'code')
event.preventDefault()
change.setBlock(isCode ? 'paragraph' : 'code')
return true
@@ -88,7 +88,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
renderNode={this.renderNode}
@@ -128,11 +128,11 @@ function BoldMark(props) {
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -145,9 +145,9 @@ class App extends React.Component {
return true
}
case '`': {
const isCode = change.state.blocks.some(block => block.type == 'code')
const isCode = change.value.blocks.some(block => block.type == 'code')
event.preventDefault()
state.setBlock(isCode ? 'paragraph' : 'code')
value.setBlock(isCode ? 'paragraph' : 'code')
return true
}
}
@@ -156,7 +156,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
renderNode={this.renderNode}

34
docs/walkthroughs/defining-custom-block-nodes.md
View File

@@ -15,11 +15,11 @@ We'll show you how. Let's start with our app from earlier:
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -32,7 +32,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
/>
@@ -71,11 +71,11 @@ function CodeNode(props) {
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -89,7 +89,7 @@ class App extends React.Component {
return (
// Pass in the `renderNode` prop...
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
renderNode={this.renderNode}
@@ -117,11 +117,11 @@ function CodeNode(props) {
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -139,7 +139,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
renderNode={this.renderNode}
@@ -168,11 +168,11 @@ function CodeNode(props) {
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -181,7 +181,7 @@ class App extends React.Component {
event.preventDefault()
// Determine whether any of the currently selected blocks are code blocks.
const isCode = change.state.blocks.some(block => block.type == 'code')
const isCode = change.value.blocks.some(block => block.type == 'code')
// Toggle the block type depending on `isCode`.
change.setBlock(isCode ? 'paragraph' : 'code')
@@ -191,7 +191,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
renderNode={this.renderNode}

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

@@ -24,15 +24,15 @@ Slate exposes a set of modules that you'll use to build your editor. The most im
import { Editor } from 'slate-react'
```
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:
In addition to rendering the editor, you need to give Slate a "initial value" to render as content. We'll use the `Value` model that ships with Slate to create a new initial value that just contains a single paragraph block with some text in it:
```js
// Import the `State` model.
// Import the `Value` model.
import { Editor } from 'slate-react'
import { State } from 'slate'
import { Value } from 'slate'
// Create our initial state...
const initialState = State.fromJSON({
// Create our initial value...
const initialValue = Value.fromJSON({
document: {
nodes: [
{
@@ -54,15 +54,15 @@ const initialState = State.fromJSON({
})
```
And now that we've our initial state, we define our `App` and pass it into Slate's `Editor` component, like so:
And now that we've our initial value, we define our `App` and pass it into Slate's `Editor` component, like so:
```js
// Import React!
import React from 'react'
import { Editor } from 'slate-react'
import { State } from 'slate'
import { Value } from 'slate'
const initialState = State.fromJSON({
const initialValue = Value.fromJSON({
document: {
nodes: [
{
@@ -86,21 +86,21 @@ const initialState = State.fromJSON({
// Define our app...
class App extends React.Component {
// Set the initial state when the app is first constructed.
// Set the initial value when the app is first constructed.
state = {
state: initialState
value: initialValue
}
// On change, update the app's React state with the new editor state.
onChange = ({ state }) => {
this.setState({ state })
// On change, update the app's React state with the new editor value.
onChange = ({ value }) => {
this.setState({ value })
}
// Render the editor.
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)
@@ -109,7 +109,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 changed 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 value. That way, when it re-renders the editor, the new value is reflected with your changes.
And that's it!

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

@@ -15,17 +15,17 @@ import { Editor } from 'slate-react'
class App extends React.Component {
state = {
state: Plain.deserialize('')
value: Plain.deserialize('')
}
onChange({ state }) {
this.setState({ state })
onChange({ value }) {
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)
@@ -209,8 +209,8 @@ const html = new Html({ rules })
And finally, now that we have our serializer initialized, we can update our app to use it to save and load content, like so:
```js
// Load the initial state from Local Storage or a default.
const initialState = (
// Load the initial value from Local Storage or a default.
const initialValue = (
localStorage.getItem('content') ||
'<p></p>'
)
@@ -218,23 +218,23 @@ const initialState = (
class App extends React.Component {
state = {
state: html.deserialize(initialState),
value: html.deserialize(initialValue),
}
onChange = ({ state }) => {
onChange = ({ value }) => {
// When the document changes, save the serialized HTML to Local Storage.
if (state.document != this.state.state.document) {
const string = html.serialize(state)
if (value.document != this.state.value.document) {
const string = html.serialize(value)
localStorage.setItem('content', string)
}
this.setState({ state })
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
// Add the ability to render our nodes and marks...
renderNode={this.renderNode}

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

@@ -13,9 +13,9 @@ Let's start with a basic editor:
```js
import { Editor } from 'slate-react'
import { State } from 'slate'
import { Value } from 'slate'
const initialState = State.fromJSON({
const initialValue = Value.fromJSON({
document: {
nodes: [
{
@@ -39,17 +39,17 @@ const initialState = State.fromJSON({
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)
@@ -58,14 +58,14 @@ 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 state—nothing saves!
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 value—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, like JSON!
So, in our `onChange` handler, we need to save the `value`. But the `value` 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 initialState = State.fromJSON({
const initialValue = Value.fromJSON({
document: {
nodes: [
{
@@ -89,21 +89,21 @@ const initialState = State.fromJSON({
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
// Save the state to Local Storage.
const content = JSON.stringify(state.toJSON())
onChange = ({ value }) => {
// Save the value to Local Storage.
const content = JSON.stringify(value.toJSON())
localStorage.setItem('content', content)
this.setState({ state })
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)
@@ -114,12 +114,12 @@ class App extends React.Component {
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:
But... if you refresh the page, everything is still reset. That's because we need to make sure the initial value 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 existingState = JSON.parse(localStorage.getItem('content'))
const initialState = State.fromJSON(existingState || {
const existingValue = JSON.parse(localStorage.getItem('content'))
const initialValue = Value.fromJSON(existingValue || {
document: {
nodes: [
{
@@ -143,20 +143,20 @@ const initialState = State.fromJSON(existingState || {
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
const content = JSON.stringify(state.toJSON())
onChange = ({ value }) => {
const content = JSON.stringify(value.toJSON())
localStorage.setItem('content', content)
this.setState({ state })
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)
@@ -170,8 +170,8 @@ 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 existingState = JSON.parse(localStorage.getItem('content'))
const initialState = State.fromJSON(existingState || {
const existingValue = JSON.parse(localStorage.getItem('content'))
const initialValue = Value.fromJSON(existingValue || {
document: {
nodes: [
{
@@ -195,23 +195,23 @@ const initialState = State.fromJSON(existingState || {
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
onChange = ({ value }) => {
// Check to see if the document has changed before saving.
if (state.document != this.state.state.document) {
const content = JSON.stringify(state.toJSON())
if (value.document != this.state.value.document) {
const content = JSON.stringify(value.toJSON())
localStorage.setItem('content', content)
}
this.setState({ state })
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)
@@ -224,35 +224,35 @@ Now you're content will be saved only when the content itself changes!
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:
But what if you want something other than JSON? Well, you'd need to serialize your value 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
// Switch to using the Plain serializer.
import { Editor } from 'slate-react'
import Plain from 'slate-plain-serializer'
const existingState = localStorage.getItem('content')
const initialState = Plain.deserialize(existingState || 'A string of plain text.')
const existingValue = localStorage.getItem('content')
const initialValue = Plain.deserialize(existingValue || 'A string of plain text.')
class App extends React.Component {
state = {
state: initialState
value: initialValue
}
onChange = ({ state }) => {
if (state.document != this.state.state.document) {
const content = Plain.serialize(state)
onChange = ({ value }) => {
if (value.document != this.state.value.document) {
const content = Plain.serialize(value)
localStorage.setItem('content', content)
}
this.setState({ state })
this.setState({ value })
}
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
/>
)

24
docs/walkthroughs/using-plugins.md
View File

@@ -17,11 +17,11 @@ Starting with our app from earlier:
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
onKeyDown = (event, change) => {
@@ -34,7 +34,7 @@ class App extends React.Component {
render() {
return (
<Editor
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
onKeyDown={this.onKeyDown}
renderMark={this.renderMark}
@@ -106,11 +106,11 @@ const plugins = [
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
render() {
@@ -118,7 +118,7 @@ class App extends React.Component {
// Add the `plugins` property to the editor, and remove `onKeyDown`.
<Editor
plugins={plugins}
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
renderMark={this.renderMark}
/>
@@ -151,18 +151,18 @@ const plugins = [
class App extends React.Component {
state = {
state: initialState,
value: initialValue,
}
onChange = ({ state }) => {
this.setState({ state })
onChange = ({ value }) => {
this.setState({ value })
}
render() {
return (
<Editor
plugins={plugins}
state={this.state.state}
value={this.state.value}
onChange={this.onChange}
renderMark={this.renderMark}
/>