EC-IDE v0.4说明书
Author: Feng WeiGuo
Email: forxm@21cn.com
Web: http://www.supertree.org
Tel: 86-0755-81030955
All Rights Reserved
2008-10
目录
EC-IDE v0.4说明书
1. 简介
2. 概述
3．EC-IDE引擎加载
4．类模型
4.1 概念
4.2 类定义
4.3 类继承
4.4 引用外部类
4.5 类的名称空间管理和引用完整性
5．绑定
5.1 Javascript类的绑定接口
5.2 从HTML绑定Javascript类
5.3 从Javascript类绑定DOM元素
5.4 绑定对象相互访问
6．资源
6.1 HTMI资源
6.2 CSS资源
6.3 静态FILE资源
6.4 动态FILE资源
6.5 主资源
7．DOM元素寻址
7.1 绝对寻址
7.2名称相对寻址
7.3轴式相对寻址
8. 动态DOM id分配
9. 事件映射
9.1 DOM事件回调接口
9.2 非DOM回调接口方案
9.3 事件通知（Notify）方案
10. 文件管理
11. 编译选项
12. 类库
附录A. EC-IDE系统对象和工具函数
name convention
$ec
$ec()
$ec.$preload()
$ec.$import()
$ec.$derive()
$ec.$init()
$ec.$apply()
$ec.$eid()
$ec.$find()
$ec.$()
$ec.$notify()
$ec.$bind()
$ec.$res
$ec.$file
$ec.regNotify()
$ec.bind
附录B. 资源定义格式
主资源格式
附加资源格式
附加资源格式（扩展）
附录C. 事件映射格式
附录D. 调试选项
附录E. 类模型工作原理，及使用指定参数初始化基类
附录F. EC引擎加载过程
附录G. EC-IDE的DOM类库实现
G.1. 全局Z-index分配
G.2. DOM基类、控件设计
G.3. 窗体设计
G.4. 对话框设计
附录H. EC-IDE引擎缩减版本
1. 简介
EC-IDE是一个Javascript框架系统和集成环境，在完全遵守现有Javascript语法的基础上，实现类语言编程，并对Javascript代码、HTML代码、CSS样式表、外部文件（如图片文件）、Javascript类库、Web应用程序等进行完全的模块化，极大地提高了它们的可重用性。
2. 概述
EC-IDE是 ECMAScript Class-Oriented Integrated Development Environment 的简称，是一种在ECMA-262 3rd 基础上，将面向对象语言改造为面向类语言的一个Script语言框架系统。当前已在Javascript语言上实现了框架系统，并提供集成开发环境。
与其它Javascript框架系统对比，EC-IDE系统具有以下特点：
1.
类定义语法：在完全遵守现有Javascript语法的基础上，实现与常规面向类语言如C++、Java等相似的类定义语法，包括：类继承；外部类导入和引用；与类名相同的构造函数；类的所有属性、方法和构造函数，并列于同一源码层次上，符合类语言的编码习惯。
2.
HTML
代码
分解为Javascript
类的资源：传统的Web程序中Javascript代码是为HTML代码服务的，但在EC-IDE系统中，
Javascript
类代码是程序实现的中心，HTML代码被分解为代码片段，依附于Javascript类代码作为其资源存在。这样，可以使 Javascript代码脱离出全局性的HTML代码。
3.
文件资源：除了HTML代码片段外，还可以指定各种文件作为Javascript类的资源。当前EC-IDE系统支持的资源包括：HTML代码片断、CSS样式文件、图片文件、通用文件等，只要引入了Javascript类，则所有指定的资源会自动打包加载，避免手工拷贝文件的工作。同时，可以使Javascript类文件和它所包括的资源成为完全独立的模块，有利于代码和各种资源文件的重用。
4.
Javascript
类与DOM
对象的绑定：EC-IDE系统明确了Javascript类与DOM对象之间的联系方式，称为Javascript
类实例与DOM
对象的绑定；既可以在HTML代码中指定类名和参数，由EC-IDE引擎在运行时自动建立绑定，也可以在Javascript程序中动态建立绑定；同时系统提供简单的方法，使绑定关系的两方可以方便地相互访问。
5.
动态DOM id
分配：HTML/DOM的id属性是一个常用属性，通过document.getElementById()访问DOM元素是一种有效的元素绝对寻址方式，但是我们知道id属性具有全局性，这对代码模块化、面向对象设计是一个非常不利的因素。EC-IDE系统引入动态id分配方案，确保id值具有唯一性、不确定性和任意性，消除id属性的全局影响，保持并扩大了id的绝对寻址能力，在Javascript代码中可以保存任意DOM元素的动态分配的id值，有效地引用对应的DOM元素。
6.
元素相对寻址：对于模块化后独立的HTML代码片断，EC-IDE系统提供2种强大的DOM元素相对寻址方式，可以在局部HTML代码片断内或全局HTML代码中进行元素查询，即使HTML代码进行了修改或位置发生移动，仍然可以使用相对寻址的方式查询DOM元素。
7.
事件映射：类似于一些C++ IDE（如MFC）对消息的处理方式，EC-IDE使用事件映射表将DOM对象的事件映射到类的方法上，无论是使用IDE工具或手工编辑，开发从员都非常容易地编辑这个映射表；同时EC-IDE提供了主动式消息通知（Notify）的方案，以及非DOM事件处理的方案，开发人员可以选用这些方案实现更复杂的事件处理。
8.
浏览器客户端系统：虽然EC-IDE的类名采用了如Java的‘包链+类名’形式，但是Javascript类文件的物理存贮位置与类名没有必然的联系。EC-IDE系统在运行时不会主动与服务器交互，不会进行动态类加载的过程，开发人员将所有类文件打包为单独的应用程序，或打包为应用程序库，供用户一次下载所有程序，并在用户的浏览器上本地运行，这样避免了类文件数量庞大时产生的加载时延。
9.
打包和类库：使用EC-IDE提供的集成环境，开发人员既可以对每个类单独引用，方便调试，也可以将所有Javascript类打包成一个单独的Web应用程序，类比于可以单独运行的*.exe程序；还可以将相同功能的类打包为一个或数个类库，供其它Web程序引用，类比于动态程序集*.dll；所有打包后的应用程序或类库都默认设置为脱离原有开发环境，自成系统地独立工作；在集成环境中，开发人员可根据实际需要，方便灵活地修改配置；
10.
集成环境：EC-IDE提供一个一体化的集成开发环境，使开发人员可以方便快捷地完成Web程序的管理、配置、编辑、发布等工作。主要功能包括：EC-IDE编译器（类库引用完整性检查、资源解释、代码压缩、打包），项目文件管理（新建、打开、保存），简易编辑器（支持Javascript和Html语法着色，Html预览，也支持使用外部文本编辑器），各种向导工具（项目向导、类向导、类引用向导、事件映射向导、资源向导、类名插入、DOM寻址插入等）。另外要说明的是，这个IDE环境本身是用EC-IDE编译器生成，本身也是使用EC-IDE框架的Javascript应用程序。
11. EC-IDE系统的其它特性包括：以开源形式提供EC-IDE引擎的代码，以开源形式提供一组简单的DOM类库实现，内置多种选项的Javascript和Html代码压缩，可以动态设置的调试状态和调试信息输出，等等。
3．EC-IDE引擎加载
EC-IDE（以下简称为EC）系统运行须要加载EC引擎，
<script src="ec.js" id='_EC_ENGINE_'></script>
说明：
1． EC引擎必须带有名为'_EC_ENGINE_'的id值，以支持参数加载等工作；
2． 如果EC引擎已被打包到Web应用或类库中，则不可以使用以上语句；如必须加载参数，请将src属性删除，以免重复加载，如：
<script id='_EC_ENGINE_' debug=’2’></script>
<script id='_EC_ENGINE_' debug=’2’></script>
3． 仅允许加载1次EC引擎，重复加载或关键字”$ec”冲突将引起异常抛出；
4． EC引擎对象为$ec，所有EC引擎的功能都须引用此对象；当前版不会将特定关键字如$import、$等引入到GLOBAL（window）对象，以避免与其它框架冲突；
5． 当前EC引擎支持的参数有：debug，参见附录；
4．类模型
4.1 概念
EC-IDE（以下简称为EC）为了在Javascript基础上实现类模型，引入以下概念：
Javascript
构造器（JS-Constructor）：与原Javascript中的含义相同，指一个Javascript函数。
EC
类声明（EC-Declare-Function）：用于构造一个EC类，预备类的prototype对象。
EC
类入口（EC-Entry-Function）：一个
Javascript
构造器，用户及EC引擎使用Javascript系统的new关键字对这个函数操作，建立类的实例。
EC
类构造器（EC-Constructor）：与类名同名的，初始化类实例的方法。
4.2 类定义
以下是一个EC类定义和C++类定义的类比，在本说明书中，
深底色文本表示固定格式代码，可以由IDE向导生成或直接拷贝，内含的中空文本表示开发者自定义内容；
浅底色文本表示一般代码。
|
EC-Class
|
C++ Class
|
|
$ec.preload(
“
MyClass1”,
function() //EC-Declare-Function
{
this.prototype={
|
class MyClass1
{
|
|
MyClass1: function(n) //构造器
{
this.a=n;
}，
a: 0, //属性
func1: function() //方法
{
a=1;
}
|
MyClass1(n) //构造器
{
a=n;
}
int a; //属性
void func1() //方法
{
a=1;
}
|
|
}
}
);
|
}
|
说明：
1. 用户只填充EC类的属性或方法，头部和尾部为固定格式代码，可以直接拷贝或由IDE生成，再修改类名即可；
2. EC类构造器与类同名，如果类名是‘包链+类名’的形式，EC类构造器与最后一个类名相同；构造器不是必须的，可以缺省；
3. 如果要建立静态的类，即不允许建立类实例，也就是建立一个全局性的对象，应为这个全局对象建立一个EC类（与常规EC类相同），并在EC构造器中阻止实例的生成（如抛出一个异常），这样EC引擎可以统一管理这个对象（静态类），并允许从静态类中继承出新类；
4. 所有EC类声明函数（EC-Declare-Function）为空参数函数；EC类构造器可以带有参数；
4.3 类继承
类继承定义：
|
EC-Class
|
C++ Class
|
|
$ec.preload(
“
MyClass1”,
function() //EC-Declare-Function
{
this.prototype=$ec.$derive(
“
MyBase1”,
//
[“MyBase1”, “MyBase2”,…]
{
|
class MyClass1: MyBase1
{
|
|
MyClass1: function(n) //构造器
{
this.a=n;
}，
a: 0, //属性
func1: function() //方法
{
a=1;
}
|
MyClass1(n) //构造器
: MyBase1(n)
{
a=n;
}
int a; //属性
void func1() //方法
{
a=1;
}
|
|
}
);
}
);
|
}
|
说明：
1. 如果要实现多继承，将基类名称字串替换为基类名称数组，其中第1个基类为主基类；单继承也可以使用基类名称数组的形式；
2. EC引擎在新建EC类实例时，默认将相同的参数顺序传递到所有基类使之初始化；如果基类构造器的参数不为空，并且须要向基类传递不同的初始化参数，请参照附录；
4.4 引用外部类
EC类可以使用$ec.$import()方法导入并引用一个外部类，
|
EC-Class
|
C++ Class
|
|
$ec.preload(
“
MyClass1”,
function() //EC-Declare-Function
{
|
---
|
|
//EC_IMPORT
var MyExt1=$ec.$import(”MyExt1”);
var MyExt2=$ec.$import(”MyExt2”).prototype;
//END_EC_IMPRT
|
#include “MyExt1.h”
#include “MyExt2.h”
|
|
this.prototype={
|
---
|
|
……
func1: function() //方法
{
var o= new MyExt1;
MyExt2.func1();
}
……
|
……
void func1() //方法
{
MyExt1 o=new MyExt1;
MyExt2.func1();
}
……
|
|
}
}
);
|
---
|
说明：
1． 通常在EC类声明函数（EC-Declare-Function）的头部插入导入语句，也可以在类方法中插入，开发者可以使用IDE向导自动生成，也可手工编辑；
2． 如果使用IDE向导进行插入，会生成//EC_IMPORT和//END_EC_IMPRT系统注释语句，这些注释语句不是必须的，仅用于IDE向导工具工作；
3． 引用变量名可以由开发者缩减（IDE向导支持缩减功能），不影响导入类在本类以外的使用；
4． 如果导入的是静态类（全局对象），则应导入其prototype属性；静态类不必建立实例，可以直接使用；
5． 在$ec.$derive()和$ec.$bind()中使用的外部类，以及主资源HTML片断中出现在jclass属性的类，如果不在类方法中使用，可不必导入，IDE编译器会自动完成引用完整性检查；
4.5 类的名称空间管理和引用完整性
与EC-IDE的早期版本（ESOE v0.2）或其它具有名称空间管理框架类似，EC-IDE有自已的类名称空间。除了便于管理和避免名称冲突的作用外，EC-IDE的类名称空间具有以下特性：
1. EC引擎在运行时不会利用类名进行自动加载工作；引用完整性在编译时被处理；
2. IDE编译器在进行引用完整性检查工作时，检查以下调用中所包含的类信息：
$ec.$preload(), $ec.$import(), $ec.$derive(), $ec.$bind()
HTML代码片断中的jclass属性
$ec.$preload(), $ec.$import(), $ec.$derive(), $ec.$bind()
HTML代码片断中的jclass属性
3. EC-IDE编译器在确保类引用完整性时，按类名提示的路径信息查找对应的类文件；
4. 类文件也可以不在对应类库的路径中，文件可以在任意路径位置，只要被加入项目文件中即可，例如可以在引用的类库文件中；
5. 如果一个类被重复加载，EC引擎会抛出异常；
5．绑定
EC-IDE系统使用绑定的方法，将Javascript类和DOM对象关联。
5.1 Javascript类的绑定接口
如果一个Javascript类要与DOM对象绑定，EC引擎将会向新建的类实例传入被绑定的DOM对象，作为构造函数第1个参数；而第2个参数是可选的参数，作为Javascript类的参数。以下是与DOM对象绑定的Javascript类的接口示例，
MyDomClass: function( e, p ) //e: dom element, p: parameter
{
}
5.2 从HTML绑定Javascript类
在运行时，EC-IDE引擎将扫描HTML代码，如果HTML元素具有专有属性“jclass”，则生成Javascript类的一个实例，并将该实例以DOM元素的id值为索引，保存在$ec.bind对象中。这种方式称为
静态绑定。
例子：
<div jclass="MyClass">abc</div> <!--简单绑定-->
<div jclass="MyClass{a:1,b:2}"></div> <!--带参数的绑定-->
说明：
1． jclass属性必须是以完整类名起头的字串；
2． jclass属性字串可以在类名之后加入参数，参数是以花括号括起的JSON字串，可以用eval方法生成一个Object对象；EC将把这个对象传入生成的类实例，作为第2个初始化参数；
3． 每个DOM对象只允许绑定一个Javascript类实例；
4． 如果被绑定的DOM对象没有对应的id值，EC引擎会自动为其分配一个唯一的id值；
5.3 从Javascript类绑定DOM元素
EC-IDE引擎提供$ec.$bind()方法，动态绑定DOM元素。动态绑定生成的类实例同样也会被保存在$ec.bind对象中。
$ec.$bind(
“MyClass”,
//Javascript类名
e,
//Dom元素
{a:1,b:2}
//参数
);
5.4 绑定对象相互访问
如前所述，类实例会以DOM元素的id值为索引，保存在$ec.bind对象中。如果已知DOM元素的id值，可以用以下方式访问对应的绑定类实例，
o= $ec.bind[e.id];
如果已知的直接是DOM对象，EC引擎对象$ec本身提供一个快捷方法，
o= $ec(e);
或
<div jclass="MyClass" οnclick=”$ec(this).func1()”>abc</div>
如果须要在Javascript代码中访问对应的DOM元素，应首先保存绑定DOM元素的id值。IDE会自行添加这个代码，或者可以从DOM基类中获得这个属性。在EC-IDE中，类实例所保存的DOM元素的id值一般被命名为eid（element id），而类实例所保存的其它DOM元素的id值一般也以eid起头。
已知eid后，可以通过document.getElementById()访问DOM对象，EC引擎对象$ec本身提供一个document.getElementById()的快捷方法，代码例子如下：
eid: “”,
MyDomClass: function( e, p )
{
this.eid= e.id;
……
}
func1: function()
{
var e= document.getElementById(this.eid);
或
var e= $ec(this.eid);
}
6．资源
EC-IDE系统以Javascript代码为程序的现实的中心内容，HTML代码片断、CSS样式文件、图片文件及其它文件都作为Javascript代码的附加资源。
6.1 HTMI资源
在EC-IDE系统中，HTML代码被分割为单独的小块代码而依附于Javascript类代码，被称为HTML片断，缩写为
HTMI (HTML fragment item)。
//#EC_RES
//资源定义头部
//#HTMI: unique_htmi_id, htmi_path
//附加HTMI资源
//#END_EC_RES
//资源定义结束
说明：
1. 所有附加资源都在编译时刻被处理，必须放在EC-IDE系统注释“//#EC_RES”和“//#END_EC_RES”之间的资源定义块中，以使IDE解释器和编译器处理；每个Javascript类代码只允许出现1个资源定义块；
2. HTMI附加资源以“//#HTMI:”起头，unique_htmi_id必须是在整个项目中与其它HTMI资源相区别的唯一的字串值，htmi_path是HTMI资源所在的文件，相对于所在的Javascript文件；如果unique_htmi_id发生冲突，编译器会提出警告；
IDE编译器收集所有的HTMI资源，对其进行HTML代码压缩，以unique_htmi_id为索引统一存放在$ec.$res对象中；开发者可以使用$ec.$res[unique_htmi_id]引用这个资源，
e.innerHTML=$ec.$res["MyHtmi"];
说明：
1. $ec.$res[unique_htmi_id]是一个单值Array，可以作为字串直接使用；如要对其进行操作，可使用完整形式$ec.$res[unique_htmi_id][0]；
6.2 CSS资源
CSS样式文件可以用附加资源的形式依附于Javascript类代码，
//#EC_RES
//#CSS: css_id, css_path
//附加CSS资源
//#END_EC_RES
说明：
1. CSS附加资源以“//#CSS:”起头，css_id是CSS资源的id值，不必是唯一值，如果发生冲突，IDE集成环境会自行调整；css_path是CSS资源所在的文件，相对于所在的Javascript文件；
2. 如果CSS资源以link模式编译，它将以“<link …>” 的方式被输出文件联接；如果以pack模式编译，它将被编码到输出文件内部；
6.3 静态FILE资源
外部文件如图片等，可以用FILE附加资源的形式依附于Javascript类代码，
//#EC_RES
//#FILE: file_id, file_path
//附加FILE资源
//#END_EC_RES
说明：
1. FILE附加资源以“//#FILE:”起头，file_id是FILE资源的id值，静态文件的id不必是唯一值，如果发生冲突，IDE集成环境会自行调整；file_path是FILE资源所在的文件，相对于所在的Javascript文件；
2. 如果FILE资源以pack模式编译，它将被拷贝到输出目录；如果以link模式编译，IDE编译器不会对它进行处理；
6.4 动态FILE资源
如果FILE资源具有目录相关性，会被Javascript代码动态引用，则应使用扩展资源格式（参见附录）对FILE资源进行定义，
//#EC_RES
//#FILE: {id: unique_file_id, path: file_path, dyna: 1}
//附加FILE资源
//#END_EC_RES
说明：
1. 动态FILE附加资源以“//#FILE:”起头，其后为用花括号括起的JSON字串，可以用eval()方法解释出一个Object对象；其中unique_file_id必须是在整个项目中与其它动态FILE资源相区别的唯一的字串值；file_path是FILE资源所在的文件，相对于所在的Javascript文件；如果unique_file_id发生冲突，编译器会提出警告；dyna属性的值必须为1；
IDE编译器收集所有的动态FILE资源，无论是以pack模式或link模式编译，都会计算其对于输出目录的路径，并将计算结果以unique_file_id为索引统一存放在$ec.$file对象中；开发者可以使用$ec.$file[unique_file_id]引用这个资源，
e.style.backgroundImage= $ec.$file["MyImageFile"];
说明：
2. $ec.$file[unique_file_id]是一个单值Array，可以作为字串直接使用；如要对其进行操作，可使用完整形式$ec.$file[unique_file_id][0]；
6.5 主资源
每一个Javascript类可以带有一个默认的HTML代码片断，作为绑定DOM元素后设置为DOM元素的innerHTML值，此默认的HTML代码称为
主资源。
代码例子1：
//#EC_RES
this.$res=["",0,"<DIV>abc</DIV>" ];
//主资源
//#END_EC_RES
代码例子2：
//#EC_RES
this.$res=["",1,"htmi_MyHtmi" ];
//主资源
//#HTMI: htmi_MyHtmi, MyHtmi.htmi
//附加HTMI资源
//#END_EC_RES
说明：
1. 每个Javascript类文件只可有唯一的主资源，主资源定义在EC类入口函数的$res属性上；
2. 主资源可以使用内置HTML片断代码，也可以引用HTMI资源；
3. 主资源是运行时刻属性，由EC引擎处理；当使用内置HTML片断而又没有其它附加资源，并且不须要IDE资源向导工作时，资源定义块注释“//#EC_RES”和“//#END_EC_RES”不是必须的；
4. 主资源具有继承性，具体设置请参考附录；
7．DOM元素寻址
EC-IDE对DOM元素的寻址方式包括绝对寻址、名称相对寻址、轴式相对寻址3种方式。
7.1 绝对寻址
如前所述，如果保存了DOM元素的id值，可以使用document.getElementById()或快捷工具$ec()进行绝对寻址，
e= document.getElementById(eid);
或
e= $ec(eid);
7.2名称相对寻址
EC-IDE可以使用name属性寻找目标元素，这是从类实例出发访问子元素的主要寻址方式，有利于Javascript类对HTMI的封装和重用。
例子：
<div id=from>
<div>
<div name=name1></div>
<div name=name2>
<div name=name3></div>
</div>
</div>
</dv>
…
e= $ec(‘from’);
//获取起始DOM元素
ei= $ec.$find( e, “name1”);
//寻找DOM子元素
ei= $ec.$find( e, “name2.name3”);
//寻找多级DOM子元素
ei= $ec.$find( e, “name3”);
//错误的寻址方式，无法找到元素
或
ei= $ec( e, “name1”);
//寻找DOM子元素
ei= $ec( e, “name2.name3”);
//寻找多级DOM子元素
ei= $ec( e, “name3”);
//错误的寻址方式，无法找到元素
说明：
1. 名称相对寻址使用$ec.$find()方法，或使用带2个参数的$ec()快捷工具；
2. 单个name寻址查找所有子孙节点的name属性，匹配第一个符合的节点；
3. 单个name寻址不必是直接子节点；
4. 名称相对寻址不可越过不匹配name属性的元素查询其子孙元素；即匹配单个name属性的节点的所有祖先节点，到起始DOM元素为止，都不可出现其它的name属性；
5. 多级name寻址使用“.”联接；
7.3轴式相对寻址
EC-IDE还提供轴式寻址寻找目标元素，这种寻址方式提供了一种在子元素间互访的方便灵活的方法。轴式寻址支持以下5种轴（axis）：
c::
Children，直接子元素/默认轴
a::
Ancestor，祖先
p::
Previous Sibling,，上一个同级元素
n::
Next Sibling，下一个同级元素
d::
Descendent，子孙元素
轴式寻址支持以下属性：
#xxx：元素id
<xxx>：元素标记
.xxx：元素class属性
其它：元素name属性
轴式寻址可使用字符“|”进行多级链接。
说明：
1. 轴式寻址的 [”d::”轴+name属性]不等价于$ec.$find()方法，”d::”轴寻址可以越过不匹配name属性的元素查询其子孙元素，而$ec.$find()不可以；
代码例子
<input type=’checkbox’></input><span οnclick=”$ec.$(this,’p::<input>’).click()”>Check</span>
8. 动态DOM id分配
为了消除id属性的全局影响，EC-IDE系统使用动态DOM id分配方案。在Javascript代码中，如果要获取DOM元素id，或要为DOM元素分配一个唯一的id，应使用$ec.$eid()方法。
$ec.$eid()的实现（具体实现请参照源码）：
$ec.$eid= function( e )
{
if( e.id) return e.id;
else return e.id= _create_unique_eid();
}
$ec.$eid()实现以下功能：
1． 如果元素已有id属性，则返回这个id属性；
2． 如果元素没有id属性，则为元素分配一个新的唯一的id属性，并返回新的id；
如上所述，我们可以使用动态DOM id分配方案，对任意DOM元素取id值，所取得的id具有唯一性；并且只要对任意元素用$ec.$eid()获取过一次id值，我们就可以用document.getElementById()或$ec()搜索这个元素。
代码例子：
<div οnclick=”alert( $ec.$eid(this) )”>aaa</div>
9. 事件映射
与DOM元素绑定的Javascript类，可以建立事件映射表。在创建类实例时，EC-IDE引擎自动将元素事件与Javascript类方法进行关联。
代码例子：
//#EC_MAP
//事件映射定义头部
this.$map=[
["","click","OnClickMain" ], //映射主DOM元素事件
["name1.name2","click","OnClickName2" ], //映射子DOM元素事件，静态映射
["name3","click","OnClickName3",1 ], //动态映射，$ec.$find()寻址
["<div>|<button>","click","OnClickButton",2 ] //动态映射，$ec.$ ()寻址
];
//#END_EC_MAP //事件映射定义结束
说明：
1. 每个Javascript类文件只可以有唯一的一段事件映射定义代码，事件映射定义在EC类入口函数的$map属性上；
2. 如果使用IDE向导添加事件映射，要用注释语句"//#EC_MAP"和"//#END_EC_MAP"括起，否则注释不是必须的；
3. 事件映射机制可以映射以静态绑定方法加载的直接位于主资源HTMI中的DOM元素的事件，称为静态映射；静态映射使用$ec.$find()寻址；
4. 事件映射机制可以映射在构造函数中创建的DOM元素的事件，或在构造函数中以动态绑定方法加载的DOM元素的事件，称为动态映射；动态映射支持$ec.$find()或$ec.$()寻址；动态映射可能会降低系统的加载速度；
9.1 DOM事件回调接口
事件映射必须是具有类似以下参数列表的方法：
MyEventFunction: function( evt )
{
……
this.func();
……
}
说明：
1. evt是DOM事件对象，对于IE6等浏览器，如果没有回调事件对象，EC引擎自动传递一个window.event对象作为参数；
2. 回调函数中的this对象是EC类实例；
9.2 非DOM回调接口方案
EC-IDE除支持DOM事件映射外，还提供一种非DOM对象回调解决方案，其接口如下：
MyCallbacktFunction: function( cmd, pOut )
{
}
说明：
1. cmd是回调字串，可类比于对话框是返回”ok”还是”cancel”，是主回调指令；pOut是一个回调参数，由事件发起对象自定义；
2. 回调函数中的this对象是EC类实例；
9.3 事件通知（Notify）方案
EC-IDE提供一种事件通知方案，可以在EC类实例中发起一个通知事件，所有注册过的回调函数将会被调用。
代码例子1，利用事件映射表注册回调
//定义回调函数
OnTree1Notify: function( cmd, pOut )
{
if(cmd==”expand”)
{
……
}
}
……
//#EC_MAP
//事件映射定义头部
this.$map=[
["$notify","tree1","OnTree1Notify" ] //映射’$notify’事件
];
//#END_EC_MAP //事件映射定义结束
代码例子1，手工注册回调
$ec.regNotify( oEvt, this, “OnTree1Notify” ); //this是事件接收者，oEvt是事件发送者
代码例子3，发出一个事件
this.$notify( this, “expand”, pOut ); //this是事件发送者
10. 文件管理
EC-IDE按以下方法对各种文件进行管理和输出：
1. 每个Javascript类的源代码应完整地放在单独的*.js文件中；
2. Javascript类用到的CSS文件以单独的*.css文件保存，并以附加CSS资源的方式记录在Javascript类中；
3. Javascript类用到的外部文件，如图片等，以单独的文件保存，并以附加FILE资源的方式记录在Javascript类中；
4. 如果Javascript类用到多个独立的HTMI资源，文件以单独的*.htmi（或其它扩展名）文件保存，并以附加HTMI资源的方式记录在Javascript类中；
5. 如果项目使用外部Lib类库（*.lib.js），这些类库文件将不会被IDE编译器打包或拷贝，而是直接引用；但Lib类库的其它附加资源如CSS、FILE（HTMI除外）会以前述方式联入新项目中；
6. 项目配置文件保存在*.eic（EC-IDE Config）文件中，项目的工作目录与项目配置文件所在的目录相同；
7. 如果使用IDE类向导，当从一个基类继承时，如果基类文件所在目录有同名*.jst（Javascript Template）文件，则使用这个文件作为新建类的模板；
11. 编译选项
1. EC-IDE编译器对每个文件的打包方式包括：
pack方式：将文件打包至输出文件，所有Javascript文件打包到最终的*.htm或*.js输出文件，所有的CSS打包到最终的*.htm或*.css输出文件，所有的FILE资源拷贝到输出目录；
link方式：将文件链接到输出文件，如Javascript文件以“<script src=…>”的方式联接，CSS文件以“<link …>” 的方式联接；
default / pack_release方式：见下；
pack方式：将文件打包至输出文件，所有Javascript文件打包到最终的*.htm或*.js输出文件，所有的CSS打包到最终的*.htm或*.css输出文件，所有的FILE资源拷贝到输出目录；
link方式：将文件链接到输出文件，如Javascript文件以“<script src=…>”的方式联接，CSS文件以“<link …>” 的方式联接；
default / pack_release方式：见下；
2. EC-IDE编译器支持2种编译模式：Debug模式和Release模式，可分别设置不同的输出目录；2种编译模式有以下区别：
Debug模式：如果文件设置为default方式，则默认为link方式打包；
Release模式：如果文件设置为default方式，则默认为pack方式打包；
Debug模式：如果文件设置为default方式，则默认为link方式打包；
Release模式：如果文件设置为default方式，则默认为pack方式打包；
3. EC-IDE编译器支持2种输出模式，这2种输出模式不是固定的，用户可根据须要进行混合设置：
App输出：所有内容输出至主htm文件，此htm文件可作为一个独立的Web应用运行于浏览器；如果设置了输出lib.js文件，则所有pack方式js文件打包至lib.js文件，并在主htm文件链接；如果设置了输出lib.css文件，则所有pack方式css文件打包至lib.css文件，并在主htm文件链接；
Lib输出：如果没有设置主htm文件，则仅输出lib.js文件和lib.css文件，与App输出类似，但没有htm作为Web应用入口，只可被其它项目引用；Lib模式一般应使用Release模式进行编译。
App输出：所有内容输出至主htm文件，此htm文件可作为一个独立的Web应用运行于浏览器；如果设置了输出lib.js文件，则所有pack方式js文件打包至lib.js文件，并在主htm文件链接；如果设置了输出lib.css文件，则所有pack方式css文件打包至lib.css文件，并在主htm文件链接；
Lib输出：如果没有设置主htm文件，则仅输出lib.js文件和lib.css文件，与App输出类似，但没有htm作为Web应用入口，只可被其它项目引用；Lib模式一般应使用Release模式进行编译。
4. EC-IDE编译器支持将所有文件打包到同一个输出文件，包括EC引擎自身；如果EC引擎被打包，应注意避免重复加载EC引擎，否则会导致异常抛出。
5. EC-IDE编译器支持对输出文件进行源代码压缩处理，有多种压缩选项，调试时建议取消这些选项，以加快打包速度；
12. 类库
开发人员可以将固定的多个类文件打包为EC-IDE类库，供其它Web应用程序使用。
1. EC-IDE类库文件的扩展名一般为*.lib.js；
2. 将类库文件导入项目文件，即可使用类库文件中包含的类，使用方法与一般类文件相同；
3. 类库文件一般应以Release模式进行编译；类库信息包含在类库文件头部注释中，对运行时无影响，但建议不要删除，否则开发环境IDE无法识别类库，无法自动加载；
4. 当类库文件被其它项目引用时，只有*.lib.js文件保持不变而被引用，其它文件包括*.lib.css和图片文件等（HTMI资源除外），会重新以单独文件的形式编译到新项目的输出中；
5. 类库文件可以被其它Web应用程序引用，也可被其它类库文件引用，但要注意避免重复加载同一个类，否则会抛出异常；
附录A. EC-IDE系统对象和工具函数
|
ns: name space, string type name list indicate object path, such as: "name1.name2.MyClass".
nsp: name space with JSON-Object parameter, ex: "name1.name2.MyClass{a:1,b:2}"
o: object
obj: object, normally a function parameter.
i: item / sub item
oi: object item / sub item
a: array
ai: array item
func: function, the constructor, class.
cls: class
e: dom element; or error in try/catch statement.
ei: dom element item / sub item
ch: child
res: resource
h: head
param: parameter / function parameter
p: parameter
s: string
l: length
b: bool
arg: argumnet
dbg: debug
eid: dom element id
evt: event
idx: index
|
|
The EC-IDE system object
|
|
$ec( eid )
//format 1: shortcut for document.getElementById()
$ec( e )
//format 2: return the binding ec-class object for e.id
$ec( e/eid, path [, eFrom/eidFrom] )
//format 3: shortcut for $ec.$find(), refer $ec.$find
search each other between dom element and ec-class object, or shortcut for $ec.$find()
eid: string type, if eid=="", return null;
e: not-string type
path: not-empty string
if e.id not exists, return null.
|
|
$preload( ns, funcDeclare )
$preload( ns, funcDeclare, funcEntry )
pre-load into name space object, return class/package
|
|
$import( ns )
call declare function of the class, return the class / package
|
|
$derive( ns [, oProto] )
$derive( Array(ns1,ns2,...) [, oProto] )
prepare prototype from a base class, return the newly create prototype object.
new class should set its prototype to the return value, such as, func.prototype= $ec.$derive("base_class",...)
ns: namespace string; or array of namespace string, for multiple deriving, where the 1st is the main base class.
oProto: new prototype object for new class
Note: for the 1st base class, an instance will be created with empty argument, refer $init.
|
|
$init: function( oThis, args ) //auto init all base class, with same parameters.
$init: function( oThis, args, base )
//init appointed base class
ec-class constructor entry tool
oThis: this
args: arguments
base: base class
Note:
1. EC-IDE developer can use default ec-class entry to automatically initialize all base classes with same arguments, or create self defined ec-entry to initialize base class with other arguments when calling $ec.$preload.
2. $ec.$init should be only used in ec-entry.
3. auto mode ( no 'base' argument ) will call ec-class constructor.
|
|
$apply( path, oThis, args )
apply base class function, as Function.apply do.
path: class-method path string, in bellow format,
"FullThisClass:baseclass1[:baseclass2[:...]]:method"
oThis: this
args: parameters array
|
|
$eid( e [, sPrefix] )
$eid( "" [, sPrefix] )
//pre-create an unique eid
distribute unique dom element id;
if e.id not exists, set e.id to a unique eid, return the e.id;
if e.id exists, just return the e.id.
|
|
$find( e/eid, path [, eFrom/eidFrom] )
find dom item by dom name path, return the element; if not find, return null.
path: not-empty string, dom element name item list, separated by ".".
e/eid: dom element, or its eid
eFrom/eidFrom: sub item from which the search start; eFrom itself is not included in the search. Default is e.
|
|
$( e, s )
//format 1: search dom item, relative to e
$( eid, s )
//format 2: search dom item, relative to e, where e=document.getElementById(eid)
$( s )
//format 3: search dom item, s must start with '#'; if s is not started with '#', a '#' will prefix to it.
search 1 dom item
s: not-empty string indicating search path
e: dom element
eid: dom element id, string type, not empty, can start with '#'.
item type
#xxx: element id, e is ignored.
<xxx>: tag name
.xxx: class name //match full class name, not match partial class from multiple class expression.
other: name attribute
axis (not support '#'):
c:: child/default
a:: ancestor
n:: next sibling
p:: previous sibling
d:: descendent
filter splitter: '|'
|
|
$notify( oEvent, cmd, p )
Raise $ec notify event.
oEvent: ec-class instance, in which the notify event occur, normally transfer a 'this'.
It will contain a reserved var "$notify_index" used by EC-IDE system, don't touch it.
cmd: notify event string
p: param, refer "callback definition".
|
|
$bind( ns, e [, param [, oMap [, bDiff] ] ] )
bind ec-class to dom object, return the binding instance.
ns: class name
param: parameter to create the object
oMap: internal use
bDiff: internal use, if bDiff==1, oMap is not corresponding with e.
|
|
object to save htmi string
|
|
object to save dynamic file path
|
|
regNotify( oEvent, oCallback/eidCallback, sFunc )
register a notify event
oEvent: ec-class instance/object, in which the notify event occur.
oCallback: the callback 'this' object, or an eid.
sFunc: the callback function name; if oCallback is eid, sFunc is relative the binding ec-class instance; refer "callback definition".
|
|
object to map dom element id to the binding ec-class instance
|
附录B. 资源定义格式
|
class.$res: main res, an array, [ sTag, type, sData [,flag] ]
sTag: tag name for the class itself, only used by IDE, or dynamically create instance in javascript;
usually not to be used, and a default "" equals "DIV".
type: type of the sData,
0- text
1- res id
2- replace text
3- replace text res id
4- override replace text
5- override replace text res id
sData:
if type=0, it's res data text;
if type=1, it's a res id;
if type=2, it's res text, with which to replace the $EC_INNERHTML section in it's base class res;
if type=3, it's a res id, with which to replace the $EC_INNERHTML section in it's base class res;
if type=4, it's res text, with which to replace the $EC_INNERHTML section in it's base class res with res type=0 or 1;
if type=5, it's a res id, with which to replace the $EC_INNERHTML section in it's base class res with res type=0 or 1;
flag:
internal use; if normalized, flag=1; if normalized and derived from base class, flag=2.
Note:
1. all type 2/3/4/5 class res will be normalized to type 0 at runtime;
2. res is only derived from the 1st not-void-res base class, or the 1st not-void-res base class chain;
|
|
//#HTMI: unique_id, file_path
//#CSS: id, file_path
//#FILE: id, file_path
id: id for the resource
unique_id: for HTMI, its id must be unique in whole system; duplicated id may cause error.
file_path: external file path.
|
|
//#_TYPE_: {id:id_value, path:path_value, dyna: dyna_value, compile: compile_value}
_TYPE_: HTMI, CSS or FILE
id_value: string value, for HTMI, or FILE with dyna=1, it must be unique id.
path_value: file path
dyna_value: only for FILE, if the file is dynamic, set dyna_value=1
compile_value: “pack” or “link”
|
附录C. 事件映射格式
|
class.$map: an array to map element's event to object method,
$map: an array [ mi1, mi2, ..., miN [,flag] ].
mi: map item, an array [ "dom_ns", "event_name", "method_name", nMode [,flagi] ].
dom_ns: dom element "name" attribute list/path, items are separated by ".". "" means the e itself;
or directly a dom object.
event_name: event name without "on" prefix, such as "click".
method_name: class method name, the event method is like: function(evt){...}.
nMode:
===1: dynamic mapping, if fail to map statically, $bind will using $ec.$find() to search the dynamic element,
which may slow down the binding process.
===2: dynamic mapping, $bind will using $ec.$() to search the dynamic element, which may slow down the
binding process.
0/undefined/other: static mapping. elements in main-res or main-res chain can be statically mapped.
flag:
internal use; if normalized, flag=1.
flagi:
internal use; if derived from base, flagi=1; if it's duplicated item, flagi===0.
|
附录D. 调试选项
EC-IDE引擎内置一个简单调试信息输出窗口，可以预设调试参数，也可以在运行时动态设置调试状态。
调试参数
|
debug mode:
0: not-debug,
window.onerror- OFF debug bar- OFF //default
1: silent mode,
window.onerror- ON debug bar- OFF
2: debug,
window.onerror- OFF debug bar- ON
3: debug extend
window.onerror- ON debug bar- ON”
|
说明：
1. 如果EC引擎运行于非DOM环境，如WScript环境，则只支持debug=0；
预设调试参数例子
<script src=’ec.js’ id='_EC_ENGINE_'
debug=’2’></script>
动态设置调试状态
http:://www.myweb.com/myapp.htm?ec_debug=2
附录E. 类模型工作原理，及使用指定参数初始化基类
本节介绍的方法仅在确实有必要时，并且了解EC类模型的工作原理后才使用，开发者一般可以通过其它方法避免使用本节的方法。但本节会对开发者理解EC类的工作原理有所帮助。
EC
类入口函数（EC-Entry-Function
）的工作原理
如果$ec.$preload()方法只有2个参数，则EC引擎自动为第二参数（EC声明函数）建立一个默认JS构造器，
funcEntry= new Function("$ec.$init(this,arguments);");
这个JS构造器（也即EC入口函数）调用$ec.$init()进行以下3步工作：
1． 如果JS构造器是从$ec.$derive()进行调用的，立即返回，这样就跳过了基类EC构造器和本类EC构造器，直接构造了一个与prototype完全相同的实例；
2． 调用所有直接基类的EC入口函数；
3． 如果本类的EC类构造器存在，则调用之；
使用指定参数初始化基类
如果一个EC类的基类构造器的参数不为空，并且须要向基类传递指定的初始化参数，则按照前述的3个步骤，建立一个自定义的EC入口函数，将其作为$ec.$preload的第3个参数传入，代码例子如下：
$ec.$preload(
"org.supertree.dom.Control.MenuBar",
function()
{
this.prototype=$ec.$derive(
"org.supertree.dom.Popup.PopupMenu",
{
MenuBar: function( e, p )
{
……
},
……
}
);
},
function( e, p ) //ec-class entry
{
//step 1
if( arguments.callee.caller===$ec.$derive ) return;
//step2
$ec.$init(this,[e],arguments.callee.$base[0]); //only [e] as arguments
//step 3
this.MenuBar(e,p);
}
);
说明：
1． EC入口函数必须以3参数的形式对每个直接基类调用$ec.$init()，以完成对其EC入口函数的调用；
2． 对多层继承的情况，如果调用非直接基类，可能会出现多次调用非直接基类EC入口函数的情况，产生不可预知的结果；
3． $ec.$init()不可出现在EC入口函数以外的调用中，而且必须以3参数的形式调用，否则会产生不可预知的结果；
附录F. EC引擎加载过程
如果Web应用为<body>指定了绑定的js类，那么EC-IDE引擎加载时实现以下过程：
1. 在window.onload调用$ec.$bind()绑定<body>和指定的入口类；
2. 通过分析HTML/HTMI的jclass属性，自顶(<body>)向底加载类的主资源（将主资源HTMI设置为innerHTML）；
3. 自底向顶(<body>)创建Javascript类实例，将类实例与关联的DOM元素绑定；
4. 创建Javascript类实例的同时进行事件映射；
说明：
1. 当创建一个绑定于DOM元素的Javascript类实例时，在调用其EC入口函数和EC构造函数之前，对应的DOM元素的所有子孙元素已完成了加载主资源的工作，并且所有子孙元素已完成绑定；
2. 当创建一个绑定于DOM元素的Javascript类实例时，在调用其构造函数之前，对应的DOM元素的所有祖先元素未完全加载主资源，并且没有绑定；
附录G. EC-IDE的DOM类库实现
EC-IDE实现了一个简单的DOM类库，EC-IDE集成环境是在这个DOM类库上实现的，用户也可以自行开发一套DOM类库，与EC-IDE引擎并不冲突。本节简单介绍这个类库，并提出一些在EC-IDE建立自身的过程中总结出来的设计方法和原则，用户可以参考。
G.1. 全局Z-index分配
resizer: 100->110(dragging)
popup menu: 105
Window Manager: 1000 -> *
_modal: 100000
dragger: 100000000
G.2. DOM基类、控件设计
1. 一般的DOM类可从org.supertree.dom.Base继承；
2. 当使用类向导指定DOM类作为基类，但对应基类没有对应模版时，可以指定使用Base类的模板文件Base.jst；
G.3. 窗体设计
1. 窗体从org.supertree.dom.Window.Window继承；
2. 窗体可以加载菜单/工具栏等；
3. 窗体有可重载OnCommand( cmd, pOut)方法，用于处理菜单/工具栏命令；
G.4. 对话框设计
由于当前2种流行浏览器ie6/firefox对于实现对话框有诸多不一致和不必要的权限设置，EC-IDE自行实现异步式对话框，以解决一些设计上的不便。
1. 将对话框划分为运行前和运行后2个方法进行处理；运行前方法用于打开对话框，运行后方法用于处理关闭对话框后的数据处理；运行后方法使用非DOM回调接口方案；
2. 对话框从org.supertree.dom.Window.Dialog继承；
3. 对话框是全局DOM对象，通常只建一次，后续调用将重新使用已建立的DOM对象；
4. 对话框有可重载InitModal( e, p )方法，用于初始化对话框；
5. 对话框不可重入，即不可在一个对话框打开时，打开另一个由相同Javascript类创建的对话框；可重入对话框应另行设计，使用this.DoModal打开；
6. 退出对话框使用this.ExitModal(cmd,pOut)方法；
由EC-IDE类向导生成的对话框可用以下代码打开：
$ec.$import("MyDialog").prototype.DoGlobalModal(
this.eid, //or this //回调对象或回调对象的绑定eid值
"OnMyMethod", //回调函数名称引用字串
p //初始化参数
);
附录H. EC-IDE引擎缩减版本
当前版本EC-IDE引擎除提供完整功能的源码外，还提供以下发
行版本和缩减版本，以方便和适应各种开发环境，
|
文件
|
源码
|
压缩
|
大小
|
功能说明
|
|
ec.js
|
Y
|
|
37k
| |
|
ec.r.js
|
|
Y
|
11k
|
同上，
发行版
|
|
Y
|
|
31k
|
去除调试工具，包括类模型实现、DOM
支持，源码
| |
|
ec_dom.r.js
|
|
Y
|
8k
| |
|
Y
|
|
10k
|
去除DOM支持和
调试工具，只
支持基本的类模型实现，源码；适用于非DOM环境，如WSH等；
| |
|
ec_class.r.js
|
|
Y
|
3k
|
同上，发行版
|
说明：
1. 以上版本不可同时载，只能选择其中之一，否则会抛出异常；
3. $ec()快捷工具只在包含DOM支持的版本中使用；
575
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
