Home

Awesome

Vue Mobiledoc Editor

A Mobiledoc editor written using Vue and Mobiledoc Kit.

Installation

npm install vue-mobiledoc-editor

The vue-mobiledoc-editor will install the mobiledoc-kit package as a dependency and load its assets.

Basic Usage

This package is composed of two main components:

Additionally, you can use the following addons:

The most basic usage with an empty editor and a standard toolbar is:

// template
<Editor>
  <Toolbar />
</Editor>

// script
import Mobiledoc, { MobiledocToolbar } from "vue-mobiledoc-editor"

export default {
  components: {
    Editor: Mobiledoc.Editor,
    Toolbar: MobiledocToolbar
  }
}

You can check out the live mobiledoc-kit demo or clone the repo and run npm run dev for a more interactive example.

Read on for how to provide custom configurations to each component.

Mobiledoc Editor

The mobiledoc editor is a component that accepts these Mobiledoc-specific props:

Additionally, it can emit the following events:

(Note: For placeholder and other mobiledoc-related styles to work, you must import/copy mobiledoc-kit's default CSS file yourself.)

Example usage:

<MobiledocEditor
  placeholder="Start Writing..."
  @postWasUpdated="savePost">
</MobiledocEditor>

The editor has the following refs and slots available:

<MobiledocEditor>
 <slot name="header" />
 <slot /> <!--default -->
 <div ref="editorPost"> <!-- The editor's post is rendered here -->
 <slot name="footer" />
</MobiledocEditor>

You can further manipulate the editor's post element (e.g. for styling) by using $refs.editorPost; or you can grab the editor instance directly using the didCreateEditor hook.

Using provide/inject, the Editor also provides the editorVm to all child components. The editorVM has the following data and methods:

You can use the MobiledocEditor.editor instance itself to take full advantage of the features in the mobiledoc-kit API documentation.

Mobiledoc Button

The MobiledocButton is a functional component that delegates the passed props to the appropriate button. Because of this, every button requires the type prop. Any additional props depend on the type of button.

There are five types of buttons:

Additionally, all buttons accept alabel prop, to set the content of the button when used as a blockless component.

Example usage:

<MobiledocButton label="bold" type="markup" tag="strong" />

Mobiledoc Toolbar

The component creates a standard toolbar for the mobiledoc editor.

Example usage:

<MobiledocToolbar />

Advanced Usage

Component Cards

Mobiledoc supports "cards", blocks of rich content that are embedded into a post.

vue-mobiledoc-editor comes with a helper for using your own Vue components as the display and edit modes of a card.

The card's properties are passed as props to the component. You can use them like this:

// components/cards/example.vue

<template>
<div>
  <h1> {{ msg }} </h1>
</div>
</template>

<script>
export default {
  name='exCard'
  props: ['env'],
  data() {
    return {
      msg: this.env.isInEditor ? "You can edit me!" : "I'm immutable!"
    }
  }
}
</script>

Then, to use the component as a card, wrap your own component in the compToCard serializer function, before passing it to the editor as a card option:

// components/editor.js
<template>
<div>
  <Editor :cards='cards'>
    <Btn type="card" name="exCard"> exCard </Btn>
  </Editor>
</div>
</template>

<script>
import Mobiledoc, { compToCard } from "vue-mobiledoc-editor"
import example from 'components/cards/example.vue'

export default {
  data () {
    cards: [
      compToCard(example)
    ],
    components: {
      Editor: Mobiledoc.Editor,
      Btn: Mobiledoc.Button
    }
  }
}
</script>

Please note that your card must have a name to identify it. So if your component does not have a name, you'll need to provide your own to the serializer function: compToCard(NamelessComponent, 'MyCardName').

The following mobiledoc-specific properties are passed to the component:

For more details on the API for authoring cards in vanilla JavaScript, as welll as the env properties available to the card, see CARDS.md.

Creating custom mobiledoc components

To create components that control the mobiledoc editor, just inject the editorVm to child components.

For example, you can create a button that toggles whether the editor is editable or not:

export default {
  inject: ['editorVm']
  render(h) {
    const { canEdit, toggleEditMode } = this.editorVm
    return h(
      <button @click={ () => toggleEditMode() }>
        { canEdit ? 'Display' : 'Edit' }
      </button>
    )
  }
}

Note: Mobiledoc components must be nested under the Mobiledoc Editor.

Development

To get started:

Run the development server:

A development server is available under the /demo directory. You can check out the demo for an example of basic usage or to interactively test your contribution.

Run tests:

Build to dist/:

Getting Help

If you'd like to report a bug or request a feature, please open an issue.