如何编写 Cloud9 JavaScript IDE 的功能扩展
上周末我们在JSConf.eu发布了 Cloud9 IDE ，同时发布了对应的GitHub项目。在4天时间里该项目得到340个人的关注和将近50个fork。Cloud9的口号是由"由Javascripters 为Javascripters创建的IED"，这口号有点递归，它意味着你可以hack这个ide使它变得更强大。Cloud9项目开始之初就尤其注意考虑这点了；Cloud9中的每一个功能点都是一个扩展(extension)。在IED启动的时候我们用优秀的 requireJS 库加载所有的扩展。前端UI使用 ajax.org platform (apf)，apf 使我们轻松地模块化Cloud9的用户界面。下面开始详细介绍怎样为Cloud9编写扩展。
一个扩展的生命周期是从它作为requireJS的模块开始的。我将简述requireJS的基本语法，想深入了解requireJS请参考这个文档。一个扩展会依赖其他的扩展和一些核心模块。我们将编写一个给编辑器中选定的JSON代码进行格式化的扩展。该扩展依赖核心模块：core/ide, core/ext, core/util 和编辑器管理扩展：ext/editors/editors.让我们称该扩展为formatjson，然后将其置于ext文件夹下。
require.def("ext/formatjson/formatjson",
["core/ide",
"core/ext",
"core/util",
"ext/editors/editors",
"text!ext/formatjson/formatjson.xml"],
function(ide, ext, util, editors, markup) {
return ext.register("ext/formatjson/formatjson", {
//Object definition
});
}
);
{
name : "JSON Formatter",
dev : "Your Name Here",
alone : true,
type : ext.GENERAL,
markup : markup,
hook : function(){},
init : function(){},
enable : function(){},
disable : function(){},
destroy : function(){}
}
{
name : "JSON Formatter",
dev : "Ajax.org",
alone : true,
type : ext.GENERAL,
markup : markup,
nodes : [],
hook : function(){
var _self = this;
this.nodes.push(
mnuEdit.appendChild(new apf.item({
caption : "Format JSON",
onclick : function(){
ext.initExtension(_self);
_self.winFormat.show();
}
}))
);
},
init : function(amlNode){
this.winFormat = winFormat;
},
enable : function(){
this.nodes.each(function(item){
item.enable();
});
},
disable : function(){
this.nodes.each(function(item){
item.disable();
});
},
destroy : function(){
this.nodes.each(function(item){
item.destroy(true, true);
});
this.nodes = [];
this.winFormat.destroy(true, true);
}
}
<a:hbox>
<a:vbox />
<a:vbox />
<a:vbox />
</a:hbox>
可以用XPath选择器来访问元素:
vbMain.selectSingleNode("a:hbox/a:vbox[2]");
<a:application xmlns:a="http://ajax.org/2005/aml">
<!-- Your UI markup here -->
</a:application>
UI标记可以包含html和 AML元素。我们使用AML的一个下拉列表spinner和两个按钮来描述对json格式化的窗口。
<a:window
id = "winFormat"
title = "Format JSON"
center = "true"
modal = "false"
buttons = "close"
kbclose = "true"
width = "200">
<a:vbox>
<a:hbox padding="5" edge="10">
<a:label width="100">Indentation</a:label>
<a:spinner id="spIndent" flex="1" min="1" max="20" />
</a:hbox>
<a:divider />
<a:hbox pack="end" padding="5" edge="10 10 5 10">
<a:button default="2" caption="Format"
onclick = "
require('ext/formatjson/formatjson').format(spIndent.value);
"/>
<a:button onclick="winFormat.hide()">Done</a:button>
</a:hbox>
</a:vbox>
</a:window>
{
...
format : function(indent){
//获取当前编辑器
var editor = editors.currentEditor;
//从当前编辑器获取选中的对象
var sel = editor.getSelection();
//获取当前的文档对象引用
var doc = editor.getDocument();
//获取当前选中对象的range对象
var range = sel.getRange();
//从range对象获取选中的文本
var value = doc.getTextRange(range);
//尝试将选中的文本转换为JSON，并格式化
//然后再回转为文本字符串，如果出现错误则给用户显示错误.
try{
value = JSON.stringify(JSON.parse(value), null, indent);
}
catch(e){
util.alert(
"Invalid JSON",
"The selection contains an invalid or incomplete JSON string",
"Please correct the JSON and try again");
return;
}
//如果格式化成功则用格式化后值替换掉range对象
var end = doc.replace(range, value);
//用格式化的值更新当前选中的部分
<p>
sel.setSelectionRange(Range.fromPoints(range.start, end));
</p>
},
...
}
...
"ext" : {
...
"formatjson" : {
"format" : "Ctrl-Shift-J" // Or "Command-Shift-J" for the mac file
},
...
}
...
然后必须要让快捷键管理器知道该扩展对什么快捷键响应和显示什么UI元素。添加名为hotkeys和hotitems的hash表：
hotkeys : {"format":1},
hotitems : {},
现在你有两种途径为键绑定添加处理器了。直接的方式是在扩展中添加响应方法，方法的名称与hotkeys中指定的名称相同即可，此处就是“format
”。因为我们的json格式化扩展有一个菜单来显示快捷键，我更喜欢将响应方法连接到菜单的onclick事件上，这样当我按下快捷键时这个方法被执行。而且当我使用快捷键时这个菜单按钮应该点亮。可以在hotitems哈希表中添加菜单项来达到目的:
this.hotitems["format"] = [this.nodes[0]];现在我们可以在Tools菜单下的Extendtion Manage中来激活该扩展了，可以观看下面这段视频来看看，如何在3分钟内完成这个扩展。
其他资源
When you need help with creating an extension 在你开发扩展需要帮助的时候请到Cloud9的 Google Group 。可以向github的issue跟踪issue tracker of GitHub提交任何你发现的问题。Cloud9的所有开发者在Twitter上十分活跃。在扩展Cloud9的路上祝你好运。我都等不及要看你会扩展出什么了。 我们非常乐意将你酷毙了的扩展添加为Cloud9的子模块，或者在Github上提交pull request。
玩得开心!