Embedding API

gjtorikian edited this page Sep 11, 2012 · 2 revisions

ACE can be easily embedded into any existing web page. You can either use one of pre-packaged versions of ace (just copy one of src* subdirectories somewhere into your project), or use requireJS to load the contents of lib/ace as ace.

Also, take a look at the one of the included demos for how to use Ace:

The easiest version to embed Ace is to simply call:

<div id="editor" style="height: 500px; width: 500px">some text</div>
<script src="src/ace.js" type="text/javascript" charset="utf-8"></script>
<script>
    var editor = ace.edit("editor");
</script>

Setting Theme and Language Mode

To change the theme, configure the editor to use the theme using its module name. The theme file will be loaded on demand:

editor.setTheme("ace/theme/twilight");

By default, the editor only supports plain text mode. However, all other language modes are available as separate modules. Modes are also loaded on demand, and can be included like this:

Retrieving Editor States

Ace keeps all the editor states (selection, scroll position, etc.) in editor.session, which is very useful for making a tabbed editor:

var EditSession = require("ace/edit_session").EditSession
var js = new EditSession("some js code")
var css = new EditSession(["some", "css", "code here"])
// and then to load document into editor, just call
editor.setSession(js)

Quickstart

To set and get content:`

editor.setValue("the new text here"); // or session.setValue
editor.getValue(); // or session.getValue

To get selected text:

editor.session.getTextRange(editor.getSelectionRange());

To insert at cursor:

editor.insert("Something cool");

To get the current cursor line and column:

editor.selection.getCursor();

To go to a line:

editor.gotoLine(lineNumber);

To get total number of lines:

editor.session.getLength();

To set the default tab size:

editor.getSession().setTabSize(4);

To use soft tabs:

editor.getSession().setUseSoftTabs(true);

To set the font size:

document.getElementById('editor').style.fontSize='12px';

To toggle word wrapping:

editor.getSession().setUseWrapMode(true);

To set line highlighting:

editor.setHighlightActiveLine(false);

To set the print margin visibility:

editor.setShowPrintMargin(false);

To set the editor to read-only:

editor.setReadOnly(true);  // false to make it editable

Triggering Resizes

ACE only resizes itself on window events. If you resize the editor div in another manner, and need ACE to resize, use the following:

editor.resize()

Searching in Code

The main ACE search functionality is defined in search.js. The following options are available to you for your search parameters:

  • needle: The string or regular expression you're looking for
  • backwards: Whether to search backwards from where cursor currently is. Defaults to false.
  • wrap: Whether to wrap the search back to the beginning when it hits the end. Defaults to false.
  • caseSensitive: Whether the search ought to be case-sensitive. Defaults to false.
  • wholeWord: Whether the search matches only on whole words. Defaults to false.
  • range: The Range to search within. Set this to null for the whole document
  • regExp: Whether the search is a regular expression or not. Defaults to false.
  • start: The starting Range or cursor position to begin the search
  • skipCurrent: Whether or not to include the current line in the search. Default to false.

Here's an example of how you can set up search on the editor object:

editor.find('needle',{
  backwards: false,
  wrap: false,
  caseSensitive: false,
  wholeWord: false,
  regExp: false
});
editor.findNext();
editor.findPrevious();

Here's how you can perform a replace:

editor.find('foo');
editor.replace('bar');

And here's a replace all:

editor.replaceAll('bar');

(editor.replaceAll uses the needle set by searchoptions.needle.)

Listening to Events

To listen for an onchange:

editor.getSession().on('change', callback);

To listen for an selection change:

editor.getSession().selection.on('changeSelection', callback);

To listen for a cursor change:

editor.getSession().selection.on('changeCursor', callback);

Adding New Commands and Keybindings

To assign key bindings to a custom function:

editor.commands.addCommand({
    name: 'myCommand',
    bindKey: {win: 'Ctrl-M',  mac: 'Command-M'},
    exec: function(editor) {
        //...
    }
});