Aloha Editor

Aloha Editor Guides

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

Guides Index ▸

Develop 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 Branches for hotfixes

Try to base your fixes on the oldest Aloha Editor Branch if possible. Currently hotfix-0.24.x is the oldest branch. Your fix will be merged in hotfix-0.25.x during the release process.

  • hotfix-0.24.x (0.24.x)
  • hotfix (0.25.x always the latest version)
  • hotfix-0.25.x (0.25.x – the latest version at this moment)

3 Pre-commit hook

A precommit hook is provided in .githooks/pre-commit. This file has to be symlinked or copied to .git/hooks/pre-commit to be effective.

The pre-commit hook will check for the most common mistakes like ‘debugger;’ or ‘console.log();’ statements.

The pre-commit hook will also invoke the jslint command on every javascript file that is to be committed. You can get jslint via npm:


  npm install -g jslint

For the appropriate flags please see .githooks/pre-commit.

All commits must be linted before being pushed, or the continous integration build may break.

4 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

5 Changelog

New changelog entries should not be added to the CHANGELOG.md file.

  • Draw a number for your changelog entry using the numbercruncher
  • Write your changelog entry in textile syntax.
  • Save the entry to the changelog entry file (e.g: /alohaeditor/build/changelog/entries/2014/02/4698.bugfix). You can also add a ticket reference to the filename.
  • Commit this file

Repeat this process for each new changelog entry.

5.1 Changelog Filenames

  • The pattern is:

[ numbercruncher ].{ RT | RM | GH | KB }[ TICKETNUMBER ].{ bugfix | feature | enhancement |
security | note | manualchange | optional-manualchange }
  • bugfix: 5.RT52145-RM7654.bugfix
  • enhancement: 5.RT52145-RM7654.enhancement
  • manualchange: 5.RT52145-RM7654.manualchange
  • optional-manualchange: 5.RT52145-RM7654.optional-manualchange
  • security fix: 5.RT52145-RM7654.security
  • note: 5.RT52145-RM7654.note

5.2 Rules

  • Write in english!
  • Write full sentences!
  • Write customer friendly changelog entries!
  • Add a ticket id to your changelog entry filename
  • Finish your sentences with correct punctuation marks!

5.3 What happens after i pushed?

Once a release is executed the maven changelog plugin will collect all changes that were not assigned to a specific aloha version and add them to a newly created changelog mapping file.

6 Building – Aloha Building

6.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
  mvn clean package

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


  mvn clean package -DbareMode=true

You can also build just the css:


  mvn generate-sources

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

6.2 Other OS:

  • Microsoft Windows: Not yet supported

6.3 Customized Builds:

6.3.1 Javavscript

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, set the ‘locale’ property. If the locale property is not set, 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.

6.3.2 CSS

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

7 Developing on Repository Browser

Currently it is needed to copy the build output of the repository-browser project (git@github.com:gentics/repository-browser.git) over the contents of alohaeditor/src/lib/vendor/repository-browser.

  • Build the repository-browser project and overwrite the files of the named folder with the contents of the generated ‘repository-browser-0.1-SNAPSHOT.zip’ file.

8 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-common-extra.css over src/css/aloha.css.

Commiting the built CSS to the repository as the default CSS that is loaded by the Aloha-Editor demos 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 positioning, which is common when implementing UI widgets, they should be appended to the element exposed by 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
    });
});

9 Guides

9.1 Installation

9.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
9.1.2 Mac OSX

  gem install guides
9.1.3 Microsoft Windows

9.2 Using the Guides

  • Preview Guides:

  cd alohaeditor/doc/guides
  guides preview

Preview URL: http://localhost:9292/

  • Building Guides:

  guides build