Tag: Scratch


Deprecated: Function create_function() is deprecated in /home2/thebrand/public_html/wp-content/plugins/wp-spamshield/wp-spamshield.php on line 1884
28 Jul

Creating An Accessible Dialog From Scratch

by TBSCategories: News

First of all, don’t do this at home. Do not write your own dialogs or a library to do so. There are plenty of them out there already that have been tested, audited, used and reused and you should prefer these ones over your own. a11y-dialog is one of them, but there are more (listed at the end of this article).

Let me take this post as an opportunity to remind you all to be cautious when using dialogs. It is tentalizing to address all design problems with them, especially on mobile, but there often are other ways to overcome design issues. We tend to quickly fall into using dialogs not because they are necessarily the right choice but because they are easy. They set aside screen estate problems by trading them for context switching, which is not always the right trade-off. The point is: consider whether a dialog is the right design pattern before using it.

In this post, we’re going to write a small JavaScript library for authoring accessible dialogs from the very beginning (essentially recreating a11y-dialog). The goal is to understand what goes into it. We’re not going to deal with styling too much, just the JavaScript part. We will use modern JavaScript for sake of simplicity (such as classes and arrow functions), but keep in mind that this code might not work in legacy browsers.

  1. Defining the API
  2. Instantiating the dialog
  3. Showing and hiding
  4. Closing with overlay
  5. Closing with escape
  6. Trapping focus
  7. Maintaining focus
  8. Restoring focus
  9. Giving an accessible name
  10. Handling custom events
  11. Cleaning up
  12. Bring it all together
  13. Wrapping up

Defining The API

First, we want to define how we’re going to use our dialog script. We are going to keep it as simple as possible to begin with. We give it the root HTML element for our dialog, and the instance we get has a .show(..) and a .hide(..) method.

class Dialog {   constructor(element) {}   show() {}   hide() {} }

Instantiating The Dialog

Let’s say we have the following HTML:

<div id="my-dialog">This will be a dialog.</div>

And we instantiate our dialog like this:

const element = document.querySelector('#my-dialog') const dialog = new Dialog(element)

There are a few things we need to do under the hood when instantiating it:

  • Hide it so it’s hidden by default (hidden).
  • Mark it as a dialog for assistive technologies (role="dialog").
  • Make the rest of the page inert when open (aria-modal="true").
constructor (element) {   // Store a reference to the HTML element on the instance so it can be used   // across methods.   this.element = element   this.element.setAttribute('hidden', true)   this.element.setAttribute('role', 'dialog')   this.element.setAttribute('aria-modal', true) }

Note that we could have added these 3 attributes in our initial HTML not to have to add them with JavaScript, but this way it’s out of sight, out of mind. Our script can make sure things will work as they should, regardless of whether we’ve thought about adding all our attributes or not.

Showing And Hiding

We have two methods: one to show the dialog and one to hide it. These methods won’t do much (for now) besides toggling the hidden attribute on the root element. We’re also going to maintain a boolean on the instance to quickly be able to assess if the dialog is shown or not. This will come in handy later.

show() {   this.isShown = true   this.element.removeAttribute('hidden') }  hide() {   this.isShown = false   this.element.setAttribute('hidden', true) }

To avoid the dialog being visible before JavaScript kicks in and hides it by adding the attribute, it might be interesting to add hidden to the dialog directly in the HTML from the get go.

<div id="my-dialog" hidden>This will be a dialog.</div>

Closing With Overlay

Clicking outside of the dialog should close it. There are several ways to do so. One way could be to listen to all click events on the page and filter out those happening within the dialog, but that’s relatively complex to do.

Another approach would be to listen to click events on the overlay (sometimes called “backdrop”). The overlay itself can be as simple as a <div> with some styles.

So when opening the dialog, we need to bind click events on the overlay. We could give it an ID or a certain class to be able to query it, or we could give it a data attribute. I tend to favor these for behavior hooks. Let’s modify our HTML accordingly:

<div id="my-dialog" hidden>   <div data-dialog-hide></div>   <div>This will be a dialog.</div> </div>

Now, we can query the elements with the data-dialog-hide attribute within the dialog and give them a click listener that hides the dialog.

constructor (element) {   // … rest of the code   // Bind our methods so they can be used in event listeners without losing the   // reference to the dialog instance   this._show = this.show.bind(this)   this._hide = this.hide.bind(this)    const closers = [...this.element.querySelectorAll('[data-dialog-hide]')]   closers.forEach(closer => closer.addEventListener('click', this._hide)) }

The nice thing about having something quite generic like this is that we can use the same thing for the close button of the dialog as well.

<div id="my-dialog" hidden>   <div data-dialog-hide></div>   <div>     This will be a dialog.     <button type="button" data-dialog-hide>Close</button>   </div> </div>

Closing With Escape

Not only should the dialog be hidden when clicking outside of it, but it also should be hidden when pressing Esc. When opening the dialog, we can bind a keyboard listener to the document, and remove it when closing it. This way, it only listens to key presses while the dialog is open instead of all the time.

show() {   // … rest of the code   // Note: `_handleKeyDown` is the bound method, like we did for `_show`/`_hide`   document.addEventListener('keydown', this._handleKeyDown) }  hide() {   // … rest of the code   // Note: `_handleKeyDown` is the bound method, like we did for `_show`/`_hide`   document.removeEventListener('keydown', this._handleKeyDown) }  handleKeyDown(event) {   if (event.key === 'Escape') this.hide() }

Trapping Focus

Now that’s the good stuff. Trapping the focus within the dialog is kind of at the essence of the whole thing, and has to be the most complicated part (although probably not as complicated as you might think).

The idea is pretty simple: when the dialog is open, we listen for Tab presses. If pressing Tab on the last focusable element of the dialog, we programmatically move the focus to the first. If pressing Shift + Tab on the first focusable element of the dialog, we move it to the last one.

The function might look like this:

function trapTabKey(node, event) {   const focusableChildren = getFocusableChildren(node)   const focusedItemIndex = focusableChildren.indexOf(document.activeElement)   const lastIndex = focusableChildren.length - 1   const withShift = event.shiftKey    if (withShift && focusedItemIndex === 0) {     focusableChildren[lastIndex].focus()     event.preventDefault()   } else if (!withShift && focusedItemIndex === lastIndex) {     focusableChildren[0].focus()     event.preventDefault()   } }

The next thing we need to figure out is how to get all the focusable elements of the dialog (getFocusableChildren). We need to query all the elements that can theoretically be focusable, and then we need to make sure they effectively are.

The first part can be done with focusable-selectors. It’s a teeny tiny package I wrote which provides this array of selectors:

module.exports = [   'a[href]:not([tabindex^="-"])',   'area[href]:not([tabindex^="-"])',   'input:not([type="hidden"]):not([type="radio"]):not([disabled]):not([tabindex^="-"])',   'input[type="radio"]:not([disabled]):not([tabindex^="-"]):checked',   'select:not([disabled]):not([tabindex^="-"])',   'textarea:not([disabled]):not([tabindex^="-"])',   'button:not([disabled]):not([tabindex^="-"])',   'iframe:not([tabindex^="-"])',   'audio[controls]:not([tabindex^="-"])',   'video[controls]:not([tabindex^="-"])',   '[contenteditable]:not([tabindex^="-"])',   '[tabindex]:not([tabindex^="-"])', ]

And this is enough to get you 99% there. We can use these selectors to find all focusable elements, and then we can check every one of them to make sure it is actually visible on screen (and not hidden or something).

import focusableSelectors from 'focusable-selectors'  function isVisible(element) {   return element =>     element.offsetWidth ||     element.offsetHeight ||     element.getClientRects().length }  function getFocusableChildren(root) {   const elements = [...root.querySelectorAll(focusableSelectors.join(','))]    return elements.filter(isVisible) }

We can now update our handleKeyDown method:

handleKeyDown(event) {   if (event.key === 'Escape') this.hide()   else if (event.key === 'Tab') trapTabKey(this.element, event) }

Maintaining Focus

One thing that’s often overlooked when creating accessible dialogs is making sure the focus remains within the dialog even after the page has lost focus. Think of it this way: what happens if once the dialog is open? We focus the URL bar of the browser, and then start tabbing again. Our focus trap is not going to work, since it only preserves the focus within the dialog when it’s inside the dialog to begin with.

To fix that problem, we can bind a focus listener to the <body> element when the dialog is shown, and move the focus to the first focusable element within the dialog.

show () {   // … rest of the code   // Note: `_maintainFocus` is the bound method, like we did for `_show`/`_hide`   document.body.addEventListener('focus', this._maintainFocus, true) }  hide () {   // … rest of the code   // Note: `_maintainFocus` is the bound method, like we did for `_show`/`_hide`   document.body.removeEventListener('focus', this._maintainFocus, true) }  maintainFocus(event) {   const isInDialog = event.target.closest('[aria-modal="true"]')   if (!isInDialog) this.moveFocusIn() }  moveFocusIn () {   const target =     this.element.querySelector('[autofocus]') ||     getFocusableChildren(this.element)[0]    if (target) target.focus() }

Which element to focus when opening the dialog is not enforced, and it could depend on which type of content the dialog displays. Generally speaking, there are a couple of options:

  • Focus the first element.
    This is what we do here, since it is made easier by the fact that we already have a getFocusableChildren function.
  • Focus the close button.
    This is also a good solution, especially if the button is absolutely positioned relatively to the dialog. We can conveniently make this happen by placing our close button as the first element of our dialog. If the close button lives in the flow of the dialog content, at the very end, it could be a problem if the dialog has a lot of content (and therefore is scrollable), as it would scroll the content to the end on open.
  • Focus the dialog itself.
    This is not very common among dialog libraries, but it should also work (although it would require adding tabindex="-1" to it so that’s possible since a <div> element is not focusable by default).

Note that we check whether there is an element with the autofocus HTML attribute within the dialog, in which case we would move the focus to it instead of the first item.

Restoring Focus

We’ve managed to successfully trap the focus within the dialog, but we forgot to move the focus inside the dialog once it opens. Similarly, we need to restore the focus back to the element that had it before the dialog was open.

When showing the dialog, we can start by keeping a reference to the element that has the focus (document.activeElement). Most of the time, this will be the button that was interacted with to open the dialog, but in rare cases where a dialog is opened programmatically, it could be something else.

show() {   this.previouslyFocused = document.activeElement   // … rest of the code   this.moveFocusIn() }

When hiding the dialog, we can move the focus back to that element. We guard it with a condition to avoid a JavaScript error if the element somehow no longer exists (or if it was a SVG):

hide() {   // … rest of the code   if (this.previouslyFocused && this.previouslyFocused.focus) {     this.previouslyFocused.focus()   } }

Giving An Accessible Name

It is important our dialog has an accessible name, which is how it will be listed in the accessibility tree. There are a couple of ways to address it, one of which is to define a name in the aria-label attribute, but aria-label has issues.

Another way is to have a title within our dialog (whether hidden or not), and to associate our dialog to it with the aria-labelledby attribute. It might look like this:

<div id="my-dialog" hidden aria-labelledby="my-dialog-title">   <div data-dialog-hide></div>   <div>     <h1 id="my-dialog-title">My dialog title</h1>     This will be a dialog.     <button type="button" data-dialog-hide>Close</button>   </div> </div>

I guess we could make our script apply this attribute dynamically based on the presence of the title and whatnot, but I’d say this is just as easily solved by authoring proper HTML, to begin with. No need to add JavaScript for that.

Handling Custom Events

What if we want to react to the dialog being open? Or closed? There is currently no way to do it, but adding a small event system should not be too difficult. We need a function to register events (let’s call it .on(..)), and a function to unregister them (.off(..)).

class Dialog {   constructor(element) {     this.events = { show: [], hide: [] }   }   on(type, fn) {     this.events[type].push(fn)   }   off(type, fn) {     const index = this.events[type].indexOf(fn)     if (index > -1) this.events[type].splice(index, 1)   } }

Then when showing and hiding the method, we’ll call all functions that have been registered for that particular event.

class Dialog {   show() {     // … rest of the code     this.events.show.forEach(event => event())   }    hide() {     // … rest of the code     this.events.hide.forEach(event => event())   } }

Cleaning Up

We might want to provide a method to clean up a dialog in case we’re done using it. It would be responsible for unregistering event listeners so they don’t last more than they should.

class Dialog {   destroy() {     const closers = [...this.element.querySelectorAll('[data-dialog-hide]')]     closers.forEach(closer => closer.removeEventListener('click', this._hide))      this.events.show.forEach(event => this.off('show', event))     this.events.hide.forEach(event => this.off('hide', event))   } }

Bringing It All Together 

import focusableSelectors from 'focusable-selectors'  class Dialog {   constructor(element) {     this.element = element     this.events = { show: [], hide: [] }      this._show = this.show.bind(this)     this._hide = this.hide.bind(this)     this._maintainFocus = this.maintainFocus.bind(this)     this._handleKeyDown = this.handleKeyDown.bind(this)      element.setAttribute('hidden', true)     element.setAttribute('role', 'dialog')     element.setAttribute('aria-modal', true)      const closers = [...element.querySelectorAll('[data-dialog-hide]')]     closers.forEach(closer => closer.addEventListener('click', this._hide))   }    show() {     this.isShown = true     this.previouslyFocused = document.activeElement     this.element.removeAttribute('hidden')      this.moveFocusIn()      document.addEventListener('keydown', this._handleKeyDown)     document.body.addEventListener('focus', this._maintainFocus, true)      this.events.show.forEach(event => event())   }    hide() {     if (this.previouslyFocused && this.previouslyFocused.focus) {       this.previouslyFocused.focus()     }      this.isShown = false     this.element.setAttribute('hidden', true)      document.removeEventListener('keydown', this._handleKeyDown)     document.body.removeEventListener('focus', this._maintainFocus, true)      this.events.hide.forEach(event => event())   }    destroy() {     const closers = [...this.element.querySelectorAll('[data-dialog-hide]')]     closers.forEach(closer => closer.removeEventListener('click', this._hide))      this.events.show.forEach(event => this.off('show', event))     this.events.hide.forEach(event => this.off('hide', event))   }    on(type, fn) {     this.events[type].push(fn)   }    off(type, fn) {     const index = this.events[type].indexOf(fn)     if (index > -1) this.events[type].splice(index, 1)   }    handleKeyDown(event) {     if (event.key === 'Escape') this.hide()     else if (event.key === 'Tab') trapTabKey(this.element, event)   }    moveFocusIn() {     const target =       this.element.querySelector('[autofocus]') ||       getFocusableChildren(this.element)[0]      if (target) target.focus()   }    maintainFocus(event) {     const isInDialog = event.target.closest('[aria-modal="true"]')     if (!isInDialog) this.moveFocusIn()   } }  function trapTabKey(node, event) {   const focusableChildren = getFocusableChildren(node)   const focusedItemIndex = focusableChildren.indexOf(document.activeElement)   const lastIndex = focusableChildren.length - 1   const withShift = event.shiftKey    if (withShift && focusedItemIndex === 0) {     focusableChildren[lastIndex].focus()     event.preventDefault()   } else if (!withShift && focusedItemIndex === lastIndex) {     focusableChildren[0].focus()     event.preventDefault()   } }  function isVisible(element) {   return element =>     element.offsetWidth ||     element.offsetHeight ||     element.getClientRects().length }  function getFocusableChildren(root) {   const elements = [...root.querySelectorAll(focusableSelectors.join(','))]    return elements.filter(isVisible) }

Wrapping Up

That was quite something, but we eventually got there! Once again, I would advise against rolling out your own dialog library since it’s not the most straightforward and errors could be highly problematic for assistive technology users. But at least now you know how it works under the hood!

If you need to use dialogs in your project, consider using one of the following solutions (kind reminder that we have our comprehensive list of accessible components as well):

Here are more things that could be added but were not for sake of simplicity:

Articles on Smashing Magazine — For Web Designers And Developers

24 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

24 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

23 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

23 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

23 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

23 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

22 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

22 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

21 May

Building A Rich Text Editor (WYSIWYG) From Scratch

by TBSCategories: News

In recent years, the field of Content Creation and Representation on Digital platforms has seen a massive disruption. The widespread success of products like Quip, Google Docs and Dropbox Paper has shown how companies are racing to build the best experience for content creators in the enterprise domain and trying to find innovative ways of breaking the traditional moulds of how content is shared and consumed. Taking advantage of the massive outreach of social media platforms, there is a new wave of independent content creators using platforms like Medium to create content and share it with their audience.

As so many people from different professions and backgrounds try to create content on these products, it’s important that these products provide a performant and seamless experience of content creation and have teams of designers and engineers who develop some level of domain expertise over time in this space. With this article, we try to not only lay the foundation of building an editor but also give the readers a glimpse into how little nuggets of functionalities when brought together can create a great user experience for a content creator.

Understanding The Document Structure

Before we dive into building the editor, let’s look at how a document is structured for a Rich Text Editor and what are the different types of data structures involved.

Document Nodes

Document nodes are used to represent the contents of the document. The common types of nodes that a rich-text document could contain are paragraphs, headings, images, videos, code-blocks and pull-quotes. Some of these may contain other nodes as children inside them (e.g. Paragraph nodes contain text nodes inside them). Nodes also hold any properties specific to the object they represent that are needed to render those nodes inside the editor. (e.g. Image nodes contain an image src property, Code-blocks may contain a language property and so on).

There are largely two types of nodes that represent how they should be rendered –

  • Block Nodes (analogous to HTML concept of Block-level elements) that are each rendered on a new line and occupy the available width. Block nodes could contain other block nodes or inline nodes inside them. An observation here is that the top-level nodes of a document would always be block nodes.
  • Inline Nodes (analogous to HTML concept of Inline elements) that start rendering on the same line as the previous node. There are some differences in how inline elements are represented in different editing libraries. SlateJS allows for inline elements to be nodes themselves. DraftJS, another popular Rich Text Editing library, lets you use the concept of Entities to render inline elements. Links and Inline Images are examples of Inline nodes.
  • Void Nodes — SlateJS also allows this third category of nodes that we will use later in this article to render media.

If you want to learn more about these categories, SlateJS’s documentation on Nodes is a good place to start.

Attributes

Similar to HTML’s concept of attributes, attributes in a Rich Text Document are used to represent non-content properties of a node or it’s children. For instance, a text node can have character-style attributes that tell us whether the text is bold/italic/underlined and so on. Although this article represents headings as nodes themselves, another way to represent them could be that nodes have paragraph-styles (paragraph & h1-h6) as attributes on them.

Below image gives an example of how a document’s structure (in JSON) is described at a more granular level using nodes and attributes highlighting some of the elements in the structure to the left.

Some of the things worth calling out here with the structure are:

  • Text nodes are represented as {text: 'text content'}
  • Properties of the nodes are stored directly on the node (e.g. url for links and caption for images)
  • SlateJS-specific representation of text attributes breaks the text nodes to be their own nodes if the character style changes. Hence, the text ‘Duis aute irure dolor’ is a text node of it’s own with bold: true set on it. Same is the case with the italic, underline and code style text in this document.

Locations And Selection

When building a rich text editor, it is crucial to have an understanding of how the most granular part of a document (say a character) can be represented with some sort of coordinates. This helps us navigate the document structure at runtime to understand where in the document hierarchy we are. Most importantly, location objects give us a way to represent user selection which is quite extensively used to tailor the user experience of the editor in real time. We will use selection to build our toolbar later in this article. Examples of these could be:

  • Is the user’s cursor currently inside a link, maybe we should show them a menu to edit/remove the link?
  • Has the user selected an image? Maybe we give them a menu to resize the image.
  • If the user selects certain text and hits the DELETE button, we determine what user’s selected text was and remove that from the document.

SlateJS’s document on Location explains these data structures extensively but we go through them here quickly as we use these terms at different instances in the article and show an example in the diagram that follows.

  • Path
    Represented by an array of numbers, a path is the way to get to a node in the document. For instance, a path [2,3] represents the 3rd child node of the 2nd node in the document.
  • Point
    More granular location of content represented by path + offset. For instance, a point of {path: [2,3], offset: 14} represents the 14th character of the 3rd child node inside the 2nd node of the document.
  • Range
    A pair of points (called anchor and focus) that represent a range of text inside the document. This concept comes from Web’s Selection API where anchor is where user’s selection began and focus is where it ended. A collapsed range/selection denotes where anchor and focus points are the same (think of a blinking cursor in a text input for instance).

As an example let’s say that the user’s selection in our above document example is ipsum:

The user’s selection can be represented as: 

{   anchor: {path: [2,0], offset: 5}, /0th text node inside the paragraph node which itself is index 2 in the document/   focus: {path: [2,0], offset: 11}, // space + 'ipsum' }`

Setting Up The Editor

In this section, we are going to set up the application and get a basic rich-text editor going with SlateJS. The boilerplate application would be create-react-app with SlateJS dependencies added to it. We are building the UI of the application using components from react-bootstrap. Let’s get started!

Create a folder called wysiwyg-editor and run the below command from inside the directory to set up the react app. We then run a yarn start command that should spin up the local web server (port defaulting to 3000) and show you a React welcome screen.

npx create-react-app . yarn start

We then move on to add the SlateJS dependencies to the application.

yarn add slate slate-react

slate is SlateJS’s core package and slate-react includes the set of React components we will use to render Slate editors. SlateJS exposes some more packages organized by functionality one might consider adding to their editor.

We first create a utils folder that holds any utility modules we create in this application. We start with creating an ExampleDocument.js that returns a basic document structure that contains a paragraph with some text. This module looks like below:

const ExampleDocument = [   {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },     ],   }, ];  export default ExampleDocument;

We now add a folder called components that will hold all our React components and do the following:

  • Add our first React component Editor.js to it. It only returns a div for now.
  • Update the App.js component to hold the document in its state which is initialized to our ExampleDocument above.
  • Render the Editor inside the app and pass the document state and an onChange handler down to the Editor so our document state is updated as the user updates it.
  • We use React bootstrap’s Nav components to add a navigation bar to the application as well.

App.js component now looks like below:

import Editor from './components/Editor';  function App() {   const [document, updateDocument] = useState(ExampleDocument);    return (     <>       <Navbar bg="dark" variant="dark">         <Navbar.Brand href="#">           <img             alt=""             src="/app-icon.png"             width="30"             height="30"             className="d-inline-block align-top"           />{" "}           WYSIWYG Editor         </Navbar.Brand>       </Navbar>       <div className="App">         <Editor document={document} onChange={updateDocument} />       </div>     </>   );

Inside the Editor component, we then instantiate the SlateJS editor and hold it inside a useMemo so that the object doesn’t change in between re-renders. 

// dependencies imported as below. import { withReact } from "slate-react"; import { createEditor } from "slate";  const editor = useMemo(() => withReact(createEditor()), []);

createEditor gives us the SlateJS editor instance which we use extensively through the application to access selections, run data transformations and so on. withReact is a SlateJS plugin that adds React and DOM behaviors to the editor object. SlateJS Plugins are Javascript functions that receive the editor object and attach some configuration to it. This allows web developers to add configurations to their SlateJS editor instance in a composable way.

We now import and render <Slate /> and <Editable /> components from SlateJS with the document prop we get from App.js. Slate exposes a bunch of React contexts we use to access in the application code. Editable is the component that renders the document hierarchy for editing. Overall, the Editor.js module at this stage looks like below:

import { Editable, Slate, withReact } from "slate-react";  import { createEditor } from "slate"; import { useMemo } from "react";  export default function Editor({ document, onChange }) {   const editor = useMemo(() => withReact(createEditor()), []);   return (     <Slate editor={editor} value={document} onChange={onChange}>       <Editable />     </Slate>   ); }

At this point, we have necessary React components added and the editor populated with an example document. Our Editor should be now set up allowing us to type in and change the content in real time — as in the screencast below.

Character Styles

Similar to renderElement, SlateJS gives out a function prop called renderLeaf that can be used to customize rendering of the text nodes (Leaf referring to text nodes which are the leaves/lowest level nodes of the document tree). Following the example of renderElement, we write an implementation for renderLeaf.

export default function useEditorConfig(editor) {   return { renderElement, renderLeaf }; }  // ... function renderLeaf({ attributes, children, leaf }) {   let el = <>{children}</>;    if (leaf.bold) {     el = <strong>{el}</strong>;   }    if (leaf.code) {     el = <code>{el}</code>;   }    if (leaf.italic) {     el = <em>{el}</em>;   }    if (leaf.underline) {     el = <u>{el}</u>;   }    return <span {...attributes}>{el}</span>; }

An important observation of the above implementation is that it allows us to respect HTML semantics for character styles. Since renderLeaf gives us access to the text node leaf itself, we can customize the function to implement a more customized rendering. For instance, you might have a way to let users choose a highlightColor for text and check that leaf property here to attach the respective styles.

We now update the Editor component to use the above, the ExampleDocument to have a few text nodes in the paragraph with combinations of these styles and verify that they are rendered as expected in the Editor with the semantic tags we used.

# src/components/Editor.js  const { renderElement, renderLeaf } = useEditorConfig(editor);  return (     ...     <Editable renderElement={renderElement} renderLeaf={renderLeaf} /> ); 
# src/utils/ExampleDocument.js  {     type: "paragraph",     children: [       { text: "Hello World! This is my paragraph inside a sample document." },       { text: "Bold text.", bold: true, code: true },       { text: "Italic text.", italic: true },       { text: "Bold and underlined text.", bold: true, underline: true },       { text: "variableFoo", code: true },     ],   },

Adding A Toolbar

Let’s begin by adding a new component Toolbar.js to which we add a few buttons for character styles and a dropdown for paragraph styles and we wire these up later in the section. 

const PARAGRAPH_STYLES = ["h1", "h2", "h3", "h4", "paragraph", "multiple"]; const CHARACTER_STYLES = ["bold", "italic", "underline", "code"];  export default function Toolbar({ selection, previousSelection }) {   return (     <div className="toolbar">       {/* Dropdown for paragraph styles */}       <DropdownButton         className={"block-style-dropdown"}         disabled={false}         id="block-style"         title={getLabelForBlockStyle("paragraph")}       >         {PARAGRAPH_STYLES.map((blockType) => (           <Dropdown.Item eventKey={blockType} key={blockType}>             {getLabelForBlockStyle(blockType)}           </Dropdown.Item>         ))}       </DropdownButton>       {/* Buttons for character styles */}       {CHARACTER_STYLES.map((style) => (         <ToolBarButton           key={style}           icon={<i className={`bi $  {getIconForButton(style)}`} />}           isActive={false}         />       ))}     </div>   ); }  function ToolBarButton(props) {   const { icon, isActive, ...otherProps } = props;   return (     <Button       variant="outline-primary"       className="toolbar-btn"       active={isActive}       {...otherProps}     >       {icon}     </Button>   ); }

We abstract away the buttons to the ToolbarButton component that is a wrapper around the React Bootstrap Button component. We then render the toolbar above the Editable inside Editor component and verify that the toolbar shows up in the application.

Here are the three key functionalities we need the toolbar to support:

  1. When the user’s cursor is in a certain spot in the document and they click one of the character style buttons, we need to toggle the style for the text they may type next.
  2. When the user selects a range of text and click one of the character style buttons, we need to toggle the style for that specific section.
  3. When the user selects a range of text, we want to update the paragraph-style dropdown to reflect the paragraph-type of the selection. If they do select a different value from the selection, we want to update the paragraph style of the entire selection to be what they selected.

Let’s look at how these functionalities work on the Editor before we start implementing them.

Adding A Link Button To The Toolbar

Let’s add a Link Button to the toolbar that enables the user to do the following:

  • Selecting some text and clicking on the button converts that text into a link
  • Having a blinking cursor (collapsed selection) and clicking the button inserts a new link there
  • If the user’s selection is inside a link, clicking on the button should toggle the link — meaning convert the link back to text.

To build these functionalities, we need a way in the toolbar to know if the user’s selection is inside a link node. We add a util function that traverses the levels in upward direction from the user’s selection to find a link node if there is one, using Editor.above helper function from SlateJS.

# src/utils/EditorUtils.js  export function isLinkNodeAtSelection(editor, selection) {   if (selection == null) {     return false;   }    return (     Editor.above(editor, {       at: selection,       match: (n) => n.type === "link",     }) != null   ); }

Now, let’s add a button to the toolbar that is in active state if the user’s selection is inside a link node.

# src/components/Toolbar.js  return (     <div className="toolbar">       ...       {/* Link Button */}       <ToolBarButton         isActive={isLinkNodeAtSelection(editor, editor.selection)}         label={<i className={`bi $  {getIconForButton("link")}`} />}       />     </div>   );

If we had to do this by ourselves, we’d have to figure out the range of selection and create three new nodes (text, link, text) that replace the original text node. SlateJS has a helper function called Transforms.wrapNodes that does exactly this — wrap nodes at a location into a new container node. We also have a helper available for the reverse of this process — Transforms.unwrapNodes which we use to remove links from selected text and merge that text back into the text nodes around it. With that, toggleLinkAtSelection has the below implementation to insert a new link at an expanded selection.

# src/utils/EditorUtils.js  export function toggleLinkAtSelection(editor) {   if (!isLinkNodeAtSelection(editor, editor.selection)) {     const isSelectionCollapsed =       Range.isCollapsed(editor.selection);     if (isSelectionCollapsed) {       Transforms.insertNodes(         editor,         {           type: "link",           url: '#',           children: [{ text: 'link' }],         },         { at: editor.selection }       );     } else {       Transforms.wrapNodes(         editor,         { type: "link", url: '#', children: [{ text: '' }] },         { split: true, at: editor.selection }       );     }   } else {     Transforms.unwrapNodes(editor, {       match: (n) => Element.isElement(n) && n.type === "link",     });   } }

If the selection is collapsed, we insert a new node there with Transform.insertNodes that inserts the node at the given location in the document. We wire this function up with the toolbar button and should now have a way to add/remove links from the document with the help of the link button.

# src/components/Toolbar.js       <ToolBarButton         ...         isActive={isLinkNodeAtSelection(editor, editor.selection)}                onMouseDown={() => toggleLinkAtSelection(editor)}       />

If the text ’ABCDE’ was the first text node of the first paragraph in the document, our point values would be — 

cursorPoint = { path: [0,0], offset: 5} startPointOfLastCharacter = { path: [0,0], offset: 4}

If the last character was a space, we know where it started — startPointOfLastCharacter.Let’s move to step-2 where we move backwards character-by-character until either we find another space or the start of the text node itself. 

...    if (lastCharacter !== " ") {     return;   }    let end = startPointOfLastCharacter;   start = Editor.before(editor, end, {     unit: "character",   });    const startOfTextNode = Editor.point(editor, currentNodePath, {     edge: "start",   });    while (     Editor.string(editor, Editor.range(editor, start, end)) !== " " &&     !Point.isBefore(start, startOfTextNode)   ) {     end = start;     start = Editor.before(editor, end, { unit: "character" });   }    const lastWordRange = Editor.range(editor, end, startPointOfLastCharacter);   const lastWord = Editor.string(editor, lastWordRange);

Here is a diagram that shows where these different points point to once we find the last word entered to be ABCDE.

Note that start and end are the points before and after the space there. Similarly, startPointOfLastCharacter and cursorPoint are the points before and after the space user just inserted. Hence [end,startPointOfLastCharacter] gives us the last word inserted.

We log the value of lastWord to the console and verify the values as we type.

Now let’s focus on caption-editing. The way we want this to be a seamless experience for the user is that when they click on the caption, we show a text input where they can edit the caption. If they click outside the input or hit the RETURN key, we treat that as a confirmation to apply the caption. We then update the caption on the image node and switch the caption back to read mode. Let’s see it in action so we have an idea of what we’re building.

Let’s update our Image component to have a state for caption’s read-edit modes. We update the local caption state as the user updates it and when they click out (onBlur) or hit RETURN (onKeyDown), we apply the caption to the node and switch to read mode again.

const Image = ({ attributes, children, element }) => {   const [isEditingCaption, setEditingCaption] = useState(false);   const [caption, setCaption] = useState(element.caption);   ...    const applyCaptionChange = useCallback(     (captionInput) => {       const imageNodeEntry = Editor.above(editor, {         match: (n) => n.type === "image",       });       if (imageNodeEntry == null) {         return;       }        if (captionInput != null) {         setCaption(captionInput);       }        Transforms.setNodes(         editor,         { caption: captionInput },         { at: imageNodeEntry[1] }       );     },     [editor, setCaption]   );    const onCaptionChange = useCallback(     (event) => {       setCaption(event.target.value);     },     [editor.selection, setCaption]   );    const onKeyDown = useCallback(     (event) => {       if (!isHotkey("enter", event)) {         return;       }        applyCaptionChange(event.target.value);       setEditingCaption(false);     },     [applyCaptionChange, setEditingCaption]   );    const onToggleCaptionEditMode = useCallback(     (event) => {       const wasEditing = isEditingCaption;       setEditingCaption(!isEditingCaption);       wasEditing && applyCaptionChange(caption);     },     [editor.selection, isEditingCaption, applyCaptionChange, caption]   );    return (         ...         {isEditingCaption ? (           <Form.Control             autoFocus={true}             className={"image-caption-input"}             size="sm"             type="text"             defaultValue={element.caption}             onKeyDown={onKeyDown}             onChange={onCaptionChange}             onBlur={onToggleCaptionEditMode}           />         ) : (           <div             className={"image-caption-read-mode"}             onClick={onToggleCaptionEditMode}           >             {caption}           </div>         )}       </div>       ...

With that, the caption editing functionality is complete. We now move to adding a way for users to upload images to the editor. Let’s add a toolbar button that lets users select and upload an image.

# src/components/Toolbar.js  const onImageSelected = useImageUploadHandler(editor, previousSelection);  return (     <div className="toolbar">     ....    <ToolBarButton         isActive={false}         as={"label"}         htmlFor="image-upload"         label={           <>             <i className={`bi $  {getIconForButton("image")}`} />             <input               type="file"               id="image-upload"               className="image-upload-input"               accept="image/png, image/jpeg"               onChange={onImageSelected}             />           </>         }       />     </div>

As we work with image uploads, the code could grow quite a bit so we move the image-upload handling to a hook useImageUploadHandler that gives out a callback attached to the file-input element. We’ll discuss shortly about why it needs the previousSelection state.

Before we implement useImageUploadHandler, we’ll set up the server to be able to upload an image to. We setup an Express server and install two other packages — cors and multer that handle file uploads for us. 

yarn add express cors multer

We then add a src/server.js script that configures the Express server with cors and multer and exposes an endpoint /upload which we will upload the image to.

# src/server.js  const storage = multer.diskStorage({   destination: function (req, file, cb) {     cb(null, "./public/photos/");   },   filename: function (req, file, cb) {     cb(null, file.originalname);   }, });  var upload = multer({ storage: storage }).single("photo");  app.post("/upload", function (req, res) {   upload(req, res, function (err) {     if (err instanceof multer.MulterError) {       return res.status(500).json(err);     } else if (err) {       return res.status(500).json(err);     }     return res.status(200).send(req.file);   }); });  app.use(cors()); app.listen(port, () => console.log(`Listening on port $  {port}`));

Now that we have the server setup, we can focus on handling the image upload. When the user uploads an image, it could be a few seconds before the image gets uploaded and we have a URL for it. However, we do what to give the user immediate feedback that the image upload is in progress so that they know the image is being inserted in the editor. Here are the steps we implement to make this behavior work –

  1. Once the user selects an image, we insert an image node at the user’s cursor position with a flag isUploading set on it so we can show the user a loading state.
  2. We send the request to the server to upload the image.
  3. Once the request is complete and we have an image URL, we set that on the image and remove the loading state.

Let’s begin with the first step where we insert the image node. Now, the tricky part here is we run into the same issue with selection as with the link button in the toolbar. As soon as the user clicks on the Image button in the toolbar, the editor loses focus and the selection becomes null. If we try to insert an image, we don’t know where the user’s cursor was. Tracking previousSelection gives us that location and we use that to insert the node.

# src/hooks/useImageUploadHandler.js import { v4 as uuidv4 } from "uuid";  export default function useImageUploadHandler(editor, previousSelection) {   return useCallback(     (event) => {       event.preventDefault();       const files = event.target.files;       if (files.length === 0) {         return;       }       const file = files[0];       const fileName = file.name;       const formData = new FormData();       formData.append("photo", file);        const id = uuidv4();        Transforms.insertNodes(         editor,         {           id,           type: "image",           caption: fileName,           url: null,           isUploading: true,           children: [{ text: "" }],         },         { at: previousSelection, select: true }       );     },     [editor, previousSelection]   ); }

As we insert the new image node, we also assign it an identifier id using the uuid package. We’ll discuss in Step (3)’s implementation why we need that. We now update the image component to use the isUploading flag to show a loading state.

{!element.isUploading && element.url != null ? (    <img src={element.url} alt={caption} className={"image"} /> ) : (    <div className={"image-upload-placeholder"}>         <Spinner animation="border" variant="dark" />    </div> )}

That completes the implementation of step 1. Let’s verify that we are able to select an image to upload, see the image node getting inserted with a loading indicator where it was inserted in the document.

Moving to Step (2), we will use axois library to send a request to the server.

export default function useImageUploadHandler(editor, previousSelection) {   return useCallback((event) => {     ....     Transforms.insertNodes(      …      {at: previousSelection, select: true}     );      axios       .post("/upload", formData, {         headers: {           "content-type": "multipart/form-data",         },       })       .then((response) => {            // update the image node.        })       .catch((error) => {         // Fire another Transform.setNodes to set an upload failed state on the image       });   }, [...]); }

We verify that the image upload works and the image does show up in the public/photos folder of the app. Now that the image upload is complete, we move to Step (3) where we want to set the URL on the image in the resolve() function of the axios promise. We could update the image with Transforms.setNodes but we have a problem — we do not have the path to the newly inserted image node. Let’s see what our options are to get to that image —

  • Can’t we use editor.selection as the selection must be on the newly inserted image node? We cannot guarantee this since while the image was uploading, the user might have clicked somewhere else and the selection might have changed.
  • How about using previousSelection which we used to insert the image node in the first place? For the same reason we can’t use editor.selection, we can’t use previousSelection since it may have changed too.
  • SlateJS has a History module that tracks all the changes happening to the document. We could use this module to search the history and find the last inserted image node. This also isn’t completely reliable if it took longer for the image to upload and the user inserted more images in different parts of the document before the first upload completed.
  • Currently, Transform.insertNodes’s API doesn’t return any information about the inserted nodes. If it could return the paths to the inserted nodes, we could use that to find the precise image node we should update.

Since none of the above approaches work, we apply an id to the inserted image node (in Step (1)) and use the same id again to locate it when the image upload is complete. With that, our code for Step (3) looks like below — 

axios         .post("/upload", formData, {           headers: {             "content-type": "multipart/form-data",           },         })         .then((response) => {           const newImageEntry = Editor.nodes(editor, {             match: (n) => n.id === id,           });            if (newImageEntry == null) {             return;           }            Transforms.setNodes(             editor,             { isUploading: false, url: `/photos/$  {fileName}` },             { at: newImageEntry[1] }           );         })         .catch((error) => {           // Fire another Transform.setNodes to set an upload failure state           // on the image.                 });

With the implementation of all three steps complete, we are ready to test the image upload end to end.

With that, we’ve wrapped up Images for our editor. Currently, we show a loading state of the same size irrespective of the image. This could be a jarring experience for the user if the loading state is replaced by a drastically smaller or bigger image when the upload completes. A good follow up to the upload experience is getting the image dimensions before the upload and showing a placeholder of that size so that transition is seamless. The hook we add above could be extended to support other media types like video or documents and render those types of nodes as well.

Conclusion

In this article, we have built a WYSIWYG Editor that has a basic set of functionalities and some micro user-experiences like link detection, in-place link editing and image caption editing that helped us go deeper with SlateJS and concepts of Rich Text Editing in general. If this problem space surrounding Rich Text Editing or Word Processing interests you, some of the cool problems to go after could be:

  • Collaboration
  • A richer text editing experience that supports text alignments, inline images, copy-paste, changing font and text colors etc.
  • Importing from popular formats like Word documents and Markdown.

If you want to learn more SlateJS, here are some links that might be helpful.

  • SlateJS Examples
    A lot of examples that go beyond the basics and build functionalities that are usually found in Editors like Search & Highlight, Markdown Preview and Mentions.
  • API Docs
    Reference to a lot of helper functions exposed by SlateJS that one might want to keep handy when trying to perform complex queries/transformations on SlateJS objects.

Lastly, SlateJS’s Slack Channel is a very active community of web developers building Rich Text Editing applications using SlateJS and a great place to learn more about the library and get help if needed.

Articles on Smashing Magazine — For Web Designers And Developers

Newer postsOlder posts
×

Powered by WhatsApp Chat

WhatsApp Chat is free, download and try it now here!

× Chat with Us