Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alidcast/vue-mobiledoc-editor

A lightweight and customizable editor that allows you to embed rich content using Vuejs components.
https://github.com/alidcast/vue-mobiledoc-editor

mobiledoc-editor ui-components vue vue-components wysiwyg-editor

Last synced: about 2 months ago
JSON representation

A lightweight and customizable editor that allows you to embed rich content using Vuejs components.

Awesome Lists containing this project

README 

        
# Vue Mobiledoc Editor



A Mobiledoc editor written using Vue and [Mobiledoc Kit](https://github.com/bustlelabs/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:



* `MobiledocEditor`

* `MobiledocButton`



Additionally, you can use the following addons:

* `MobiledocToolbar` (component)

* `compToCard` (factory function)



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



```

// template



  



// 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](https://bustle.github.io/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:



* `mobiledoc`, a Mobiledoc to be edited. (*The package also exports an `EMPTY_MOBILEDOC` template that you can use as a default when passing a `mobiledoc` payload to the editor.*)



* `atoms`, an array of available atoms for use by the editor.



* `cards`, an array of available cards for use by the editor. (Jump to the section on Card-based components for details on how to create cards as Vue components.)



* `cardOptions`, an object of additional props to pass to rendered cards.



* `spellcheck`, a boolean. Defaults to true.



* `autofocus`, a boolean. Defaults to true.



* `placeholder`, a string to use as the placeholder text when the mobiledoc is blank.



* `serializeVersion`, a string representing the mobiledoc version to serialize to when firing the `postWasUpdated` action. Defaults to 0.3.0.



* 'enableEditing', a boolean that represents whether the editor is rendered in display or edit mode.



Additionally, it can emit the following events:



* `willCreateEditor`, a callback that fires when the Mobiledoc editor instance is about to be created. Takes no arguments.



* `didCreateEditor`, a callback that fires once the Mobiledoc editor instance has been created. Will be called with the editor instance and may be used to configure it further.



* `postWasUpdated`, a callback that will fire whenever the underlying document changes. It is called with the serialized mobiledoc.



(*Note: For placeholder and other mobiledoc-related styles to work, you must import/copy mobiledoc-kit's [default CSS](https://github.com/bustle/mobiledoc-kit/blob/master/src/css/mobiledoc-kit.css) file yourself.*)



Example usage:



```



```



The editor has the following `refs` and `slots` available:



```HTML



 

  

 
 

 



```



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:



* `editor`, a function that returns the Mobiledoc editor instance itself



* `activeSectionTags`, an object with true values for section tag names in the current selection. For example activeSectionTagNames.isH1.



* `activeMarkupTags`, an object with true values for markup tag names in the current selection. For example activeMarkupTagNames.isStrong



* `canEdit`, a function that returns a boolean stating whether editing is currently enabled or disabled.



* `toggleMarkup`, toggles the passed markup tag name in the current selection.



* `toggleSection`, toggles the passed section tag name in the current selection.



* `toggleLink`, toggles the linking of a selection. The user will be prompted for a URL if required.



* `addAtom`, passed an atom `name`, `text`, and `payload`, will add that atom at the cursor position.



* `addCard`, passed a card `name`, `payload`, and `editMode` will add that card at the end of a post and render it in the specified mode initially.



* `toggleEditMode`, updates the `canEdit` state and toggles the edit mode of the mobiledoc editor.



You can use the `MobiledocEditor.editor` instance itself to take full advantage of the features in the [mobiledoc-kit API documentation](http://bustlelabs.github.io/mobiledoc-kit/demo/docs/).



#### 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:



* `MarkupButton`, requires a `tag` prop to identify the type of markup to toggle.



* `SectionButton`, requires a `tag` prop to identify the type of section to toggle.



* `LinkButton`, accepts an optional `prompt` prop that you can pass if you wish to provide a custom dialog that the user will shown when prompted input the link.



* `AtomButton`, requires a `name` prop to identify the atom that will be added to the end of the post and accepts an optional `text` and `payload` prop.



* `CardButton`, requires a `name` prop to identify the card that will be added to the end of the post and accepts an optional `payload` and `mode` prop. There are two `mode` options, `edit` or `display`; the default is `display`.



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



Example usage:



```



```



#### Mobiledoc Toolbar



The component creates a standard toolbar for the mobiledoc editor.



Example usage:



```



```



### 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





  
 {{ msg }} 





export default {

  name='exCard'

  props: ['env'],

  data() {

    return {

      msg: this.env.isInEditor ? "You can edit me!" : "I'm immutable!"

    }

  }

}



```

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





  

     exCard 

  




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

    }

  }

}



```



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:



- `env`, an object of that holds environment-specific properties

- `payload`, an object that holds the data payload retrieved from the mobiledoc for this card



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](https://github.com/bustlelabs/mobiledoc-kit/blob/master/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(

       toggleEditMode() }>

        { canEdit ? 'Display' : 'Edit' }

      

    )

  }

}

```



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



## Development



To get started:



* `git clone` this repository



* `npm install`



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.



* `npm run dev` from project root



*  Visit your app at `http://localhost:8080`.



Run tests:



* `npm run unit`



Build to `dist/`:



* `npm run build`



#### Getting Help



If you'd like to report a bug or request a feature, please [open an issue](https://github.com/studbits/vue-mobiledoc-editor/issues).