03Oct2013

WYSWYG MERCURY EDITOR

Mercury Editor is a great tools to use for giving your site content creator the ability to write and publish content on your site.

Once, I worked on a website for publishing news related to games.  My client, who is also an editor for the site, keep stressing me, that it is very important for the editor (the tool, not the person) to gives the exact same visual output when being written as when it is being read.  Content must not be reflowed or moved in any given way.  Back then, I used a slighly customized version of CKEditor, which is a great editor non the less, but it do the editing inside an iframe with it's own sandboxed css.  This proved to be a bit of problem, and I spent quite some time trying to achieve this visual perfection.

Enter Mercury Editor.  With this, you can do the editing in the same element where you want it to be displayed, hence what you see is literally what you will get.  Oh, btw, you can give it a try here.

The installation guide on the website is enough to get you started, but when I did it, there're several hiccup in trying to make it works nicely :

  1. It hasn't been properly updated to support rails 4.

    At least, not the version on rubygems.  To make it works with rails 4, you need to install the one on master by doing :

    gem 'mercury-rails', github: 'jejacks0n/mercury'
    

  2. Use different HTTP Method and submit to different url based on whether the data is a new_record?

    To make it reusable, I put the data inside a div like so :

    <div id="mercury_params"
         data-action="/path/to/action"
         data-method="POST" />

    and in mercury.js you need to add

    $(window)
      .on('mercury:ready', function() {
        // your content are wrapped inside #mercury_iframe
        // so to access the div, you have to do it like this
        innerContent    = $('#mercury_iframe').contents();
        params          = innerContent.find("#mercury_param");
    
        // the supported method to change saveUrl on request
        Mercury.saveUrl = params.data('action');
    
        // unfortunately, changing saveMethod is not officially
        // supported, so this is a bit of a hack
        window.mercuryInstance.options.saveMethod =
          params.data("method");
      });
    

  3. Make it redirect to url given by server.

    Here's how to do it.  First, make sure you render a proper json containing the url, then in mercury.js add this :

    $(window)
      .on('mercury:ready', function() {
        // there is a 'mercury:saved' event on window
        // but you can't get the data over there
        Mercury.on("saved", function(e, data) {
          // data given from server is { url: "http://the/url" }
          window.location = data.url;
        });
      });
    

  4. Responding to server validations

    Mercury is built without any assumption about your server, hence you need some work to make it display the error messages from your validation. Like on redirect, you can do this by returning the error messages in a json response, parse it inside Mercury.on("saved") event, then display it for example in a tooltip.

There're a lot more stuff you can do with the editor, so be sure to check the full documentation.  Hope this helps :)



Ignatius Reza
Learn something about everything, and everything about something.