Mobiledoc 0.3, Mobiledoc-Kit 0.8.2 released

Haven’t used Mobiledoc-Kit? Try a live demo

Mobiledoc, the easy-to-render and portable document format backing our Mobiledoc-Kit WYSIWYG editor, has landed some exciting changes this weekend. Most of the related libraries have been bumped to a new version:

• Mobiledoc itself, the document specification, has been bumped to 0.3.0. All mobiledoc renderers and the editor kit are compatible with both 0.2.0 and 0.3.0 documents, so upgrading should be painless. Changelog
• Mobiledoc-Kit 0.8.2 is released. Along with support for a great new feature in Mobiledoc 0.3.0, it brings continued improvements in the reliability and consistency of the editing surface.
• mobiledoc-dom-renderer 0.3.0 is released (as is ember-mobiledoc-dom-renderer 0.3.0), with compatibility for the new mobiledoc version and the addition of rendering hooks for section elements.
• mobiledoc-html-renderer has likewise reached 0.3.0 with the same features as the DOM renderer

In these releases we’re extremely pleased to introduce an API for “atoms”, a lightweight inline version of cards that was originally designed and championed by Richard Livsey (@rlivsey). More about this and other features below.

Simplifying Card Definitions

In mobiledoc 0.7.0 we dramatically simplified the card definition API. An idiomatic card definition is now a single render hook.

Render hooks are expected to return a DOM node (or another appropriate type, for example the mobiledoc-text-renderer requires strings be returned). An example:

let card = {
 name: 'simple-image',
 type: 'dom', // different renderers may require different types
 render({env, options, payload}) {
   let src = payload.src || 'https://placehold.it/30x20';
   let img = document.createElement('img');
   img.src = src;
   return img;
 }
};

Teardown for a card can be attached via a callback passed to env.onTeardown. The render hook alone is sufficient for implementations of non-editable cards. Cards passed to Mobiledoc-Kit for use in editing should also implement an edit hook.

See the CARDS.md documentation in Mobiledoc-Kit for more details on how to author a card.

Atoms

Mobiledoc cards define rich content in a block, content that is seamlessly navigable with a cursor and mouse and editable with expected behaviors like copy/paste. A quick example:

Cards can be seen as peers of paragraphs in a document. This makes them easy to reason about as an editor and author of a card.

Atoms are rich content that remains inline. Atoms have text value, a payload, and are implemented with a hook like cards. For example, this is a simple atom definition:

export default {
  name: 'mention',
  type: 'dom',
  render({ env, options, value, payload}) {
    return document.createTextNode(`@${value}`);
  }
};

Users interact with atoms as single-character units. If the cursor is on the right side of an atom and the user taps the left arrow, the cursor will jump over the entire atom.

An example of what interacting with atoms is like:

Like cards or other Mobiledoc content, they can be copied, pasted, highlighted, deleted etc.

For more information about the API for defining an atom, see ATOMS.md in the Mobiledoc-Kit repo.

Improved Browser Compatibility

In 0.7.0 we investigated and confirmed support for the Microsoft Edge browser. In 0.8.2, we’ve also added support for IE11.

The biggest challenge when adapting to IE11 was knowing when to reparse the rendered document DOM. Mobiledoc-Kit often captures user interactions and implements their behavior instead of allowing default browser edits to occur, however there is no way to intercept spelling corrections and drag/dropped content from 3rd party DOM without watching for DOM mutation. Since we began work on Mobiledoc, we’ve use the input event to capure these changes.

Since IE11 does not support input for contentEditable, we’ve refactored Mobiledoc’s reparsing logic to use the MutationObserver API.

Unfortunately MutationObserver is not supported in IE10. This pins the minimum required version for Mobiledoc firmly at IE11.

What’s Next

In the past several weeks we’ve been discussing several goals for the next few weeks:

• The various renderers duplicate a lot of logic. We have ideas on how to reduce this by improving the composability of their APIs and increasing reliance on simple-dom.
• Support for the Accelerated Mobile Pages (AMP) via a Mobiledoc renderer is well underway. AMP is a snap with Mobiledoc, and highlights how important it is to decouple server-persisted content from HTML.
• Mobiledoc still ships some legacy CSS. This can be cleaned up.
• Improving the pasted version of Mobiledoc rich content in 3rd party editors.
• We’re investigating patterns for undo/redo support, with a number of approaches being considered.

For more, follow the project on GitHub or join us in the Gitter chat.

Huge thanks to Bustle Labs for their continued sponsorship of our work on Mobiledoc. We’re having a great time with their smart and fun team here in NYC. Bustle is looking for software engineers and UX designers to join their talented crew.