: Functional Description

Functional Description

After reading this guide, you will

Know about browser specific issues with empty block level elements
Understand how Aloha Editor will handle paragraphs and line breaks
Contents will be deleted

1 Empty Block Level Elements

Generally, empty block level elements are not rendered by browsers. This will lead to some problems when it comes to contenteditable.

1.1 Problems while editing

Suppose you start editing with the following HTML (where [] marks the current cursor position):


<p>First paragraph[]</p>

After hitting the Enter key, you would expect to get


<p>First paragraph</p>
<p>[]</p>

Visually, you should see two paragraphs now, the first one containing the words “First Paragraph”, while the second should be empty (but consuming one line in height) with the cursor blinking in it. But, since most browsers will not render empty paragraphs (even in contenteditable areas), you would not properly see the second paragraph.

To fix this situation, Aloha Editor will instead generate HTML like this (note the additional  s added):


<p>First paragraph<br class="aloha-end-br"/></p>
<p>[]<br class="aloha-end-br"/></p>

Everything is fine now, the additional  s at the end of s do not change the rendering of non-empty paragraphs, but make the empty ones appear.

At least, everything would be fine, if there was no Internet Explorer. IE is the only browser, that renders even empty , when found in contenteditable areas, and – even worse – would add additional empty lines if  s are found at the end of s.

When using Internet Exporer 7, however, things get much worse: Internet Exporer 7 renders empty  only, if they are the last elements. If you have an empty  between two non-empty , it will not be rendered. If the last  contains the aloha-end-br, it would show an additional line (but this is only true for the last . Therefore, the Implementation of Aloha Editor for Internet Exporer 7 is special, as described below.

1.2 Main goal in Aloha Editor

The main goals in Aloha Editor are

Identical editing experience across all browsers and platforms. Therefore, browser differences must be compensated by implementation wherever possible.
What You See Is What You Get: If an editor hits the Enter key multiple times, and creates multiple empty paragraphs, that’s exactly what the resulting HTML code should render. Therefore “empty” paragraphs must not be really empty, but need to contain at least a single   in the resulting HTML code.

1.3 Implemented behaviour

The current implementation of Aloha Editor regarding block level elements is like follows:

When initializing an editable

remove all empty block level elements (since they are invisible anyway)
remove all   when using Internet Explorer (since they would add additional lines while editing)
add zero-width spaces to all empty block level elements when using Internet Explorer 7
add   to all <li> elements, except for Internet Exporer

While editing

For every operation, that might lead to an empty block level elements (hitting ENTER, deleting, …), fix the empty block level element by appending a   (except for Internet Explorer). For Internet Explorer 7, instead of   the zero-width spaces will be used.

When getting the editable’s content (e.g. for saving) with the getContents() method

Make sure that every block level element contains a single   as last child.
Remove all   contained in <li>.

The current implementation handles


<h1> – <h6>
<pre>
<blockquote>

Initialization and getContents behaviour is implemented in the Blockelement Content Handler.

2 Paragraphs & Line Breaks

Paragraphs and line breaks are a fundamental part of editing text. Aloha Editor will decide for you which kind of line break to use if certain preconditions are met. Both kind of line breaks can be created using the enter key.

Pressing enter when contents are selected will remove those contents.

2.1 Creating Paragraphs ``

To have the enter key create a new paragraph the cursor has to be located inside an existing paragraph. Every time you press enter, the existing paragraph will be split at the cursor position resulting in two paragraphs.

2.2 Creating Line Breaks ` `

If the cursor is within an editable, but no wrapping paragraph can be detected a   is inserted instead of a . If you are inside a paragraph you may insert a line break at any time by pressing Shift+Enter.

3 Deletion of Contents

If you want to delete contents you may use the Del Button to issue a forwardDelete command or the Backspace key to trigger a delete command.

If contents have been selected both forwardDelete and delete will remove the selected contents in the same manner.

3.1 `forwardDelete`

Forward delete means deleting characters that are right of your current caret position. If the selection is collapsed every time the Del key is hit a single character will be deleted. If you keep pressing Del and an inline formatting (like ) is encountered, the formatting will be kept for the remaining characters unless all of the formatted content is gone. If you encounter a phrasing element like a <h1> tag the contents will be unwrapped before character deletion is continued.

3.2 `delete`

The delete command will delte characters left of your current caret position. Deleting inline formattings will work the same way as with forwardDelete, but deleting phrasing elements will open up the end of the phrasing element which will then engulf the rest of the contents until the end of the current paragraph or comparable wrapping phrasing element is hit.