Extending Mercury

This page explains the different ways that you can customize Mercury for your specific needs. One of the easiest ways is to add your own toolbar buttons to expose additional functionality, which you can do directly from the configuration.

Adding Actions (Buttons and Behaviors)

Let's say you want to provide some basic markup, like a title, paragraph tag, and a styled link. You can add a new button to the toolbar configuration (inside the MercurySetup.config.toolbars.editable):

titleAndContent: ['Simple Markup', 'Inserts a title, paragraph tag, and a button']

Now, define a behavior for it in the behaviors section of the configuration (MercurySetup.config.behaviors):

titleAndContent: function(selection) {
  var url = prompt('Enter the link for the button');
  selection.replace('<div><h2>Title</h2><p>content</p><a href="' + url + '" class="button">button</a><hr/></div>');
}

That's it. Now you have a button that will insert a predefined set of markup, along with a user provided url. You can also style this button using your own methods, or by putting them inside the mercury_overrides.css. Here's some example CSS for a primary and editable button:

.mercury-primary-toolbar .mercury-inspector-button em,
.mercury-expander-button[data-button="inspector"] em {
  background-image: url(/assets/mercury/toolbar/primary/inspectorpanel.png);
}
.mercury-editable-toolbar .mercury-titleAndContent-button {
  background: url(/assets/mercury/toolbar/editable/title_and_content.png) no-repeat 0 0;
}
.mercury-editable-toolbar .mercury-titleAndContent-button.active {
  background-position: 0 -18px;
}

To change existing functionality you can follow a very similar pattern. Let's say you want to insert an image instead of an HR tag when a user clicks the Insert HR button. Because behaviors are used before the default actions defined in Mercury.Regions.Editable.actions you can override existing behavior, which you can check for all the default actions.

Define a behavior in the configuration:

horizontalRule: function(selection) {
  selection.replace('<img src="/rule.gif" class="horizontal-rule">');
}

Now when a user inserts a horizontal rule, they'll actually get the image tag.

Changing Functionality

If you want to change the functionality of Mercury, you'll have to dive into the source a bit more. But let's say you wanted to change how the PageEditor saves content (to make it use PUT instead of POST). You can configure a lot of this in the configuration, but if that falls short for your needs, you have a few options. If you want to work in coffeescript you're welcome to define a new file /assets/mercury/custom_page_editor.js.coffee and put something like the following:

class CustomPageEditor extends PageEditor
  
  constructor: ->
    super

  save: ->
    data = @serialize()
    Mercury.log('saving', data)
    data = jQuery.toJSON(data) unless @options.saveStyle == 'form'
    jQuery.ajax '/contents', {
      type: 'POST'
      data: {_method: 'PUT', content: data}
      success: =>
        Mercury.changes = false
      error: =>
        alert("Mercury was unable to save.")
    }

Instead of instantiating Mercury.PageEditor, you can instantiate Mercury.CustomPageEditor and saving will be an update action instead of a create action.

Alternatively, and perhaps more simply, in javascript just put the following after Mercury.PageEditor has been defined:

Mercury.PageEditor.prototype.save = function() {
  var data = this.serialize();
  Mercury.log('saving', data);
  var data = jQuery.toJSON(data);
  jQuery.ajax('/contents', {
      type: 'POST',
      data: {_method: 'PUT', content: data},
      success: function() { Mercury.changes = false },
      error: function() { alert("Mercury was unable to save.") }
  });
};