Skip to content

[Draft] Aloha Blocks

Jump to bottom
Jotschi edited this page Nov 11, 2011 · 1 revision

Table of Contents

Block functionality

The functionality is provided by the Aloha-Plugin-Block. (Some functionality, especially block handling is implemented in the core or the utils).

Aloha blocks (following called blocks) are non editable parts inside an Aloha Editor editable, that can be handled by the editor and which may contain static or dynamic data.

  • The content of block elements is unknown to the Aloha Editor or the block plugin
  • Every block has a property id. If a block has no defined id, Aloha Editor sets a GUID as id
  • Blocks are either span or div elements
  • A block renderer renders the block content
  • The block renderer can use static templates or dynamic templates provided by a backend service (in case of a CMS you could use the CMS render engine)
  • Blocks may have properties, which may be modified by editors and are stored in the HTML attributes of block elements
  • The HTML attributes are the only values passed to the block renderer
  • When calling the .getContents() of the surrounding editable the contents of block elements is emptied
  • Aloha blocks may contain editables

Block configuration

HTML

All span and div elements with the class aloha-block are automatically recognized as blocks. In some cases it is necessary to provide more data for backend processing. This attributes are passed to the Aloha block renderer and pass through the .getContents() method. 

<div id="content">
Hello <span class="aloha-block" data-aloha-block-renderer="mailtemplate" data-aloha-block-prop="cn">Haymo Meran</span>,
The following item left our stock
<div class="aloha-block">
<table>
<tr><td><img src="img.png"></td><td>Super fancy laptop</td></tr>
</table>
</div>
</div>

JS

You may define blocks dynamically or in the Aloha Editor configuration. 

<script>
Aloha.block.defaults = {
  '.placeholder': {},
 '.address': {
      renderer: 'Gentics.AddressRenderer',
      addressFormat: 'US' // Default Value
  }
 };
</script>

<div id="content">
Hello <span class="placeholder">Haymo Meran</span>,
The following item left our stock
<div id="list">
<table>
<tr><td><img src="img.png"></td><td>Super fancy laptop</td></tr>
</table>
</div>
</div>
<script>
  $('#list').alohaBlock({
      renderer: 'Gentics.AddressRenderer',
      addressFormat: 'US' // Default Value
  });
</script>

Block handling

Visualization of blocks

See Aloha Concept

info

When an editable is activated all blocks inside that editable are highlighted via a css class info. The visual representation should be background yellow.

focus

When a block gets the focus all surrounding editables remain activated (editable path). The activated block is marked with a css class "focus". Selected blocks get a css class focus. The visual representation should be background blue and an outline border (It could be that the block element is covered by its content and the background therefore not visible)

selection

drag & drop

  • is only possible for blocks which are inside an editable
  • When a block has the focus, it gets a floating outline drag handle.
  • Editors may start dragging the block using the drag handle.
  • the target areas where the block can be dropped are outlined with info color.
  • During dragging the block is visible with a transparency of 60% and the source block looses its focus state and gets transparent with 60% as well.
  • When the user stops is mouse move for 1200ms the block is moved to the new location with transparency 60%.
  • When the user releases the mouse transparency is removed.
  • When the user presses ESC the source block is focused and the D&D stops.
  • When a block is release in a non drop area the block is deleted and a deletion symbol (puffing cloud symbolizes the deletion)

Caret positioning

  • Caret position left before a block: keypress right jumps to the right end of the block
  • Caret position right after a block: keypress left jumps to the left end of the block

Block Selection

  • Position left before a block keypress Shift+right jumps to the right end of the block
  • Position right before a block keypress SHIFT+left jumps to the left end of the block
  • A click on the block selects it and bubbles the event up
  • When a selection starts before a block and ends after the block is part of the selection

Manipulating blocks

TODO

Drag N Drop

By default the whole block is draggable. This is optional. Blocks can be moved always using the drag & drop handle which is always floating outside the block at the top close to the opt/left position of the block element. Reference when implementing D&D funcitonality:

Cut/Paste

TODO

Delete

  • click on a symbol close to the drag handle can delete a block
  • DEL deletes a focused block
  • BACKSPACE deletes a focused block
  • Caret position left before a block: keypress DEL deletes the block
  • Caret position right after a block: keypress BACKSPACE deleted the block

Inserting blocks

You may insert blocks at runtime.

Simple block insertion: 

Aloha.block({default:'Some content'}).appendTo('#block-container');

This example inserts a block for the renderer mailtemplate with property mail and the displayed value [email protected]: 

GENTICS.Utils.Dom.addMarkup(Aloha.Selection.rangeObject, Aloha.block({
	'renderer':'mailtemplate',
	'prop':'mail',
	'default':'[email protected]'
}));

If there is content selected the selected content should be passed to the renderer as selected content. 

GENTICS.Utils.Dom.addMarkup(Aloha.Selection.rangeObject, Aloha.block({
	'default':Aloha.Selection.rangeObject
}));

.getContents() with blocks

When you call the .getContents() of an editable with blocks the content of blocks is emptied.

Example: 

<div id="content">
Hello <span class="aloha-block" data-aloha-block-renderer="mailtemplate" data-aloha-block-prop="cn">Haymo Meran</span>
</div>
<script>
console.log(Aloha.getEditableById('content').getContents());
</script>
The output of the example will be: 
Hello <span id="mailcn" class="aloha-block" data-aloha-block-renderer="mailtemplate" data-aloha-block-prop="cn"></span>

The contents of blocks can be maintained: 

console.log(Aloha.getEditableById('content').getContents({'removeblockcontent':false}));
The output of the example will be: 
Hello <span id="mailcn" class="aloha-block" data-aloha-block-renderer="mailtemplate" data-aloha-block-prop="cn">Haymo Meran</span>

You can get the current content of a of a block with 

console.log(Aloha.getBlock('#content').getCurrentContents());

or from the renderer with the following .getContents(), where blockparams override the parametes of the block 

console.log(Aloha.getBlock('#content').getContents(blockparams));

Block rendering

Every block can be (re)rendered at any time consistently with HTML attributes of the block element. Eg. 

<div id="content">
Hello <span id="mailcn" class="aloha-block" data-aloha-block-renderer="mailtemplate" data-aloha-block-prop="cn"></span>
</div>
When you call the render method with the block id, Aloha Editor will look for a block renderer in the HTML attribute data-aloha-block-renderer of the block, in this case mailtemplate. If no renderer is defined the default block renderer is used. Blocks are rendered asynchronously. Before rendering an event aloha-block-render-start and when finish an event aloha-block-render-stop is thrown. 
Aloha.block('#mailcn').render();
The user defined renderer mailtemplate could result in: 
<div id="content">
Hello <span class="aloha-block" data-aloha-block-renderer="mailtemplate" data-aloha-block-prop="cn">Haymo Meran</span>
</div>

Default block renderer

The default renderer is used if no data-aloha-block-renderer attribute is available. The default renderer uses the content of the HTML node at the time the block is initialized.

User defined block renderer

You may define your own block renderer using the following API.

TODO define API.

Clone this wiki locally