Tutorial #44
Embedded Code Editor - Ace Intermediate   2014-01-21

Introduction

Tutorial #43 - Embedded Text Editor - CKEditor described how you can embed a Text Editor in a web page and allow users to enter formatted text with links, images, etc.

A special case of text editing involves writing software Source Code. Here the list of desired features is different. Syntax Highlighting, specific to the target Language and Line Indentation makes the structure and syntax of the code easier to follow and can help spot errors. Autocompletion speeds up writing and helps prevent typing errors.

There are several editors available that you might consider. I have used CodeMirror in the past but the one that seems to be the 'market leader' at the moment is Ace which is supported by both Cloud9 IDE and Mozilla.

This tutorial will show you how to set up Ace in a web page, customize it and send the edited code to your server.

Demo 1 screenshot for this tutorial


Step by Step

1: Download a Build of Ace from Github

ace.js is hosted on two Content Delivery Networks: jsDelivr and cdnjs. You can include the ace.js scripts from either of those sites, but those do not seem to have syntax error detection enabled.

For all the sophistication of Ace, their download process is not at all friendly. If you are not familar with git and Github, the simplest approach is to go to the ace-builds page on Github and dowload the entire directory structure as a ZIP file using the link on the lower right of that page:

Image 1 for this tutorial

2: Unpack the ZIP file - it will create a directory called ace-builds-master

There are 4 directories that begin with src. In the demo I use src-min, which contains a minified (compressed) version of the main Ace JavaScript file ace.js. It also contains around 170 other files that implement various features, themes and syntax highlighting code for different languages.

Copy this entire src-min directory into your public directory somewhere appropriate.

Even though there are a ton of files, these are only accessed as needed by ace.js and if you only need certain themes and languages then you can remove the others.

3: Take a look at the Demo

The Editor in the Demo is configured to highlight JavaScript and the page is preloaded with a few lines of this. Make some changes to the code, including an error or two , and see how the editor responds.

In this screenshot there is one line with a missing semicolon (var a) which ace has marked with an i (information) note and one marked with an error. Moving your mouse over these will show a popup with more information. This on-the-fly error checking can save a lot of time.

Image 2 for this tutorial


Understanding the Code

In Tutorial 43, ckeditor interacted directly with a textarea in a form. ace works only on divs so we need to do a bit more work to create an equivalent example here.

In the HTML we create a div with id editor_div - this is what ace will interact with. We also create a textarea and submit button in the form, and we style these such that the textarea is only a few pixels in height.

We load the ace.js script and then, in our custom script, we access the textarea and immediately hide it using textarea.hide().

We configure ace to use editor_div and set the Theme to that used by github and set the Mode to javascript. There are many themes and modes - see the ace directory and docs for more information. The github theme is relatively boring but it's a 'safe' choice.

With this configuration, ace has control of editor_div and that functions as JavaScript-aware code editor. But to send the edited text to a server we need to copy it to the hidden textarea element before submitting the form.

The on click callback function gets the current contents of the editor with editor.getSession().getValue() and copies that into the textarea.



This approach is a a little indirect compared to ckeditor but is still pretty simple. You could also omit the form completely and send the editied code to the server with an ajax, which is probably what you would do in a real application.

ace has a lot of options available. Take a look at the Kitchen Sink Demo to see more of these. There is also an extensive Ace API through which you can access things like the current line, or cursor position.

Image 3 for this tutorial

Ace is a very sophisticated Code Editor and it is one that your users are probably familar with through sites like Github. If you need a web-based code editor you should take a close look at ace.


More Information

Wikipedia page on Code Editors

Ace Editor Home Page

Ace Downloads on Github

Ace Development on Github

Ace Howto Guide

Ace API Reference

jQuery-ace - jQuery plugin that simplifies Ace installation even more


Code for this Tutorial


Share this tutorial


Related Tutorials

43 : Embedded Text Editor - CKEditor   (Intermediate)


Comment on this Tutorial


comments powered by Disqus