bergie / hallo

Simple rich text editor (contentEditable) for jQuery UI

Hallo - contentEditable for jQuery UI

Hallo is a very simple in-place rich text editor for web pages. It uses jQuery UI and the HTML5 contentEditable functionality to edit web content.

The widget has been written as a simple and liberally licensed editor. It doesn't aim to replace popular editors like Aloha, but instead to provide a simpler and more reusable option.

Read the introductory blog post for more information.

Using the editor

You need jQuery, jQuery UI (1.10+), and Rangy loaded. An easy way to do this is to use Google's JS service:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.10.2/jquery-ui.min.js"></script>
<script src="http://rangy.googlecode.com/svn/trunk/currentrelease/rangy-core.js"></script>

The editor toolbar is using jQuery UI theming, so you'll probably also want to grab a theme that fits your needs. Toolbar pluggins use icons from Font Awesome. Check these integration instructions for the right way to include Font Awesome depending on if/how you use Twitter Bootstrap. To style the toolbar as it appears in the demo, you'll also want to add some CSS (like background and border) to the class hallotoolbar.

<link rel="stylesheet" href="/path/to/your/jquery-ui.css">
<link rel="stylesheet" href="/path/to/your/font-awesome.css">

Then include Hallo itself:

<script src="hallo.js"></script>

Editor activation is easy:

jQuery('p').hallo();

You can also deactivate the editor:

jQuery('p').hallo({editable: false});

Hallo itself only makes the selected DOM elements editable and doesn't provide any formatting tools. Formatting is accomplished by loading plugins when initializing Hallo. Even simple things like bold and italic are plugins:

jQuery('.editable').hallo({
  plugins: {
    'halloformat': {}
  }
});

This example would enable the simple formatting plugin that provides functionality like bold and italic. You can include as many Hallo plugins as you want, and if necessary pass them options.

Hallo has got more options you set when instantiating. See the hallo.coffee file for further documentation.

Events

Hallo provides some events that are useful for integration. You can use jQuery bind to subscribe to them:

• halloenabled: Triggered when an editable is enabled (editable set to true)
• hallodisabled: Triggered when an editable is disabled (editable set to false)
• hallomodified: Triggered whenever user has changed the contents being edited. Event data key content contains the HTML
• halloactivated: Triggered when user activates an editable area (usually by clicking it)
• hallodeactivated: Triggered when user deactivates an editable area

Plugins

• halloformat - Adds Bold, Italic, StrikeThrough and Underline support to the toolbar. (Enable/Disable with options: "formattings": {"bold": true, "italic": true, "strikethrough": true, "underline": false})
• halloheadings - Adds support for H1, H2, H3. You can pass a headings option key to specify what is going to be displayed (e.g. "formatBlocks":["p", "h2","h3"])
• hallojustify - Adds align left, center, right support
• hallolists - Adds support for ordered and unordered lists (Pick with options: "lists": {"ordered": false, "unordered": true})
• halloreundo - Adds support for undo and redo
• hallolink - Adds support to add links to a selection (currently not working)
• halloimage - Image uploading, searching, suggestions
• halloblacklist - Filtering unwanted tags from the content

Licensing

Hallo is free software available under the MIT license.

Contributing

Hallo is written in CoffeeScript, a simple language that compiles into JavaScript. You'll need Node.js to to build it. All build dependencies can be installed with:

$ npm install

To generate the JavaScript code to dist/hallo.js from Hallo sources, run Grunt:

$ grunt build

Hallo development is coordinated using Git. Just fork the Hallo repository on GitHub and send pull requests.

Unit tests

We use the Travis continuous integration service for testing Hallo. Currently we run two types of tests:

• CoffeeLint for ensuring compliance with coding standards
• Some QUnit tests

You can run the unit tests locally by opening test/index.html in your browser, or with PhantomJS by running:

$ grunt test

or:

$ npm test

Writing plugins

Hallo plugins are written as regular jQuery UI widgets.

When Hallo is loaded it will also load all the enabled plugins for the element, and pass them some additional options:

• editable: The main Hallo widget instance
• uuid: unique identifier of the Hallo instance, can be used for element IDs

A simplistic plugin would look like the following:

#    Formatting plugin for Hallo
#    (c) 2011 Henri Bergius, IKS Consortium
#    Hallo may be freely distributed under the MIT license
((jQuery) ->
  jQuery.widget "IKS.halloformat",
    boldElement: null

    options:
      uuid: ''
      editable: null

    _create: ->
      # Add any actions you want to run on plugin initialization
      # here

    populateToolbar: (toolbar) ->
      # Create an element for holding the button
      @boldElement = jQuery '<span></span>'

      # Use Hallo Button
      @boldElement.hallobutton
        uuid: @options.uuid
        editable: @options.editable
        label: 'Bold'
        # Icons come from Font Awesome
        icon: 'icon-bold'
        # Commands are used for execCommand and queryCommandState
        command: 'bold'

      # Append the button to toolbar
      toolbar.append @boldElement

    cleanupContentClone: (element) ->
      # Perform content clean-ups before HTML is sent out

)(jQuery)

hallo's Issues

Plans for cross-browser normalization for contenteditable

How lightweight will Hallo be? In other words:

• Will it bother about the cross browser differences?
• Will it bother with only HTML5 browsers? or HTML4 too?

[imageplugin] strip layout elements on save

in #36 we merged the WIP for the image plugin to hallo. this is one of the tasks that remain to do:

on save, the drag+drop elements should be stripped out of the content that is stored through the backbone. currently the ui-draggable attributes and with bad timing even the blue blocks get stored.

[Annotate] Shouldn't load entities in the background if no tooltip plugin exist

Disabled Hallo still listens for click events

When Hallo has been enabled, and later disabled, it still listens for events on the element. This causes errors:

Component returned failure code: 0x80004005 (NS_ERROR_FAILURE) [nsIDOMHTMLDocument.queryCommandState]
[Break On This Error] if (document.queryCommandState(format)) { 

Make the default UI minimalistic

In normal writing mode there should be no toolbar to distract user. Formatting could be provided as a separate popover when user actually makes selections.

The Byword writing app for Mac is a great example of this concept: http://minimalmac.com/post/3855002258/byword

[imageplugin] fix drag and drop styling

in #36 we merged the WIP for the image plugin to hallo. this is one of the tasks that remain to do:

the drag and drop is somehow wobbly, there are layout issues with the blue areas and the dragged image is not always visible.

[imageplugin] reduce code duplication in tabs

in #36 we merged the WIP for the image plugin to hallo. this is one of the tasks that remain to do:

the search result html area should be generalized, showResults could be abstracted to work for both suggestions and search. it should be the same for search and suggestions (suggestion is missing paging right now).

maybe we should even allow injecting tabs into the imageplugin. somebody might need a browse tab with a directory-like structure, or something we can't imagine yet...

Support WebIntents

WebIntents would be a great way to connect some of the editor functionality with whatever social web services the user utilizes.

For example, insert link could choose the link based on a http://webintents.org/pick intent looking for items of type text/uri-list. This way the links could be coming from a CMS (if it registers such an intent), or from some social bookmarking service that the user uses.

While WebIntents are not yet supported by browsers, there is a JavaScript shim that we can use.

clean up the image plugin

in #36 we merged the work in progress for the image plugin. it is still buggy though (see the list in #36 for what should be cleaned)

Joining forces for the Aloha Editor jQuery UI rewrite?

Hey Henri,

Would you be interested in joining me to do the jQuery UI stuff for Aloha Editor? I'm thinking we can prototype the jQuery UI widgets in their own MIT licensed repository, such that they can be used by Hallo and Aloha Editor and whatever else needs them. This work will start end of this month, or start of next month.

cannot call methods on halloformat prior to initialization

Hello,

I'm trying out hallo in my project and I'm getting some odd error messages. This is my integration code:

$('#edit_icon_id').click(function() {
    $('#div_id').hallo({
        plugins: {
            'halloformat': {}
        }
    });
});

When I click the #edit_icon_id for the first time, I get following error:

(new String("cannot call methods on halloformat prior to initialization; attempted to call method 'cleanupContentClone'"))

After that, every time I click #edit_icon_id I get this error:

(new TypeError("this.toolbar is null", "http://localhost/resources/js/hallo-min.js", 7))

Also note, when I call only $('#div_id').hallo(); it works, but without toolbar so I can't format contents... :S

Browser compatibility issues due to use of execCommand

For formatting the hallo editor uses the browsers built in execCommand function. This works well for 'bold' but not at all for 'formatBlock' as it is not supported by IE. For other commands the browser behavior may differ wildly.

see: http://www.quirksmode.org/dom/execCommand.html

I guess the hallo editor will need a proper formatting engine. Maybe we could 'steal' one from http://www.github.com/xing/wysihtml5

storeSelection/restoreSelection for dialogs

This is the reason the link dialog is not working: the current selection is lost when the dialog is opened.

Can't get it to compile

[balupton@localhost hallo]$ coffee -c -o examples *.coffee
[balupton@localhost hallo]$ ls
examples format.coffee hallo.coffee README.md
[balupton@localhost hallo]$ coffee *.coffee
ReferenceError: jQuery is not defined
at Object. (/home/balupton/Work/hallo/format.coffee:3:3)
at Object. (/home/balupton/Work/hallo/format.coffee:47:4)
at Module._compile (module.js:404:26)
at Object.run (/usr/local/lib/node_modules/coffee-script/lib/coffee-script.js:62:19)
at /usr/local/lib/node_modules/coffee-script/lib/command.js:120:29
at /usr/local/lib/node_modules/coffee-script/lib/command.js:90:26
at [object Object]. (fs.js:107:5)
at [object Object].emit (events.js:61:17)
at afterRead (fs.js:878:12)
at wrapper (fs.js:245:17)
[balupton@localhost hallo]$

Demo?

Font size plugin

Would be nice to have a (dropdown?) font size plugin.

Improve build instructions

I just tried building hallo, so I entered

cake build

in my shell. Ubuntu then told me that cake is not installed and that I can install it with

apt-get install cakephp-scripts

I did that and afterwards I get some other error (BuildShell can't be found or something). I assume that "cake" in the README refers to something else, because it would be strange if a coffeescript codebase needs some PHP framework to build it, but I know nothing about coffeescript, so I couldn't really figure it out. It would be nice if the instructions could be a bit more precise.

API execute without removing selection

Hi,
I'm trying to implement a colorpicker into Hallo as it is essential to our app, and we love it so much that we don't really want to change it into anything else.
The only issue is that when a color is selected we run:
widget.options.editable.execute 'foreColor', '#' + color
But this loses the selection when the color is being selected on first click on canvas (dragging cursor over a canvas) and we're forced to reselect the text by hand. Is there any way to prevent the execute from removing the selection?

Thanks!

Make Hallo Zepto compatible

I know there is a dependency to jQuery UI too, but maybe this could be done to have a very minimalistic contentEditable editor.
Would be great!

isModified compares to wrong content

On http://bergie.github.com/hallo/markdown.html, when adding a single letter, the Markdown window is updated correctly.

However, when deleting the same letter (thus restoring the original content), Markdown is not updated. This is not correct.

The cause of this lies in the event 'hallomodified', it only fires if (this.originalContent = this.getContents()). The expected behavior is not to compare the current content with the original content, but with the content since the previous 'hallomodified' event.

Force browsers to produce structured HTML

By default many browsers produce content like:

Foo <span style="font-weight: bold;">bar</span>

While what we usually want is:

Foo <strong>bar</strong>

Hallo should force browsers to produce the latter.

External resource support

Aloha has a great feature in Repositories which allow plugins like image or link insertion to search the local system or external repositories (Delicious, Flickr, you name it) for resources user wants to insert.

Hallo should be able to do the same. One approach would be to use Backbone.js Models and Collections for this, as that would provide a very nice API for integrators, and allow two-way interaction (editor UI could even send stuff back to the repository).

Always show toolbar config option

Add an option to make the toolbar appear at all times when an editable area is focused.

Use Font Awesome for the editor buttons

Font Awesome would give us very nice icons for the editor buttons. The licensing seems very compatible:

The Font Awesome webfont, CSS, and LESS files are licensed under CC BY 3.0: http://creativecommons.org/licenses/by/3.0/ A mention of 'Font Awesome - http://fortawesome.github.com/Font-Awesome' in human-readable source code is considered acceptable attribution (most common on the web). If human readable source code is not available to the end user, a mention in an 'About' or 'Credits' screen is considered acceptable (most common in desktop or mobile software).

Fixed Hallo toolbar doesn't hide after deactivation

From Create issues:

With latest version if I have multiple editables in single page, each time I click on one I get new Hallo toolbar rendered on top of the previous one.

Buttonset corner classes applied incorrectly in Chrome

Hi. For some reason "ui-corner-left" and "ui-corner-right" classes are swapped in a buttonset in Chrome. For example among halloformat's buttons ("B", "I", "S" and "U"), "B" is supposed to have left round corner and "U" is supposed to have right round corner. Chrome got the other way around. Firefox displays this fine though, which is very strange.

Chrome version: 17.0

Block-level formatting should only affect selected text

When user has made a selection and chooses a different block-level formatting (from paragraph to a h2, for instance), this should affect only the selected area, not the whole paragraph.

The way to do this would be to split the current paragraph to its own block-level elements before and after the selection before the execCommand call.

When user has no selection made, then the block-level formatting should affect the whole element.

Reported via Hacker News.

My overwriteToolbarFocus() has an issue with halloimage. How to solve?

My last pull request has an issue with halloimage: 1) the hallodeactivated event closes the dialog, 2) which in turn calls my function overwriteToolbarFocus, 3) which calls focus on the editable, 4) which activates hallo again.

1. is required only when the dialog is not modal, the dialog should close if the user clicks somewhere on the page.
2. this is required for the dialog to keep focus
3. This is a luxery: when you close the dialog the editor has focus again and the old selection is restored
4. this is how hallo is activated anyway

I fixed it with some spagetti like below, and it works. It comes with an instruction of how and when plugins should call these function ("on" and "off" on opening and closing the dialog, "silent" in the above scenario). But maybe a more elegant solution is possible? The easiest solution is to require dialogs to be modal, of course.

  overwriteToolbarFocus: function(swtch) {
    switch (swtch)  {
    case "on" : 
        this._overwriteToolbarFocus = true;
        break;
    case "off" : 
        this._overwriteToolbarFocus = false;
        this.element.focus();
        break;
    case "silent" : 
        this._overwriteToolbarFocus = false;
        break;
    }   
  },

[imageplugin] work with top-bar-editor too

in #36 we merged the WIP for the image plugin to hallo. this is one of the tasks that remain to do:

dialog closes right again if the editor is not created with showAlways: true

Can't place text cursor in links

When I have a hyperlink in an editable area (especially one that covers the entire editable area), and I try to click on the text to get a cursor for editing, the browser follows the href atribute instead and takes me to the link target. This only happens after saving the content and editing again. At the time you insert the link, you are still able to get a text cursor, but afterwards this is impossible

[Annotate]: hallomodified not fired when accepting an annotation

When user accepts an annotation it is written to DOM. However, this doesn't fire hallomodified.

Multiple button rows

Make it possible to add linebreaks for button bars so you can have more than one line of buttons

Markdown microsyntax for formatting while entering content

When user is writing content, we should allow at least parts of the Markdown microsyntax for formatting. The microsyntax should be converted to HTML immediately when inputted.

So, for example writing # Hello... would immediately by turned into <h1>Hello...</h1>.

This would be great for power users, as then they wouldn't need obscure keyboard shortcuts or resorting to the mouse to do formatting.

Floating or relative positioned toolbar option

Add an option to float the toolbar or position it relatively with an x and y offset.

https://github.com/liip/hallo/commit/afb3741aaf2cbd0b160a109f14a1712bc5c89976

[Annotate]: non-accepted annotations are stored with content

Content returned by Hallo's getContents method includes non-accepted annotations from annotate plugin, for example:

This means creating the new generation of <span class="entity organisation withSuggestions">Content Management</span> interfaces in the <span class="entity organisation">IKS Project</span>

These should be cleaned up in getContents phase.

Firefox always shows the toolbar

On Firefox, the Hallo toolbar is always shown regardless of whether there is a selection or not.

Clicking UL button twice doesn't go back to original HTML

This can be seen on http://createjs.org If you click into the first paragraph, and click the UL button twice, the layout will not revert back to the original, because the p tag is not restored

Link plugin

I'm creating this issue to mainly track the development of the Link plugin.

I see that on README it is stated that it's not currently working. Can you @bergie give some pointers where to go if I'm going to fix it? Is it just buggy or missing half of the implementation?

Thanks.

Insert menu

There should be a + button in the Hallo toolbar that allows users to insert new content to the page, including images and tables.

As the menu is available only on selection, we could also listen to double clicks and bring the menu up on them.

style markdown in-place

Rather than being a 2-pane editor, the Markdown mode should format the elements in place (much like http://iawriter.com ).
When a line starts with a #, that line is then styled as heading one (and still has the pound in front of it). Likewise with * for lists, and links should also be autolinked.

[Annotate]: VIE complains about missing namespaces

In Chrome I see a lot of:

http://creativecommons.org/ns#license> doesn't have a namespace definition in ' 

Object

Which also causes Firefox to crash.

Online demo

That'd be a nice to have! People are lazy and wanna try it quickly before cloning. At least I'm this kind of guy.

Clean up HTML contents

We should clean up HTML generated by browser's contentEditable implementation, especially when pasting. Sanitize.js might be a good option for this.

'unselected' does not trigger when you click into the text after something was selected

After selecting text and clicking somewhere to unselect, the toolbar does not disappear (tested with chrome, firefox, safari).
It disappears after you click for a second time.

Looks like the the mouseup event triggers before the text selection is updated.

[imageplugin] use jquery-ui tabs instead of homemade

in #36 we merged the WIP for the image plugin to hallo. this is one of the tasks that remain to do:

the tabs in the dialog are somehow handmade instead of using jquery-ui. as a result, if the first tab is not visible (as in the example) there is no content at all => use a jquery-ui tab plugin if there is a reasonable one. => http://jqueryui.com/demos/tabs/

Markdown example source

Where is the source for the markdown example? It doesn't appear to be in the git repository.

[imageplugin] refactor suggestion logic out of hallo

in #36 we merged the WIP for the image plugin to hallo. this is one of the tasks that remain to do:

the code starting here should be refactored to use the injected suggestions function:
https://github.com/bergie/hallo/blob/master/plugins/image.coffee#L148

this also involves porting this implementation of suggestions to create.

[linkplugin] add tabs similar to imageplugin

Add tabs to links as well

• Suggested URLs
• Related URLs

the VieBundle link plugin has them, see http://cmf.liip.ch/ and https://github.com/liip/LiipVieBundle/blob/8afac2c58bbf68d962d8e059b8b2ce754dbb9e3d/Resources/halloplugins/link.js (though the standbol handling is still outside everything, guess the code is more for the idea than actual reuse)

Color picker plugin

I imagine a color picker is quite essential to a lot of people.

I'm going to start working on this today as I need it in a project that I'm working on. If anyone has any thoughts on the best way to implement this, I would be glad to hear them.

Hallo toolbar shown in wrong place on keyboard selection

After merging the pull request #24, the Hallo toolbar is now shown inconsistently:

• When selection is made with mouse, the toolbar is shown under the selection, as intended
• When selection is made with keyboard, the toolbar is shown above the element that Hallo is enabled for

Ping @rryter for getting this fixed.