The Aloha Editor UI
1 The Aloha-Editor UI is a plugin
To use the Aloha-Editor UI, the UI plugin must be added to the list of plugins that are to be loaded. For example:
<script src="aloha.js"
data-aloha-plugins="common/ui,common/format"></script>
Most plugins depend on the UI plugin and JavaScript errors will occur if it they are loaded but the UI plugin is not.
requirejs can be configured such that the ui/* namespace points to your own UI implementation (see requirejs documentation, in particular the paths setting). This should only be done for modules where all exposed functions and the module itself all carry an API annotation. The ui/ui-plugin module is the entry-point of the UI plugin, and is the most likely place to override with custom behaviour.
2 Adopting components into the UI
To add a new component to the UI, a component type may be required, extended, instantiated and adopted. This can be done in a single call like this:
Aloha.require(['ui/ui', 'ui/button'], function(Ui, Button) {
var button = Ui.adopt("myButton", Button, {
click: function(){
alert("Click!");
}
});
});
The Ui.adopt() call will instantiate a new button and display it as part of the Aloha-Editor UI.
Please see the ui/ui module and the individual component modules (src/plugins/common/ui/lib) for more information.
2.1 Arena
Arenas can be used to to group buttons of one specific plugin or functionality together. The arena must be defined in the toolbar configuration (eg. in the Configuration section) first and can then be referenced by a plugin. Don’t forget to load Arena and Button in your plugin!
var arena = Ui.adopt("myArena", Arena);
var button = Ui.adopt('myButton', Button, {
tooltip: "My tooltip",
scope: 'Aloha.continuoustext',
click: function() {
alert("Click!");
}
});
arena.adopt(button);
3 Configuration
The Toolbar is made up of tabs and groups. The following example defines a toolbar with the three tabs Format, Insert and Link. Groups are nested lists of component names and are visually distinguished when displayed in the toolbar.
The tab labels are passed to i18n which translates them to the display language.
When a plugin calls Ui.adopt(componentName, …), the adopted component will appear in the toolbar, at the place where the component name appears in the configuration.
Most components will be displayed inline (next to each other). The special string ‘\n’ will force the following component to be displayed below the preceding components.
Aloha.settings.toolbar = {
tabs: [
{
label: 'Format',
components: [
[ 'bold', 'italic', 'underline', '\n',
'subscript', 'superscript', 'strikethrough' ],
[ 'formatBlock' ]
]
},
{
label: 'Insert',
exclusive: true,
components: [
"createTable", "characterPicker", "insertLink",
[ "myArena" ]
]
},
{
label: 'Link',
components: [ 'editlink' ]
}
],
exclude: [ 'strong', 'emphasis', 'strikethrough' ],
responsiveMode: false
};
The UI plugin merges this toolbar configuration with the default toolbar configuration. The default toolbar configuration can be looked up in src/plugins/common/ui/lib/settings.js.
The merge rules are as follows
- remove all components and tabs from the default toolbar configuration that are listed in Aloha.settings.toolbar.exclude,
- add all remaining tabs from the default configuration to the user configuration,
- and merge tabs with the same name such that a tab property that is omitted in the user configuration will be taken from the default configuration,
- and, if both the default tab and the user’s tab configuration contain a components property, and unless the exclusive property on a tab is true, append all remaining components from the default tab to the user’s tab configuration.
Setting responsiveMode to true will replace the default float & pin behavior of the toolbar so that it stays fixed above the active editable and will resize to fit on devices with small screens.
Chapters