Aloha Editor

Aloha Editor Guides

These guides help you to make your content editable and to develop Aloha Editor.

Guides Index ▸

Aloha Editor Events

1 Two event mechanisms

Aloha has two mechanisms for subscribing to and publishing events.

The old bind/trigger mechanism uses jQuery’s bind() and trigger() behind the scenes and currently handles most of the events fired by Aloha:


Aloha.bind('event-name', function (jQuery.Event, eventArgument) {});
Aloha.trigger('event-name', eventArgument);

We are now in the process of replacing this API with a PubSub mechanism that we implement ourselves. The advantage of implementing it ourselves is that we have greater flexibility when we need to make extensions to the event system in the future. Also, the PubSub mechanism has less overhead (important for IE7) and a slightly cleaner API (requirejs module; forces a map argument; no event object).


define(['PubSub'], function (PubSub) {
    PubSub.sub('event.name', function (eventArgument) {});
    PubSub.pub('event.name', {key: value});
});

2 Available events

2.1 aloha-command-will-execute Event

This event is triggered before a command will be executed. The commandId hold the command which should be executed (eg. bold).


Aloha.trigger( 'aloha-command-will-execute', {
	'commandId'			: , // the command as string
	'preventDefault'	: , // boolean; default: false
} );

2.2 aloha-command-executed Event

This event is triggered after a command was executed with the Engine.execCommand method.


Aloha.trigger( 'aloha-command-executed', // command as string );

2.3 aloha-logger-ready Event

This event is triggered when the Aloha Editor logger is fully initialized.


Aloha.trigger( 'aloha-logger-ready' );

2.4 aloha-log-full Event

This event is triggered when the Aloha Editor log history is fully (definded by Aloha.settings.logHistory.maxEntries).


Aloha.trigger( 'aloha-log-full' );

2.5 aloha-ready Event

When Aloha Editor is fully initialized (the core, plugins and UI) the aloha-ready event is triggered.


Aloha.trigger( 'aloha-ready' );

2.6 aloha-editable-created Event

This event fires after a new editable has been created, eg. via $( '#editme' ).aloha()


Aloha.trigger( 'aloha-editable-created', [
	// jQuery object reference of an editable
] );

2.7 aloha-editable-destroyed Event

This event fires after a new editable has been destroyed, eg. via $( '#editme' ).mahalo()


Aloha.trigger( 'aloha-editable-destroyed', [ 
	// jQuery object reference of an editable
] );

2.8 aloha-editable-activated Event

This event notifies the system that an editable has been activated by clicking on it.


Aloha.trigger( 'aloha-editable-activated', {
	'oldActive'		: , //object of the editable
	'editable'		: , //object of the editable
} );

2.9 aloha-editable-deactivated Event

When an editable has been deactivated by clicking on a non editable part of the page or on an other editable this event is triggered.


Aloha.trigger( 'aloha-editable-deactivated', {
	'editable'		: , //object of the editable
	'newEditable'	: , // object of the new editable (may be null)
} );

2.10 aloha-smart-content-changed Event

A smart content change occurs when a special editing action, or a combination of interactions are performed by the user during the course of editing within an editable.

The smart content change event would therefore signal to any component that is listening to this event, that content has been inserted (or changed) into the editable that may need to be processed in a special way. It even lets you know when an Aloha Block has changed (i.e. when any of its attributes have changed). The smart content change event is also triggered after an idle period that follows rapid, basic changes to the contents of an editable such as when the user is typing.


Aloha.trigger( 'aloha-smart-content-changed', {
	'editable'			: , // object of the editable
	'keyIdentifier'		: , // char | null
	'keyCode'			: , // char | null
	'char'				: , // char | null
	'triggerType'		: , // keypress, idle, blur, paste, block-change
	'snapshotContent'	: , // snapshot content of the editable as HTML String
} );

2.11 aloha-block-selected Event

Processing of cursor keys will currently detect blocks (elements with contenteditable=false) and selects them (normally the cursor would jump right past them). This will also trigger the aloha-block-selected event.


Aloha.trigger( 'aloha-block-selected', 
	// DOM object (range selection)
);

2.12 aloha-selection-changed Event

This event is triggered when there are changes of the selection (using the mouse or cursor).

It is not recommended to bind to this event unless you know what you are doing. Instead consider subscribing to ‘aloha.selection.context-change’.


Aloha.trigger( 'aloha-selection-changed', [ 
	this.rangeObject, // range object
	event // browser event object
] );

2.13 aloha.selection.context-change Event

The argument to the event handler contains two properties
  • range the current value of Aloha.Selection.getRangeObject()
  • the event that caused the context change
These values are the same as for aloha-selection-changed. The message will be published every time the context of the selection changes. The context of the selection changes whenever the startContainer node or endContainer node of any range in the selection returned by Aloha.getSelection() changes, or any of their ancestors change, or any attributes of the container nodes or their ancestors change. The ancestor tree is calculated up to including the containing Aloha editable. Subscribing to this event is preferred over aloha-selection-changed because it does not fire as often, and because it is not fired at all when the user is just typing. To be able to type without introducing perceptible lag is an important aspect of editor-performance; unnecessary processing should therefore be avoided whenever possible.

3 Plugin: Image

Events provided by the Image Plugin.

3.1 aloha-image-unselected Event

When an image is unselected by the user.


Aloha.trigger( 'aloha-image-unselected' );

3.2 aloha-image-selected Event

When an image is selected by the user.


Aloha.trigger( 'aloha-image-selected' );

Events provided by the Link Plugin.

Triggers when a link is selected.


Aloha.trigger( 'aloha-link-selected' );

Triggers when a link was selected and the selection is removed.


Aloha.trigger( 'aloha-link-unselected' );

Triggers when a href attribute of a link is changed.


Aloha.trigger( 'aloha-link-href-change', {
	 'obj'			: , // jQuery object of link target
	 'href'			: , // URL of the repository item displayed to the user as string
	 'item'			: , // object of the repository item which is used
} );

5 Plugin: Table

Events provided by the Table Plugin.

5.1 aloha-table-selection-changed Event

Triggers when one or more cells of a table are selected or unselected.


Aloha.trigger( 'aloha-table-selection-changed' );

5.2 aloha-table-activated Event

After an existing dom-table is transformed into an editable Aloha Editor table this event is triggered.


Aloha.trigger( 'aloha-table-activated' );

6 Plugin: DragAndDropFiles

Events provided by the DragAndDropFiles Plugin.

6.1 aloha-allfiles-upload-prepared Event

After all files are prepared for the upload (aloha-file-upload-prepared) this event is triggered.


Aloha.trigger( 'aloha-allfiles-upload-prepared' );

6.2 aloha-drop-files-in-editable Event

Is triggerd when files are dropped into an editable part.


Aloha.trigger( 'aloha-drop-files-in-editable', {
	'filesObjs'		: , // object of dropped files
	'range'			: , // range object of the target
	'editable'		: , // jQuery object of the target editable
} );

6.3 aloha-drop-files-in-page Event

Is triggerd when files are dropped into the page and not an editable.


Aloha.trigger( 'aloha-drop-files-in-page', // object of dropped files );

6.4 aloha-file-upload-prepared Event

When a single file of many dropped files is ready for uploading.


Aloha.trigger( 'aloha-file-upload-prepared', // object of dropped files );

6.5 aloha-upload-progress Event

When the upload is still in progress this event is triggered after each uploaded file.


Aloha.trigger( 'aloha-upload-progress', // Aloha.RepositoryDocument object );

6.6 aloha-upload-success Event

A file is uploaded successfully.


Aloha.trigger( 'aloha-upload-success', // Aloha.RepositoryDocument object );

6.7 aloha-upload-failure Event

An error occurred while file upload.


Aloha.trigger( 'aloha-upload-failure', // Aloha.RepositoryDocument object );

6.8 aloha-upload-abort Event

An upload was aborted by the user or a script (IE/Safari only).


Aloha.trigger( 'aloha-upload-abort', // Aloha.RepositoryDocument object );

6.9 aloha-upload-error Event

When there occurred an error while uploading the files this event is triggered.


Aloha.trigger( 'aloha-upload-error', // Aloha.RepositoryDocument object );

7 Plugin: LinkBrowser

Events provided by the LinkBrowser Plugin.

When a link is selected in the link browser this event is triggerd.


Aloha.trigger( 'aloha-link-selected-in-linkbrowser' , // Aloha );


<head>

</head>
<body>
<div id="content-editable">
   <p>Aloha World</p>
</div>

<button id="act">activate Editable</button>
<button id="deact">deactivate Editable</button>

<script type="text/javascript">
   Aloha.jQuery( '#act').click( function () {
       Aloha.jQuery( '#content-editable').aloha();
   });

   Aloha.jQuery( '#deact').click( function () {
       Aloha.jQuery( '#content-editable').mahalo();
   });

   Aloha.ready( function(){
       Aloha.bind( 'aloha-editable-created', function( jEvent, editable ) {
           console.log( 'editable "' + editable.getId() + '" created' );
       });
       Aloha.bind( 'aloha-editable-destroyed', function( jEvent, editable ) {
           console.log( 'editable "' + editable.getId() + '" destroyed' );
       });
       Aloha.bind( 'aloha-editable-deactivated', function( jEvent, aEvent ) {
           console.log( 'editable "' + aEvent.editable.getId() + '" deactivated' );
       });
       Aloha.bind( 'aloha-editable-activated', function( jEvent, aEvent){
           console.log( 'editable "' + aEvent.editable.getId() + '" activated' );
       });
   });
</script>
</body>

8 Plugin: Block

Events provided by the Block Plugin.

8.1 aloha.drop.block.in.editable Event

Is published when a draggable block is dropped into an editable part.


PubSub.pub('aloha.drop.block.in.editable', {
  element   : , // object of dropped block
  editable  : , // object of target editable
});