Mercury Editor

Mercury Editor is a fully featured editor much like TinyMCE or CKEditor, but with a different usage paradigm. It expects that an entire page is something that can be editable, and allows different types of editable regions to be specified. It displays a single toolbar for every region on the page, and uses the HTML5 contentEditable features on block elements, instead of iframes, which allows for CSS to be applied in ways that many other editors can't handle.

Mercury has been written using CoffeeScript and jQuery for the Javascript portions, and is written on top of Rails 3.2.

Developer Note

I've started a new version of Mercury Editor with many improvements. I've learned a lot in the past few years, and I've also learned how Mercury could be improved from comments, feature requests, feedback etc.

The new project will take the place of this one, and the Rails portions will be moved to a new repo and will become more full featured -- to serve as an example of how it can be used. I will do what's reasonable to make this easy for folks (eg. moving master -> mercury1, and mercury2 -> master), but I don't get paid for this and I use this project as a sort of proving ground for various concepts and techniques, so I'd like to keep it fun and not get bogged down in version stuff. This means it's your responsibility to manage the transition or stick with the current version (which is no longer maintained by me).

There will be a purging of pull requests and issues when the transition takes place -- probably a few months from now.

Awesomeness

Ryan Bates has created an awesome RailsCast that walks you through getting Mercury Editor installed, setup and working in a Rails application. Check it out!

Mercury has been added as a Featured Project on Pivotal Tracker! If you're interested in what's planned, check out the Mercury Tracker Project.

Browser Support

Mercury has been written for the future, and thus doesn't support legacy browsers or browsers that don't follow the W3C specifications for content editing. Any browser will be supported if they support the W3C specification in the future, but there aren't plans currently for adding support for alternate implementations at this time.

Supported Browsers:

• Internet Explorer 10+
• Chrome 10+
• Firefox 4+
• Safari 5+
• Opera 11.64+
• Mobile Safari (iOS 5+)

A Demo

Feel free to check out the demo. We'll be adding a full walkthrough that goes into detail for each of the major features. If you would like to see how Mercury was implemented in the demo check the gh-pages branch, it's a useful resource to see how you can integrate the Mercury bundle into a non-rails project since it's a static site.

The Story

I was looking for a fully featured editor that didn't use iframes to edit the content, and there weren't any decent ones. My primary goal was to have areas that were editable, but that also allowed CSS to flow naturally. A few have cropped up since then (Aloha Editor for instance), and as good as they are, none had all the features I was looking for.

Mercury was written to be as simple as possible, while also providing an advanced feature set. Instead of complex configuration, we chose a mix of configuration and code simplicity, which should give you a much better chance at customizing Mercury to suit your exact needs. This doesn't mean there's not configuration, and what's there provides much of what you'll need, but efforts were taken to keep it simple and powerful.

Even though it's a great editor, Mercury Editor may not be the best for your needs (based on browser support, functionality, etc.) so here's a list of some other editors that you might want to check out:

• Aloha Editor
• jHtmlArea
• MarkItUp
• TinyMCE
• CKEditor
• NicEdit
• Raptor Editor

Features

The feature list is actually pretty long, so here's a short list that should be highlighted.

• Previewing: Preview content while you're working to see exactly how it'll look.
• Link Tools: Insert and edit links, including TOC/Bookmark links.
• Media Tools: Insert and edit images, youtube videos, and vimeo videos.
• Image Uploading: Drag images from your desktop and they'll be automatically uploaded and inserted.
• Table Editing: Advanced table editing and creation, including support for multiple column and rows spans.
• Snippets: Insert and edit predefined and reusable bits of markup/code using drag and drop.
• Custom Regions: We provide Full HTML, Markdown, Snippet, Image, and Simple region types by default.
• I18n: Built in low profile translation and internationalization system.

Installation

For Rails

Include the gem in your Gemfile and bundle to install the gem.

gem 'mercury-rails'

You can also get the configuration file and overrides by running the install generator.

rails generate mercury:install

This generator puts a mercury configuration file into your project in /app/assets/javascripts/mercury.js. This file also functions as a manifest using sprockets require to include dependencies. The install generator can optionally install the layout and css files.

Image Processing / Uploading

Mercury has a basic facility for allowing image uploads, and we provide a generator that can act as a starting point for your own back end integration. To install run the generator.

rails generate mercury:install:images

For Mongoid + MongoDB, you can use the --orm=mongoid option on the generator to get the appropriate model added to your app. This generator also puts paperclip (and mongoid_paperclip if needed) into your Gemfile, so make sure to bundle or make your own adjustments.

If you're using ActiveRecord, make sure to migrate your database. You can also disable this feature entirely in the mercury configuration if you don't plan on allowing image uploading.

Authentication

Mercury provides a generator for giving you a basic authentication implementation. You can run this generator and write your own logic into the authentication file it provides.

rails generate mercury:install:authentication

This provides a simple method for restricting the actions in the default MercuryController to only users who have the required privileges. Since this can vary largely from application to application, it's a basic approach that assumes you'll write in what you want.

For Non-Rails Environments

Download the zip file, and then follow the installation instructions on the wiki article.

Usage

There's a glob route that captures everything beginning with /editor, so for instance to edit an /about_us page, you should access it at the /editor/about_us path.

For performance reasons you may also want to notify Mercury when the page is ready to be initialized. To do this just trigger the initialize:frame event from within your normal application layouts. You can do this when the DOM is ready to be interacted with (eg. dom:loaded, document.ready), or at the bottom of your body tag. It's recommended that you do this because it gives you some load performance improvements, but it's not required.

jQuery(parent).trigger('initialize:frame');

Mercury has an expectation that content regions will be on the page (not required, but probably useful). To define content regions that Mercury will make editable you need to add a data-mercury attribute to an element. This attribute is used to specify the region type. Mercury provides some default region types, but you can also create your own. Region types are outlined below, and the available values for the data-mercury attribute are:

• full
• simple
• markdown
• snippets
• image (should only be applied to img tags)

It's important for saving that an id attribute always be set on regions, so you should always include one.

<div id="primary" data-mercury="full">
  default content
</div>

For more advanced ways to integrate Mercury Editor with your Rails application (such as not using the /editor routing prefix) check out this wiki article.

Using Mercury without Rails

If you're looking to use Mercury without Rails, you should start by checking this wiki article.

Region Types

Full Region

Full regions are for full HTML markup and utilize the HTML5 contentEditable feature. These are the core of what Mercury does, and provide the most flexibility and visual representation of what the content will look like when saved.

Simple Region

Simple regions are designed for plain text. Newlines and markup are not allowed. Simple Regions are appropriate for titles, headlines, or any area where you want the content to be editable but not the style.

Markdown Region

Markdown regions are based on Markdown syntax (specifically the github flavored version), and aren't as full featured as the full region type -- primarily because Markdown is meant to be simple. To keep it simple you can't do things like set colors etc. This region type is useful if you want to keep the markup clean and simple.

Snippets Region

Snippet regions only allow snippets and don't have a concept of content editing within them. Snippets can be the way to go with complex markup and functionality, and are ba