@warren-bank/react-trix-editor

react-trix-editor

React component for Basecamp's Trix rich text editor

Origin story

• I'm adding an HTML editor to Secure-Webmail

  • did a quick survey of what's available:

    library	size (min+gzip)	size (min)	jquery	bootstrap	react	link
    pell	1.38kB	3.54kB				https://github.com/jaredreich/pell
    squire	16kB	49kB				https://github.com/neilj/Squire
    medium-editor	27kB	105kB				https://github.com/yabwe/medium-editor
    quill	43kB	205kB				https://github.com/quilljs/quill
    trix	47kB	204kB				https://github.com/basecamp/trix
    ckeditor	163kB	551kB				https://ckeditor.com
    trumbowyg	8kB	23kB	x			https://github.com/Alex-D/Trumbowyg
    summernote	26kB	93kB	x	x		https://github.com/summernote/summernote
    draft	46kB	147kB			x	https://github.com/facebook/draft-js
    froala	52kB	186kB	x			https://github.com/froala/wysiwyg-editor
    tinymce	157kB	491kB	x			https://github.com/tinymce/tinymce

  • ruled out the ones that depend on jQuery

  • tried out the rest

    • Trix is the only html editor that could properly generate nested lists

What this is, and what this is not..

• Trix uses a very non-opinionated approach
  • the library provides a lot of low-level events to enable deep customization, but doesn't provide much high-level functionality out-of-the-box
• the purpose of this library is to:
  • provide a React component wrapper around Trix
  • encapsulate all of the customizations that I want for my particular use-case
  • share the result for anyone who has a similar need

Customizations

• file attachments:
  • are NOT uploaded to any server
  • the only files of any interest are images, which are embedded (using a data: URI)
• additional toolbar buttons:
  • Embed an image
    • opens a file-chooser dialog
    • embeds the image(s)
  • Horizontal rule
    • adds an <hr /> tag
• behavior:
  • the editor is a fixed height, and a vertical scrollbar is used (when necessary)
  • the editor automatically scrolls, such that the cursor is visible in the middle of the viewport, when:
    • image(s) are embedded
    • rich text content is pasted into the editor

React props

• set_exportTrixElement
  • Function
• set_exportHTML
  • Function
• set_exportDocument
  • Function
• document
  • Object
• autofocus
  • Boolean
• placeholder
  • String

notes:

• all React props are optional

Anti-Pattern

• set_exportTrixElement
• set_exportHTML
• set_exportDocument
  • these are functions passed to TrixEditor
  • TrixEditor calls these functions when:
    • componentDidMount
    • componentDidUpdate
  • TrixEditor passes a (corresponding) function back to the parent component
    • after the parent component has received a reference to these functions, they can be called to obtain (corresponding) data from the TrixEditor component

specifically:

• set_exportTrixElement is passed a reference to the function: exportTrixElement
  • exportTrixElement returns: the HTMLElement bound to this instance of Trix
• set_exportHTML is passed a reference to the function: exportHTML
  • exportHTML returns: a string of HTML text
• set_exportDocument is passed a reference to the function: exportDocument
  • exportDocument returns: an immutable Object representation of the current state of the document in the editor
    • the data type of this immutable Object is the same as the React prop: document

Installation:

npm install --save @warren-bank/react-trix-editor

Dependencies:

• I chose to not bundle Trix with this component
  • it expects the global: window.Trix
    • this can be satisfied in 1 of 2 ways:
      • include Trix externally
        • example: from a CDN

            <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/trix/1.0.0/trix.css" />
            <script src="https://cdnjs.cloudflare.com/ajax/libs/trix/1.0.0/trix.js"></script>

      • include Trix internally
        • add as a project dependency
        • in the script used as the entry-point for Webpack:

            const Trix = require('trix'); require('trix/dist/trix.css');
            window.Trix = Trix

Demos:

1. include Trix externally
   • run demo
2. include Trix internally
   • run demo

notes:

• both demos are nearly identical; they only differ in the way Trix is included
• in addition to rendering an instance of the TrixEditor component:
  • the App component sets 2 interval timers:
    • every 5 seconds:
      • a reference to the immutable Object representation of the current state of the document in the editor is stored in a class instance property
    • every 1 second:
      • this class instance property is saved to state
      • the TrixEditor component will update only if this.state.document has changed
        • when this does occur:
          • the string of HTML text returned by exportHTML is logged to console
          • the position of the cursor in the editor jumps to the beginning
            • makes the demo(s) annoying to use, but does effectively prove that the feature is working
            • this methodology would never be used in a real app; it's entirely contrived

Legal:

• copyright: Warren Bank
• license: GPL-2.0