Aloha Editor

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

Guides Index ▸

Using Aloha Editor

1 Clone from Github

Fork it on github Github repository, then:


git clone git@github.com:YOURNAME/Aloha-Editor.git alohaeditor
cd alohaeditor
git checkout dev

2 Pre-commit hook

To avoid accidentally committing debugging code, symlink or copy .githooks/pre-commit into .git/hooks. This will check for the most common mistakes like ‘debugger;’ or ‘console.log();’ statements before every commit.

3 Repository Directory Structure

  • /
  • /bin – build scripts
  • /build – build configuration
  • /doc
  • /doc/api – the API documentation
  • /doc/guides
  • /vendor – third party libraries (e.g. jquery)
  • /target – build output folder
  • /src
  • /src/css – Aloha core css files
  • /src/demo – Aloha demos
  • /src/img – Aloha core images
  • /src/lib – Require plugins and bootstrap files
  • /src/lib/aloha – Main Aloha Editor core sources
  • /src/lib/vendor – third party libraries jquery
  • /src/lib/util – utility libraries (e.g. json2.js, class.js)
  • /src/plugins
  • /src/plugins/common – Common plugin bundle
  • /src/plugins/extra – Extra plugin bundle
  • /src/test – QUnit tests

4 Building – Aloha Building

4.1 Debian Linux / Mac OS X

  • Install nodejs See: http://nodejs.org
  • Install npm See: http://npmjs.org

curl http://npmjs.org/install.sh | sh
  • Invoke Building:

cd alohaeditor
mvn3 clean package

You probably want to ommit building of the api and guides:


mvn3 clean package -DbareMode=true

You can also build just the css:


mvn3 generate-sources

The resulting css will be generated in src/css/aloha.css.

4.2 Other OS:

  • Microsoft Windows: Not yet supported

4.3 Customized builds:

Aloha-Editor uses maven to build a distributable package (includes documentation etc.). To build just the javascript, it suffices to invoke r.js from the command line. For example


node build/r.js -o build/aloha/build.js

To customize the build to your needs, you can modify the build profile in build/aloha/build.js. The most likely customization you want to make is to remove or add plugins from the include property of the ‘aloha’ module definition.

To include i18n files in your build, define the locale property. If the locale property is not defined, the appropriate i18n files will be loaded dynamically by requirejs. Remember to configure Aloha.locale as well.

Unless you ask for plugins to be loaded that are not defined in the build profile, or use a locale that was not defined during building, no additional files should be downloaded by requirejs. In the future requirejs may be replaced with an AMD stub such that requirejs is not necessary for production deployments.

Css building can be customized by adding or removing entries in src/css/aloha-common-extra.css. If you removed or added plugins in the r.js build profile, you also want to add or remove the appropriate css import statement. Then, run


mvn3 generate-sources

The resulting css will be generated in src/css/aloha.css.

If you want to redefine modules in the build profile, for example if you want to use your own jqueryui, please first read Custom jQuery, jQueryUI and other modules

5 Developing CSS

src/css/aloha.css is a concatenated and minified version of src/css/aloha-common-extra.css. To develop CSS without rebuilding the CSS everytime, temporarily copy src/css/aloha-comm-extra.css over src/css/aloha.css.

Having the built version be included during development makes it possible to develop Aloha without having to worry too much about the IE maximum stylesheet limit.

Every CSS class must have either an ‘aloha-’ prefix, or must be limited to occur within an ‘.aloha’ context. For example:


.aloha .new-style { ... }
.aloha-new-style { ... }

This is to avoid interference with the CSS of the host page.

If UI elements are added to the DOM with the purpose of absolute posistioning, which is common when implementing UI widgets, they should be appended to the ui/context module:


define(['ui/context'], function(Context) {
    // preferably append it directly to the element
    Context.element.append(widgetx);
    // sometimes you need a selector instead
    elementx.widgetx({
        appendTo: Context.selector
    });
});

6 Guide

6.1 Installation

6.1.1 Debian Linux

apt-get install build-essential
apt-get install ruby1.9.1-full
cd /usr/bin
ln -s ruby1.9.1  ruby
ln -s gem1.9.1  gem
gem install guides
ln -s /var/lib/gems/1.9.1/gems/guides-0.7.1/bin/guides /usr/bin/guides
guides preview
6.1.2 Mac OSX

gem install guides
6.1.3 Microsoft Windows

6.2 Using the Guides

  • Preview Guides:

cd alohaeditor/doc/guides
guides preview

Preview URL: http://localhost:9292/

  • Building Guides:

guides build