Readme.md 6.5 KB
Newer Older
F
Fabian Jakobs 已提交
1
Ace (Ajax.org Cloud9 Editor)
F
Fabian Jakobs 已提交
2
============================
F
Fabian Jakobs 已提交
3

4 5
[![Build Status](https://github.com/ajaxorg/ace/workflows/CI/badge.svg)](https://github.com/ajaxorg/ace/actions) 
[![npm](https://img.shields.io/npm/v/ace-builds.svg)](https://www.npmjs.com/package/ace-builds)
J
Julian Verdurmen 已提交
6

K
Kevin Ji 已提交
7
_Note_: The new site at http://ace.c9.io contains all the info below along with an embedding guide and all the other resources you need to get started with Ace.
M
Matt 已提交
8

K
Kevin Ji 已提交
9
Ace is a standalone code editor written in JavaScript. Our goal is to create a browser based editor that matches and extends the features, usability and performance of existing native editors such as TextMate, Vim or Eclipse. It can be easily embedded in any web page or JavaScript application. Ace is developed as the primary editor for [Cloud9 IDE](https://c9.io/) and the successor of the Mozilla Skywriter (Bespin) Project.
F
Fabian Jakobs 已提交
10

F
Fabian Jakobs 已提交
11 12 13
Features
--------

N
nightwing 已提交
14
* Syntax highlighting for over 120 languages (TextMate/Sublime/_.tmlanguage_ files can be imported)
G
Garen Torikian 已提交
15
* Over 20 themes (TextMate/Sublime/_.tmtheme_ files can be imported)
16
* Automatic indent and outdent
F
Fabian Jakobs 已提交
17
* An optional command line
G
Garen Torikian 已提交
18
* Handles huge documents (at last check, 4,000,000 lines is the upper limit)
G
Garen Torikian 已提交
19
* Fully customizable key bindings including vim and Emacs modes
F
Fabian Jakobs 已提交
20 21 22 23
* Search and replace with regular expressions
* Highlight matching parentheses
* Toggle between soft tabs and real tabs
* Displays hidden characters
L
Lamaster 已提交
24
* Drag and drop text using the mouse
25
* Line wrapping
N
nightwing 已提交
26
* Code folding
G
Garen Torikian 已提交
27 28 29
* Multiple cursors and selections
* Live syntax checker (currently JavaScript/CoffeeScript/CSS/XQuery)
* Cut, copy, and paste functionality
F
Fabian Jakobs 已提交
30 31 32 33

Take Ace for a spin!
--------------------

K
Kevin Ji 已提交
34
Check out the Ace live [demo](http://ace.c9.io/build/kitchen-sink.html) or get a [Cloud9 IDE account](https://c9.io/) to experience Ace while editing one of your own GitHub projects.
F
Fabian Jakobs 已提交
35

N
nightwing 已提交
36
If you want, you can use Ace as a textarea replacement thanks to the [Ace Bookmarklet](http://ajaxorg.github.io/ace/build/demo/bookmarklet/index.html).
F
Fabian Jakobs 已提交
37

F
Fabian Jakobs 已提交
38 39 40
Embedding Ace
-------------

N
nightwing 已提交
41 42
Ace can be easily embedded into any existing web page. You can either use one of pre-packaged versions of [ace](https://github.com/ajaxorg/ace-builds/) (just copy one of `src*` subdirectories somewhere into your project), or use requireJS to load contents of [lib/ace](https://github.com/ajaxorg/ace/tree/master/lib/ace) as `ace`

F
Fabian Jakobs 已提交
43 44 45

The easiest version is simply:

46
```html
J
Julian Verdurmen 已提交
47 48 49 50 51
<div id="editor">some text</div>
<script src="src/ace.js" type="text/javascript" charset="utf-8"></script>
<script>
    var editor = ace.edit("editor");
</script>
52
```
53 54 55

With "editor" being the id of the DOM element, which should be converted to an editor. Note that this element must be explicitly sized and positioned `absolute` or `relative` for Ace to work. e.g.

56
```css
J
Julian Verdurmen 已提交
57 58 59 60 61
#editor {
    position: absolute;
    width: 500px;
    height: 400px;
}
62
```
63

F
Fabian Jakobs 已提交
64 65
To change the theme simply include the Theme's JavaScript file

66
```html
J
Julian Verdurmen 已提交
67
<script src="src/theme-twilight.js" type="text/javascript" charset="utf-8"></script>
68
```
69

F
Fabian Jakobs 已提交
70 71
and configure the editor to use the theme:

72
```javascript
J
Julian Verdurmen 已提交
73
editor.setTheme("ace/theme/twilight");
74
```
75

76
By default the editor only supports plain text mode; many other languages are available as separate modules. After including the mode's JavaScript file:
F
Fabian Jakobs 已提交
77

78
```html
J
Julian Verdurmen 已提交
79
<script src="src/mode-javascript.js" type="text/javascript" charset="utf-8"></script>
80
```
81

G
Garen Torikian 已提交
82
The mode can then be used like this:
F
Fabian Jakobs 已提交
83

84
```javascript
J
Julian Verdurmen 已提交
85 86
var JavaScriptMode = ace.require("ace/mode/javascript").Mode;
editor.session.setMode(new JavaScriptMode());
87
```
F
Fabian Jakobs 已提交
88

N
nightwing 已提交
89 90 91
to destroy editor use

```javascript
J
Julian Verdurmen 已提交
92 93
editor.destroy();
editor.container.remove();
N
nightwing 已提交
94 95 96
```


97 98 99
Documentation
-------------

K
Kevin Ji 已提交
100
Additional usage information, including events to listen to and extending syntax highlighters, can be found [on the main Ace website](http://ace.c9.io).
N
nightwing 已提交
101

K
Kevin Ji 已提交
102
You can also find API documentation at [http://ace.c9.io/#nav=api](http://ace.c9.io/#nav=api).
103

G
Garen Torikian 已提交
104
Also check out the sample code for the kitchen sink [demo app](https://github.com/ajaxorg/ace/blob/master/demo/kitchen-sink/demo.js).
105

G
Garen Torikian 已提交
106
If you still need help, feel free to drop a mail on the [ace mailing list](http://groups.google.com/group/ace-discuss), or at `irc.freenode.net#ace`.
107

F
Fabian Jakobs 已提交
108 109 110
Running Ace
-----------

111
After the checkout Ace works out of the box. No build step is required. To try it out, simply start the bundled mini HTTP server using Node.JS
F
Fabian Jakobs 已提交
112

113
```bash
J
Julian Verdurmen 已提交
114
node ./static.js
115
```
116

N
nightwing 已提交
117
The editor can then be opened at http://localhost:8888/kitchen-sink.html. 
F
Fabian Jakobs 已提交
118

N
nightwing 已提交
119
To open the editor with a file:/// URL see [the wiki](https://github.com/ajaxorg/ace/wiki/Running-Ace-from-file).
G
Garen Torikian 已提交
120 121

Building Ace
F
Fabian Jakobs 已提交
122 123
-----------

G
Garen Torikian 已提交
124 125 126
You do not generally need to build ACE. The [ace-builds repository](https://github.com/ajaxorg/ace-builds/) endeavours to maintain the latest build, and you can just copy one of _src*_ subdirectories somewhere into your project.

However, all you need is Node.js and npm installed to package ACE. Just run `npm install` in the ace folder to install dependencies:
F
Fabian Jakobs 已提交
127

128
```bash
J
Julian Verdurmen 已提交
129 130
npm install
node ./Makefile.dryice.js
131
```
132

G
Garen Torikian 已提交
133 134 135 136 137 138 139 140 141 142 143
To package Ace, we use the dryice build tool developed by the Mozilla Skywriter team. Call `node Makefile.dryice.js` on the command-line to start the packing. This build script accepts the following options

```bash
-m                 minify build files with uglify-js          
-nc                namespace require and define calls with "ace"
-bm                builds the bookmarklet version
--target ./path    specify relative path for output folder (default value is "./build")
```

To generate all the files in the ace-builds repository, run `node Makefile.dryice.js full --target ../ace-builds`

F
Fabian Jakobs 已提交
144 145 146
Running the Unit Tests
----------------------

N
nightwing 已提交
147
The Ace unit tests can run on node.js. Assuming you have already done `npm install`, just call:
F
Fabian Jakobs 已提交
148

149
```bash
150
npm run test
151
```
F
Fabian Jakobs 已提交
152

153 154 155 156 157 158
You can also run the tests in your browser by serving:

    http://localhost:8888/lib/ace/test/tests.html

This makes debugging failing tests way more easier.

G
Garen Torikian 已提交
159 160 161 162 163
Contributing
-----------------------------

Ace is a community project and wouldn't be what it is without contributions! We actively encourage and support contributions. The Ace source code is released under the BSD License. This license is very simple, and is friendly to all kinds of projects, whether open source or not. Take charge of your editor and add your favorite language highlighting and keybindings!

N
nightwing 已提交
164
Feel free to fork and improve/enhance Ace any way you want. If you feel that the editor or the Ace community will benefit from your changes, please open a pull request. For more information on our contributing guidelines, see [CONTRIBUTING.md](https://github.com/ajaxorg/ace/blob/master/CONTRIBUTING.md).
G
Garen Torikian 已提交
165