Mercury API

This page contains more detailed information about Mercury events, when they're fired, and how you can integrate your own plugins based on those events.

Events

All custom Mercury events (we'll refer to them as events) go through the Mercury.trigger method, which is essentially just a wrapper around jQuery's trigger method. It prepends mercury: to the event name, and fires all of these events on top.document. It's important to understand that all events are in the top window, should you be using the PageEditor. To listen to an event you can use the Mercury.on method, in which case it might look like the following:

Mercury.on('resize', function(event) {
  // you can do whatever here
});

You can also bind to the top.document, and listen for mercury:resize, which will give you the same result but isn't as concise.

Note: You can turn on debug mode in the configuration and all of the events will be logged (to console.debug), if you want to see each of the events and when they're fired (a select few events are filtered from this to keep it from being spammy).

Common Events

initialize:frame

This can be fired after the document loads to tell Mercury that it's ready to be worked on, and is the only event that you're encouraged to fire. Mercury uses an iframe to display the original document (the one that's being edited). This is to keep Mercury from impacting your pages as much as possible, and allows some nicer focus/blur handling. On pages that may have slow loading scripts or images, it's good to fire this event as soon as the dom is ready -- with the caveat that if you're dynamically loading elements that contain regions you may want to wait until all of that is done before firing this.

loaded

Fired directly after all Mercury js files have loaded. It can be used to tie into Mercury before anything is instantiated.

ready

This event is fired when Mercury has finished initializing the PageEditor. This means that everything has been loaded and initialized.

toggle:interface

Enables or disables Mercury interface items. This will also put your page into preview mode/toggle edit mode back on.

focus:window

Takes focus away from the iframe. This is used primarily for things like modals windows.

focus:frame

Focuses the iframe so editing can continue after entering data into a modal window or other such user interactions.

hide:dialogs

This is fired on various toolbar actions and will hide all currently visible dialogs (dialogs include things like selects, palettes, and the toolbar expander).

hide:panels

This is fired when opening a panel, to keep more than one panel from being toggled on at any given time. It hides all currently open panels.

unfocus:regions

Tells all regions that they should lose focus. This is fired when dealing with region types that don't actually get a true focus (snippet regions).

region:focused

This event is fired when a region gains focus. The toolbar uses this to determine which buttons and actions are available based on the region that currently has focus.

region:blurred

When a region is blurred. Primarily used by the toolbar to know which buttons it should disabled.

region:update

Every action in a region fires an update event. Keypress, mouse actions, etc. are tracked so we can keep the interface updated with information -- the status bar uses this event to display the element path.

show:toolbar

Custom toolbars are shown and hidden based on different user actions. This event will show a custom toolbar type. The toolbar type is passed as a string with the event.

hide:toolbar

Custom toolbars are shown and hidden based on different user actions. This event tells custom toolbars to hide, and the toolbar type is passed as a string.

resize

This event is used to communicate to different user interface elements that the window has been resized and that the interface should make the appropriate adjustments.

mode

Modes are just states, and are used to put Mercury into a specific mode -- preview mode for instance. This event is fired when you click on the preview button and the mode is passed as a string in the options.

saved

After a successful save, the save event is triggered.

button

There are times when you may want to simulate that a button was pressed (for instance to open a modal or panel without having to know about what's configured for it). You can do so by triggering this event and providing the name of the action (aka configuration name) like:

{action: 'insertMedia'}

action

Actions are the core of interacting with the different region types. Each region implements it's own actions, and this is broken into it's own category below.

Action events are used throughout Mercury, and tell the active region to do something. Bold is an example of this so we'll use it for some our examples.

When you click on the bold button, an action event is fired, and a few options are passed with the event. The active region will execute the action if it supports it. The options of an action event are comprised of an action command, and typically a value.

Options for a simple action like bold or italicize looks like the following:

{action: 'bold'}

But for more complex actions like setting the foreground color, it contains the action, and a value:

{action: "foreColor", value: "rgb(255, 0, 0)"}

For actions to work they need to be implemented in the different regions. For this document we'll cover the editable region type, but if you're interested in learning more you should check out the markupable region type because it implements some of the same actions, just in a different way.

Actions are defined in a few different ways. Default actions are defined in Mercury.Regions.Editable.actions. These are the common ones that support all the existing toolbar buttons and modals, but you can define custom actions in the configuration. These are considered behaviors, and this allows you to change or add all sorts of custom handling. When an action event is fired, the editable region first checks for behaviors, then tries it's default actions, and will eventually fall through to the built in contentEditable commands.

All of this allows you to add toolbar buttons and based on the naming of the button you can define custom behaviors for it as well.

Check out Extending Mercury for more information on how you can add your own behaviors, or overwrite existing ones.

If you're more interested in how these aspects work, and want to know some of the more complex things that you can do with them please check the source. Almost all aspects of Mercury regions were written using this command pattern.