hubspot / draft-extend

Build extensible Draft.js editors with configurable plugins and integrated serialization.

draft-extend

Build extensible Draft.js editors with configurable plugins and integrated serialization

---

Jump to:

• Overview
• Examples
• Editor
• compose
• Building Plugins

---

Overview

Draft Extend is a platform to build a full-featured Draft.js editor using modular plugins that can integrate with draft-convert to serialize with HTML. The higher-order function API makes it extremely easy to use any number of plugins for rendering and conversion.

Usage:

import React from 'react';
import ReactDOM from 'react-dom';
import {EditorState} from 'draft-js';
import {Editor, compose} from 'draft-extend';
import {convertFromHTML, convertToHTML} from 'draft-convert';

const plugins = compose(
    FirstPlugin,
    SecondPlugin,
    ThirdPlugin
);

const EditorWithPlugins = plugins(Editor); // Rich text editor component with plugin functionality
const toHTML = plugins(convertFromHTML); // function to convert from HTML including plugin functionality
const fromHTML = plugins(convertToHTML); // function to convert to HTML including plugin functionality

const MyEditor = React.createClass({
    getInitialState() {
        return {
            editorState: EditorState.createWithContent(fromHTML('<div></div>'))
        };
    },

    onChange(editorState) {
        const html = toHTML(editorState.getCurrentContent());
        console.log(html); // don't actually convert to HTML on every change!
        this.setState({editorState});
    },

    render() {
        return (
            <EditorWithPlugins
                editorState={this.state.editorState}
                onChange={this.onChange}
            />
        );
    }
});

ReactDOM.render(
    <MyEditor />,
    document.querySelector('.app')
);

---

Examples

Examples of how to build plugins of different types are included in the example directory. To run the examples locally:

1. run npm install in the draft-extend directory
2. open any HTML file in the examples directory in your web browser - no local server is necessary

---

Editor

Editor component on which to extend functionality with plugins created by createPlugin.

Props

The most important two props are:

• editorState - Draft.js EditorState instance to be rendered.
• onChange: function(editorState: EditorState): void - Like with vanilla Draft.js, function called on any editor change passing the EditorState.

Other props are used by plugins composed around Editor. See Building Plugins for more information. These should generally not be used outside of the context of a plugin:

• buttons: Array<Component> Array of React components to add to the controls of the editor.
• overlays: Array<Component> Array of React components to add as overlays to the editor.
• decorators: Array<DraftDecorator> Array of Draft.js decorator objects used to render the EditorState. They are added to the EditorState as a CompositeDecorator within the component and are of shape {strategy, component}.
• baseDecorator: DraftDecoratorType Replacement decorator object to override the built-in CompositeDecorator's behavior. See the "Beyond CompositeDecorator" section on this page of the Draft.js docs for more information.
• styleMap: Object Object map from Draft.js inline style type to style object. Used for the Draft.js Editor's customStyleMap prop.

All other props are passed down to the Draft.js Editor component and to any buttons and overlays added by plugins.

---

compose

Since the API of plugins is based around composition, a basic compose function is provided to make it easy to apply plugins to the component as well as conversion functions and provides a single source of truth for plugin configuration.

// without compose
const EditorWithPlugins = FirstPlugin(SecondPlugin(ThirdPlugin(Editor)));
const fromHTML = FirstPlugin(SecondPlugin(ThirdPlugin(convertFromHTML)));
const toHTML = FirstPlugin(SecondPlugin(ThirdPlugin(convertToHTML)));

// with compose
const plugins = compose(
    FirstPlugin,
    SecondPlugin,
    ThirdPlugin
);

const EditorWithPlugins = plugins(Editor);
const toHTML = plugins(convertToHTML);
const fromHTML = plugins(convertFromHTML);

---

KeyCommandController

Higher-order component to consolidate key command listeners across the component tree

An increasingly common pattern for rich text editors is a toolbar detached from the main Editor component. This toolbar will be outside of the Editor component subtree, but will often need to respond to key commands that would otherwise be encapsulated by the Editor. KeyCommandController is a higher-order component that allows the subscription to key commands to move up the React tree so that components outside that subtree may listen and emit changes to editor state. KeyCommandController. It may be used with any component, but a good example is the Toolbar component:

import {Editor, Toolbar, KeyCommandController, compose} from 'draft-extend';

const plugins = compose(
  FirstPlugin,
  SecondPlugin
);

const WrappedEditor = plugins(Editor);
const WrappedToolbar = plugins(Toolbar);

const Parent = ({editorState, onChange, handleKeyCommand, addKeyCommandListener, removeKeyCommandListener}) => {
  return (
    <div>
      <WrappedEditor
        editorState={editorState}
        onChange={onChange}
        handleKeyCommand={handleKeyCommand}
        addKeyCommandListener={addKeyCommandListener}
        removeKeyCommandListener={removeKeyCommandListener}
      />
      <WrappedToolbar
        editorState={editorState}
        onChange={onChange}
        addKeyCommandListener={addKeyCommandListener}
        removeKeyCommandListener={removeKeyCommandListener}
      />
    </div>
  );
};

export default KeyCommandController(Parent);

KeyCommandController provides the final handleKeyCommand to use in the Editor component as well as subscribe/unsubscribe functions. As long as these props are passed from some common parent wrapped with KeyCommandController that also receives editorState and onChange props, other components may subscribe and emit chagnes to the editor state.

Additionally, KeyCommandControllers are composable and will defer to the highest parent instance. That is, if a KeyCommandController receives handleKeyCommand, addKeyCommandListener, and removeKeyCommandListener props (presumably from another controller) it will delegate to that controller's record of subscribed functions, keeping all listeners in one place.

draft-extend's Issues

Update docs and examples to use the draft-js v0.10 API

Examples and documentation still use the draft-js v0.9 API for creating entities (Entity.create and Entity.get).

We should migrate these examples to the v0.10 API as we move apps forward to the latest version!

• https://github.com/HubSpot/draft-extend/blob/master/building-plugins.md
• https://github.com/HubSpot/draft-extend/blob/master/example/link.html#L55
• https://github.com/HubSpot/draft-extend/blob/master/example/token.html#L81
• https://github.com/HubSpot/draft-extend/blob/master/example/mention.html#L99
• https://github.com/HubSpot/draft-extend/blob/master/src/plugins/utils.js#L38

Plugins should have a chance to handle key commands before editor

With the current implementation, plugins don't receive an event if the same event is handle by the editor.

I'm trying to select a component with return from a menu in an overlay but since I also handle return in my editor, the overlay never gets the event. My current solution is to track when the overlay is active.

The change to let the plugins handle the event first seems straight forward but I wanted to make sure I'm not missing something before submitting a PR

Thank you

Shed create-react-class dependency

As much as I prefer the factory function style of creating components, we should get rid of this dependency. Follow up to #23

Deprecation warnings about key binding props after upgrading to draft-js 0.11.1

After upgrading to draft-js 0.11.1, the following deprecation warnings appear in the console:

Supplying an `onDownArrow` prop to `DraftEditor` has been deprecated. If your handler needs access to the keyboard event, supply a custom `keyBindingFn` prop that falls back to the default one (eg. https://is.gd/RG31RJ). 
    in DraftEditor (created by EditorWrapper)
    in EditorWrapper (created by KeyCommandController(EditorWrapper))
    in KeyCommandController(EditorWrapper) (created by Anonymous)
    ...

Supplying an `onEscape` prop to `DraftEditor` has been deprecated. If your handler needs access to the keyboard event, supply a custom `keyBindingFn` prop that falls back to the default one (eg. https://is.gd/RG31RJ). 

Supplying an `onTab` prop to `DraftEditor` has been deprecated. If your handler needs access to the keyboard event, supply a custom `keyBindingFn` prop that falls back to the default one (eg. https://is.gd/RG31RJ). 

Supplying an `onUpArrow` prop to `DraftEditor` has been deprecated. If your handler needs access to the keyboard event, supply a custom `keyBindingFn` prop that falls back to the default one (eg. https://is.gd/RG31RJ). 

It looks like the default key bindings have changed and the convenience on* handlers have been deprecated.

Middleware swallowing errors

For a while, I was seeing this cryptic error message:

After a bit of digging, I found that I had an error in my textToEntity middleware that was getting swallowed by the middleware handler, I assume here:

draft-extend/src/util/middlewareAdapter.js

Line 70 in 7eab602

} catch (e) {

I've worked around this for now by wrapping the contents of my middleware with a try/catch and logging the error.

Support editorClassName

We'd like to be able to target the draft-extend-editor in our styling, but are concerned about styling a class name that we didn't provide. We would like the draft extend editor to take in an editorClassName prop which is applied to the draft-extend-editor node, so that we can provide a className to style.

cc @bent0b0x

See LiveMessagesUI pull #2847 on the HubSpot internal git for futher context.

Errors during installation

I'm seeing errors during installation npm install. It's showing that 'BABEL_ENV' is not recognized when it starts 'build:commonjs' script.
npm-debug.log

example of overlay

Could you give an usage example of the overlay feature?

I dont see anything after opening the html page on the browser.

I followed the documentation but no editor comes up.

Entity.create deprecated

I'm seeing the following warnings using the example textToEntity middleware:

DraftEntity.js:35 WARNING: DraftEntity.create will be deprecated soon!
Please use "contentState.createEntity" instead.