volto-slate

Watch a 5 minutes "elevator pitch" for volto-slate

An alternative text editor for Volto, capable of completely replacing the default richtext editor while offering enhanced functionality and behavior. We believe that, in order to succeed, Volto's richtext form editor (the Volto Composite Page editor) needs strong integration between the rich text capabilities and the rest of the Volto blocks. Some examples of the kind of strong integration we have in mind:

Pasting complex documents inside a volto-slate text block will create multiple Volto blocks: images will be converted to Volto Image blocks, tables will be converted to Volto Table blocks, etc.
The text block accepts drag&drop images and it will upload them as Volto Image blocks.
volto-slate has a Table button with the familiar size input, but it create a Table block

While this addon is still in an early alpha stage, we've solved most of the big issues, the API starts to stabilize and we've already started several addons based on it: https://github.com/eea/volto-slate-metadata-mentions/ and https://github.com/eea/volto-slate-zotero

Why

Some of the main reasons that drove us to create volto-slate instead of enhancing Volto's draftjs implementation:

Volto's draftjs implementation depends on draft-js-plugins, a third-party project that introduces its own set of bugs and maintanance issues
Slate has a modern, developer-friendly api that makes developing plugins something easy to do. Getting the editor in a plugin is as easy as const editor = useSlate(), overriding core functionality is something that's built in as pluggable, directly in Slate.
Volto's draft based implementation depends on Redraft for its final output, which comes with its own bugs and issues. While it is nice to have view-mode components, this is something that volto-slate implements just as well.
Because Slate's internal storage uses a tree modeled on the DOM pattern, its final rendered output is very clean. Note: The Slate editor value is a JSON object, similar to the Draftjs based implementation.

Available profiles.

volto-slate provides several optional configuration:

asDefault which makes the volto-slate as the default richtext block editor
minimalDefault, same as the above, but uses a set of toolbar buttons similar to Volto
simpleLink reuses Volto's link plugin and makes for a better replacement of Volto's rich text editor.

Features

1. Hovering (floating) toolbar that shows up on selection

2. Optional expanded (fixed) toolbar

3. Working with links (internal, external, email)

4. Removing links

5. Editing links

6. Block-quotes

7. Split paragraph block in two with `Enter` key and join them back with `Backspace` key

8. Breaking and joining list items

9. Breaking (with expanded selection) and joining list items

10. Inserting a new list item at the end

11. Two `Enter` key presses in the last empty list item creates a new list

12. Using `Up` and `Down` keys to go through the blocks in both directions

13. Changing indent level of list items using `Tab` and `Shift-Tab` keys

14. Splitting a list block with `Enter` into two list blocks

15. Support for markdown bulleted lists with `*`, `-` and `+`

16. Support for markdown numbered lists with `1.` - `9.`

17. `Backspace` with cursor on first position inside a list with just one item converts the list to a paragraph

18. Creating a new text block with `Enter` at the end of a text block and removing it with `Backspace`

19. Switching the list type (numbered list to/from bulleted list)

Getting started

Try volto-slate with Docker

Get the latest Docker images

docker pull plone
docker pull plone/volto

Start Plone backend

docker run -d --name plone -p 8080:8080 -e SITE=Plone -e PROFILES="profile-plone.restapi:blocks" plone

Start Volto frontend

docker run -it --rm -p 3000:3000 --link plone -e ADDONS="volto-slate:asDefault" plone/volto

Go to http://localhost:3000
Login with admin:admin
Create a new Page and add a new Text block.

Add volto-slate to your Volto project

Make sure you have a Plone backend up-and-running at http://localhost:8080/Plone
Start Volto frontend

If you already have a Volto project, just update package.json:

"addons": [
    "volto-slate:asDefault"
],

"dependencies": {
    "volto-slate": "*"
}

If not, create one:

npm install -g yo @plone/generator-volto
yo @plone/volto my-volto-project --addon volto-slate:asDefault
cd my-volto-project

Install new add-ons and restart Volto:
```
yarn install
yarn start
```

Go to http://localhost:3000
Happy editing!

How to contribute

See DEVELOP.md.

Credit

A lot of inspiration from the great Slate Plugins repository, especially the autoformat handlers.

Copyright and license

See LICENSE.md for details.

Funding

European Environment Agency (EU)

ksuess/volto-slate