Using Mobiledoc in Ember applications

I recently discovered Mobiledoc while working on a project that required a custom text editor for creating posts. It is a fantastic solution for anyone looking to edit and display rich content in their application.

The majority of the API documentation focuses on the implementation of Mobiledoc with plain Javascript — one of the benefits of Mobiledoc is that it is framework-agnostic. However, I found myself wanting more examples within the context of an Ember application. This small tutorial outlines what I have learned using Mobiledoc with Ember.

For this demo, I created a basic blog app that lets users add memes and dancing bananas to their posts. The memes are Mobiledoc cards and the dancing bananas are Mobiledoc atoms, both created using Ember components.

Blog app with posts created with Mobiledoc

Let’s get started:

First, install the two addons that are available for using Mobiledoc in Ember applications:

$ ember install ember-mobiledoc-editor
$ ember install ember-mobiledoc-dom-renderer

With these, we essentially get two main components — the editor component and the renderer component.

For this example, we want to include the {{mobiledoc-editor}} component as part of our form for creating new blog posts.

The new post form with {{mobiledoc-editor}} and our custom toolbar component

I’m using the component’s block form which allows me to pass the editor into my own custom toolbar component {{editor-toolbar}}.

The editor addon does provide a basic toolbar component, but it is not as easily customizable. Instead, I combined the smaller provided components {{mobiledoc-markup-button}}, {{mobiledoc-section-button}}, and {{mobiledoc-link-button}} to customize my own toolbar for use in any editor instance. This will also allow me to easily add custom buttons and actions later.

The {{mobiledoc-editor}} component’s on-change attribute accepts an action that will send every time the document within the editor is updated. In this example, we pass an action called mobiledocWasUpdated that will update our controller’s mobiledoc property.

The editor serializes the post into Mobiledoc JSON format, so once the form is submitted, the createPost action will stringify the Mobiledoc object and save it as the post’s body.

Now that we have implemented the editor component within our form to create new blog posts, we need to render the post’s content when we view that post.

Each post’s body is saved and sent to our backend as a JSON string. I added a computed property on the model that returns the parsed mobiledoc object for rendering.

To display each post, I created a component called {{post-view}} that contains the {{render-mobiledoc}} component. We simply need to pass the post’s mobiledoc into the component for it to render to the DOM.

The post’s content will be rendered as individual DOM elements, giving us the the freedom to display and style the content uniquely for different scenarios within an application — a powerful aspect of Mobiledoc.

Now we have basic Mobiledoc editing and rendering working in our app!

Adding cards and atoms

Now we can add cards and atoms to create even richer, more customized content for our posts. Cards are blocks of rich content, while atoms are inline. Thanks to the addons we installed, we can use Ember components as cards and atoms within our Mobiledoc.

Let’s make a component card that lets users add and create their own meme as part of their blog post.

First, create a button with an action for adding the card in our toolbar component. The editor we pass into our toolbar provides us with two actions for adding cards, ‘addCard’ and ‘addCardInEditMode’. We will add our card in edit mode, which will render the ‘card editor’ template into our editor so the user can edit immediately.

Now we need to create the components for our meme-card. In order to be able to both display and edit the card in our posts, we must generate two components.

The component {{meme-card}} will be called for displaying the card, and the component {{meme-card-editor}} will be called for editing the card. (The ‘editor’ suffix is necessary for the addon to recognize the two templates as belonging to the same card.)

$ ember generate component meme-card
$ ember generate component meme-card-editor

Here are the components:

The {{mobiledoc-editor}} component provides us with the functions ‘saveCard’, ‘editCard’, and ‘removeCard’. The editCard action toggles the card between it’s display and editor components. To save changes made to the card, the updated values are passed in using the hash helper. This becomes the card’s payload in the serialized mobiledoc. The saveCard action must fire for the card’s payload to be updated in the larger mobiledoc object.

editing the card using the {{meme-card-editor}} component

The power of Mobiledoc, especially in Ember, is that component cards are extremely customizable and can do a lot on their own. All of the logic that lets our user choose images and input text for their meme is contained within our custom meme-card-editor component:

In this particular example, my component for displaying the meme-card does not have any custom logic. However, we could potentially add logic for manipulating the payload data if we wanted to.

The last step is to pass our card into our {{mobiledoc-editor}} and {{render-mobiledoc}} components.

The {{render-mobiledoc}} component takes an array of the component card names (as strings). The {{mobiledoc-editor}} component takes an array of cards (objects). The addon ember-mobiledoc-editor provides a ‘createComponentCard’ helper that returns a card object from our component.

I decided to create helpers to return the arrays needed, so as I add more cards, I can easily pass all of them into any instance of an editor or renderer.

$ ember generate helper mobiledoc-component-cards
$ ember generate helper mobiledoc-card-names

Use the helpers to pass the card names to the renderer and the component cards to the editor, as shown below.

And that’s it! Our meme component card is implemented and works.

The mobiledoc-editor addon also supports the creation of component atoms (the dancing bananas in this example). Atoms are inline sections of content that are imbedded directly in a line of text. The Github documentation describes atoms as “effectively read-only inline cards.” They do not toggle between a display and edit state.

Adding a component atom is done in the exact same manner as cards, so I won’t repeat the steps. However, you can take a look at the code here and see how I added a dancing banana atom to this same project as an example.

View the demo app:

View the code:

I’m looking for an opportunity to apply what I learned and expand my knowledge by working on a project building with a frontend framework like Ember, React, Angular or Vue. I’d love to talk to you if you’re looking for a passionate developer with a background in fashion and graphic design!

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.