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.bind method, in which case it might look like the following:

Mercury.bind('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.

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.

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.

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.

Actions