API 文档

##Router

用于建立URL(其路径部分)和Controller的对应关系，一个Controller可以对应多个URL，但是一个URL只能对应一个Controller。

add

  语法：add({pattren:'', action:''})

在router中添加一组pattren与Controller的对于关系

  sumeru.router.add(
  	{
  		pattern: '/studentList',
  		action: 'App.studentList'
  	}
  );

pattern

URL(其路径部分的值)
action

对应Controller的名称

如果你想关闭Server渲染，可使用下面方法：

  sumeru.router.add(
      {
       	pattern: '/studentList',
          action: 'App.studentList'
       	server_render:false
   	}
  )

server_render

Server渲染开关，false：关闭，默认为开启

setDefault

  语法：setDefault(controllerName)

设置默认启动Controller

  sumeru.router.setDefault('App.studentList');

externalProcessor.add(processor);

  语法：sumeru.router.externalProcessor.add(processor);

添加外部处理器

  添加一个backbone的外部处理器

  sumeru.router.externalProcessor.add(Backbone.Router.extend());

Model

Model用来定义App的数据模型。

 Model.student = function(exports){
    exports.config = {
    	fields: [
    		{name : 'studentName', type: 'string'},
       		{name :	'age',         type: 'int'},
      		{name :	'gender',      type: 'string'}
    	]
	};
 };

属性

name

字段的名称
type

字段的数据类型，包括一下数据类型：

<tr style="background-color:#3982ff">
	<th>类型</th>
	<th>意义</th>
</tr>

<tr>
	<th>int</th>
	<th>整形</th>
</tr>

<tr>
	<th>datetime</th>
	<th>日期</th>
</tr>

<tr>
	<th>string</th>
	<th>字符串数</th>
</tr>
<tr>
	<th>object</th>
	<th>对象</th>
</tr>
<tr>
	<th>array</th>
	<th>数组</th>
</tr>
<tr>
	<th>model</th>
	<th>数据模型</th>
</tr>
<tr>
	<th>collection</th>
	<th>数据集合</th>
</tr>

relation

使用relation时type属性值必须为“model”。
```
  {name: 'class',  type: 'model', relation: 'one' , model:'Model.class'},
```
- one
  
  引用一个Model
- many
  
  引入一个Collection

defaultValue

字段的默认值

  {name: 'gender',  type: 'string', defaultValue:'male'},

validation

  {name: 'name',  type: 'string', validation:'length[1,20]'},

字段的验证，validation包括以下方法：

<tr style="background-color:#3982ff">
	<th>方法</th>
	<th>意义</th>
</tr>

<tr>
	<th>length[min,max] </th>
	<th> 字段值的长度在min-max的范围。</th>
</tr>

<tr>
	<th>minlength(min)</th>
	<th>字段值不小于min</th>
</tr>

<tr>
	<th>maxlength(min)</th>
	<th>字段值不大于min</th>
</tr>
<tr>
	<th>required</th>
	<th>字段值不能为空</th>
</tr>
<tr>
	<th>unique</th>
	<th>字段值必须唯一</th>
</tr>
<tr>
	<th>telephone</th>
	<th>字段值必须为电话号码格式</th>
</tr>
<tr>
	<th>mobilephone</th>
	<th>字段值必须为手机号码格式,长度为11位且必须为数字</th>
</tr>
<tr>
	<th>email</th>
	<th> 字段值必须为email格式</th>
</tr>

<tr>
	<th>onlyletter</th>
	<th>字段值必须是字母</th>
</tr>

<tr>
	<th>nospecialchars</th>
	<th>字段值不能包含特殊字符</th>
</tr>
<tr>
	<th>date</th>
	<th>字段值必须是日期格式</th>
</tr>
<tr>
	<th>url</th>
	<th>字段值必须是URL</th>
</tr>

<tr>
	<th>chinese</th>
	<th>字段值必须是中文</th>
</tr>

注：多个验证条件之间使用" | "连接

	{name: 'name',  type: 'string', validation:'length[1,20]|required'},

addRule

除了上面的验证方法外，还可以自定义验证方法。

  sumeru.validation.addRule(ruleName,{
  								"runat" : "client",

  								验证方法  ,

  								"msg"   : "",
  							   });

ruleName

验证方法的名称，如"chinese"、"url"
runat

定义在哪个端上（client/server）进行验证
- client
  
  在客户端上进行验证
- server
  
  在服务器端进行验证
- both
  
  两段都需要验证

验证方法：该API中框架提供三种自定义验证方法（三种方法（regxp/func/asyncFunc）每次只能使用一种）

regxp

使用自定义正则表达式对字段进行验证

    sumeru.validation.addRule(ruleName,{
                                          "runat" : "client",

                                          "regxp" : "()",

                                          "msg"   : "",
                                  });

func

使用自定义函数对字段进行验证

    sumeru.validation.addRule(ruleName,{
                                           "runat" : "client",

                                           "func" : function(){},

                                           "msg"   : "",
                                  });

asyncFunc

该验证函数在服务器端运行，先获取指定modelObj的数据，然后根据asyncFunc中的方法进行验证，在callback中给出验证的结果。

    sumeru.validation.addRule(ruleName,{
                                          "runat" : "client",

                                          "asyncFunc":function(callback,k,v,modelObj){}

                                          "msg"   : "",
                                  });

msg

验证失败后返回的信息

create

  语法：create(modelName)

创建一个model

  var newStudent = sumeru.model.create('Model.student')

setter
```
  newStudent.studentName = 'John';		
```

set

  语法：set(key,value)

设置Model中相应字段的值

  newStudent.set('studentName','John');

setData

  语法：setData(dataMap)

使用dataMap对Model赋值

  newStudent.setData({'studnetName' : 'Smith',
  					        'age' : 19,
  					     'gender' : 'male'
  				  });

getter
```
  var name = newStudent.studentName;
```

get

  语法：get(key)

获取某一字段的值

  newStudent.get('studentName');

getId

  语法：getId()

获取model的唯一Id

  newStudent.getId();

getData

  语法：getData()

返回一个JSON数据对象

  newStudent.getData();

destroy

  语法：destroy()

删除model

  newStudent.destroy();

onValidation

  语法：onValidation(ispass, runat, validationResult)

对Model验证结果的监听方法

ispass

验证是否通过的标志
- true
  
  验证通过
- false
  
  验证不通过
runat

返回进行验证的端（客户端或者服务器端）
- client
  
  表示在客户端进行验证
- server
  
  表示在服务器端进行验证

validationResult

验证返回信息

 newStudent.onValidation = function(ispass, runat, validationResult){
 
 	if(ispass){console.log("Validation success ！");}

 	console.log((runat=='client'?'Client':'Server')+(ispass==true?'Validation Success!':'Validation failed!'));

 	for(var i = validationResult.length-1; i>=0; i--){
 		console.log(runat=='client'?'Client':'Server')+'result is：'+validationResult[i].msg);
 	}
 };

详细代码和说明请参考《Examples》文档。

Collection

Collection是Model的集合，我们之前曾使用过的subscribe()返回的结果集即是Collection。

session.studentCollection = env.subscribe("pub-allStudents",function(myCollection){

});

create

  语法：create(dataMap)

创建一个Collection

  sumeru.collection.create({'studnetName' : 'Smith',
  					        	  'age' : 19,
  					           'gender' : 'male'
  				        });

size

  语法：size()

获取collection中包含Model的数量。

  session.studentCollection.size();

add
```
  语法：add(row)
```
在collection中添加一行数据（每行数据实际是一个Model）。
```
  session.studentCollection.add(newStudent);
```

update

  语法：update(updateMap,where)

更新collection中满足条件的数据。

  session.studentCollection.update({'name':'Jack'},{'name':'John'});

remove
```
  语法：remove(where)
```
将数据从collection中去除，但并不实际删除。
```
  session.studentCollection.remove({'name':'John'});
```
当没有参数时，去除collection中所有数据。
destroy
```
  语法：destroy(where)
```
将数据从collection中实际删除。
```
  session.studentCollection.destroy({'name':'John'});
```
当没有参数时，删除collection中所有数据。
setData
```
  语法：setData(dataMap)
```
使用dataMap对Model赋值
find
```
  语法：find(where)
```
查询Collection中符合条件的所有数据。
```
  session.studentCollection.find({'name':'John'});
```
当没有参数时，返回所有的数据。

addSorters

  语法：addSorters()

collection中添加排序方法

  session.studentCollection.addSorters('time','DESC')

collection按照"time"降序排序。

clearSorters

  语法：clearSorters()

清空collection中排序方法

  session.studentCollection.clearSorters();

applyStorters

  语法：applyStorters()

手动执行所有的排序方法

  session.studentCollection.applyStorters();

get

  语法：get()

根据下标取出对应的数据

  session.studentCollection.get(2);

toJSON

  语法：toJSON()

返回一个JSON对象

  session.studentCollection.toJSON();

getData

  语法：getData()

获取包含所有数据的数组

  session.studentCollection.getData();

save

  语法：save()

将collection的修改保存到Server。

  session.studentCollection.save();

pluck

  语法：pluck(key)

返回Collection某一字段所有数据的数组

  session.studentCollection.pluck('age');

hold

  语法：hold()

暂停collection实时更新

  session.studentCollection.hold();

releaseHold

  语法：releaseHold()

恢复对collection的实时更新

  session.studentCollection.releaseHold();

where
```
  语法：where()
```
在collection中指定查询条件，需要与find、update、remove、destroy连用。
```
  session.studentCollection.where({'gender':'male'});
  
  session.studentCollection.find();
```
返回collection中‘gender’值为‘male’数据的数组。

orWhere

  语法：orWhere()

在collection中添加一个“or”条件，需要与find、update、remove、destroy连用。

  session.studentCollection.orWhere({'gender':'male'});
  
  session.studentCollection.find();

clearWheres

  语法：clearWheres()

清空collection中所有查询条件

  session.studentCollection.clearWheres()

View

View使用handlebars组件作为模板引擎，handlebars语法请参考官网。

为了更快的开发视图代码，Clouda对handlebars的语法做了一些扩展：

view中引入view
```
  语法： {{> viewName}}
```
在一个View中引用另一个View。
view中使用JS
```
  语法： {{$ alert("data.length"); }}
```
在View中直接执行Javascript代码，并将返回结果输出在View中。

foreach

用于快速遍历一个对象或数组

  语法：{{#foreach}}{{/foreach}}

用法示例：

    <p id="test-foreach-caseB">
        {{#foreach customObj}}
            {{key}} : {{value}}
        {{/foreach}}
    </p>

compare

比较两个对象

  语法：
      {{#compare a operator b}}
      {{else}}
      {{/compare}}

可以使用的operator：

operator
==
===
!=
!==
<
<=
>
>=
typeof

用法示例：

  {{#compare a "<" b}}
      a < b
  {{else}}
      a >= b
  {{/compare}}

  {{#compare a "typeof" "undefined"}}
      undefined
  {{/compare}}

注意：当省略operator时，系统默认使用操作符 ==：

  {{#compare 1 1}}
      1 == 1
  {{/compare}}

sumeru.config.view.set
```
  语法：sumeru.config.view.set('path', viewpath);
```
一般情况下将编写的view文件存放在app/view文件夹下，如果编写的view文件不在View文件夹下，我们也提供View文件路径配置的方法，框架会在配置路径下寻找需要的View文件:

实例：
```
  sumeru.config.view.set('path', 'path/to/');
```
则Clouda会在如下目录中加载视图：
```
  app目录/path/to/view/
```
注意:即使是修改viewpath的情况下，在最内一侧仍然需要有一层view文件夹，如上面路径的最后部分。

Transition

当场景发生转换时，通过transition定义场景转换效果。

 doRender(viewName,transition)

viewName

需要渲染View的名称
transition
- push
  
  推出
  - 方向
    - left
      
      从左向右推出
    - right
      
      从右向左推出
    - up
      
      从上向下推出
    - down
      
      从下向上推出
- rotate
  
  旋转
  - 方向
    - left
    - right
- fade
  
  渐变
  - 方向
    - z-index
      
      垂直方向
- shake
  
  退出场景时先缩小后放大退出，进入场景从左或者右边推入
  - 方向
    - left
      
      从左推入进场
    - right
      
      从右推入进场
- none
  
  没有转场效果
  - 方向参数
    - z
      
      默认参数
实例：
```
 env.onrender = function(doRender){
 	doRender('student', ['push', 'down']);
 };
 env.onrender = function(doRender){
 	doRender('student', ['none', 'z']);
 };
```

Controller

如果你曾经接触过MVC模型，那么将会很熟悉Controller的概念。在Clouda中，Controller是每个场景的控制器，负责实现App的核心业务逻辑。

create

  语法：sumeru.controller.create(function(env,session){});

创建一个Controller

  App.studentList = sumeru.controller.create(function(env,session){});

env
- redirect
```
   语法：env.redirect(queryPath,paramMap,isforce)
```
  一个Controller跳转到另一个Controller
```
      env.redirect('/studentList',{'class':'101'});
```
  - queryPath
    
    router中pattern的值
  - paramMap
```
  需要向跳转Controller传递的参数
```
  - isforce
    
    是否强制生成一个全新的Controller实例。
  如果在redirect中使用paramMap，可以在跳转目标Controller的create()中"param"接受参数。
```
  App.studentList = sumeru.controller.create(function(evn,session,param){


  });
```
- refresh
```
  语法： env.refresh()
```
  重新加载当前Controller
```
  env.refresh();
```
- onload
```
  语法：env.load()
```
  onload()是Controller的第一个时态，Controller中需要使用的数据都在这个时态中加载。
```
  env.onload = function(){
      return [ ];
  };
```
- onrender
```
  语法：env.onrender()
```
  当数据获取完成后，这些数据需要显示在视图(View)上，这个过程通过onrender()中的代码来实现，这是Controller的第二个时态，负责完成对视图(View)的渲染和指定转场方式。
```
  env.onrender = function(doRender){
      doRender(viewName,transition);
  };
```
- onready
```
  语法：onready()
```
  这是Controller的第三个时态，在View渲染完成后，事件绑定、DOM操作等业务逻辑都在该时态中完成；每段逻辑使用session.event包装，从而建立事件与视图block的对应关系。
```
  env.onready = function(){

      session.event(blockID,function(){

      });

  };
```
- onsleep
```
  语法：env.onsleep()
```
  当Controller长时间不处于活动状态时，可能会被置为睡眠状态，以确保正在运行中的Controller具有足够的资源。如果需要在Controller被暂停之前运行一些逻辑（比如暂存状态等），可以在onsleep()中完成。
```
  env.onsleep = function(){
  };
```
- onresume
```
  语法：env.onresume()
```
  当处在睡眠状态的Controller被唤醒时，onresume()时态将被调用。该时态可用于执行一些恢复性业务逻辑
```
  env.onresume = function(){
  };
```
- ondestroy
```
  语法：env.ondestroy
```
  当Controller被销毁时，ondestroy()将被调用。
```
  env.ondestroy = function(){
  };
```
- onerror
```
  语法： env.onerror
```
  当前Controller收到错误消息时被触发
```
  env.onerror = function(){
  };
```

subscribe

  语法：  不带参数： env.subscribe(publishName, function(collection){});
          带参数：  env.subscribe(publishName,arg1,arg2, ... , function(collection){});

关于subscribe方法请查看“Publish/Subscribe”章节。

session

set

  语法：session.set(key,value)

在session中设置“key”的值

  session.set('page',10);

get

  语法：session.get(key)

获取session中“key”的值

  session.get('page');

bind
```
  语法：session.bind(block-id,dataMap)
```
将数据绑定到视图中block-id容器
```
  session.bind('student-list',{
  				
  	data : Collection.find()
  
  });
```
一般在subscribe(publishName,function(Collection){})的function(Collection){}中使用。

event

  语法：seesion.event(block-id,function(){})

建立事件与视图block的对应关系

  session.event('student-list'，function(){
  
  	var submitButton = document.getElementById('submit');
  	
  	submitButton.addEventListener('click', submitMessage); 
  
  });

eventMap

  语法：session.eventMap(id,eventMap)

对一个标签绑定多个事件

  session.eventMap('inputMessage',{
  
  	'focus':function(e){	
  		console.log('focus!');
  	},
  	
  	'blur':function(e){
  		console.log('blur');
  	},
  
  });

id

View中标签ID
eventMap

事件Map

commit

  语法：session.commit()

触发数据对应视图block的更新

  session.commit();

sub controller

创建的Controller可以作为另外一个Controller的子Controller使用。

callSubController

  语法：  callSubController(queryPath,options)

在当前Controller中调用一个子Controller，配合show()和hide()方法使用。

isready

  语法：env.isready(){}

当前Controller的子Controller已经加载完成

  env.isready = function(){
  };

show

  语法：env.show(){}

显示当前当前Controller的子Controller

  env.show = function(){
  };

hide

  语法：env.hide(){}

隐藏当前Controller的子Controller

  env.hide = function(){
  };

destory

  语法：env.destory(){}

销毁当前Controller的子Controller

  env.destroy = function(){
  };

Touch

在开发移动端的应用中会使用到很多的手势操作，例如一指拖动、两指旋转等等，为了方便开放者快速集成这些手势，在Clouda中内置了事件和手势库Library.touch，下面将详细的介绍如何使用Library.touch。

touch.config

语法： touch.config(config)

对手势事件库进行全局配置。

参数描述：

config为一个对象

  {
      tap: true,                  //tap类事件开关, 默认为true
      doubleTap: true,            //doubleTap事件开关， 默认为true
      hold: true,                 //hold事件开关, 默认为true
      holdTime: 650,              //hold时间长度
      swipe: true,                //swipe事件开关
      swipeTime: 300,             //触发swipe事件的最大时长
      swipeMinDistance: 18,       //swipe移动最小距离
      swipeFactor: 5,             //加速因子, 值越大变化速率越快
      drag: true,                 //drag事件开关
      pinch: true,                //pinch类事件开关
  }

touch.on

语法：touch.on(element, types, options, callback)

绑定指定元素的事件。

参数描述：

element: 元素对象或选择器。
types: 事件的类型, 可接受多个事件以空格分开，支持原生事件的透传, 支持的一些事件类型有:

<tr>
    <th> pinchstart </th>
    <th> 双指缩放动作开始 </th>
</tr>
<tr>
    <th> pinchend </th>
    <th> 双指缩放动作结束 </th>
</tr>
<tr>
    <th> pinch </th>
    <th> 双指缩放事件 </th>
</tr>
<tr>
    <th> pinchin </th>
    <th> 双指向里缩小 </th>
</tr>
<tr>
    <th> pinchout </th>
    <th> 双指向外放大 </th>
</tr>
<tr>
    <th> rotateleft </th>
    <th> 向左旋转 </th>
</tr>
<tr>
    <th> rotateright </th>
    <th> 向右旋转 </th>
</tr>
<tr>
    <th> rotate </th>
    <th> 旋转事件 </th>
</tr>
<tr>
    <th> swipestart </th>
    <th> 单指滑动动作开始 </th>
</tr>
<tr>
    <th> swiping </th>
    <th> 单指滑动事件 </th>
</tr>
<tr>
    <th> swipeend </th>
    <th> 单指滑动动作结束 </th>
</tr>
<tr>
    <th> swipeleft </th>
    <th> 单指向左滑动 </th>
</tr>
<tr>
    <th> swiperight </th>
    <th> 单指向右滑动事件 </th>
</tr>
<tr>
    <th> swipeup </th>
    <th> 单指向上滑动 </th>
</tr>
<tr>
    <th> swipedown </th>
    <th> 单指向下滑动 </th>
</tr>
<tr>
    <th> swipe </th>
    <th> 单指滑动事件 </th>
</tr>
<tr>
    <th> drag </th>
    <th> 单指向左右拖动 </th>
</tr>
<tr>
    <th> hold </th>
    <th> 单指按住不放事件 </th>
</tr>
<tr>
    <th> tap </th>
    <th> 单指点击 </th>
</tr>
<tr>
    <th> doubletap </th>
    <th> 单指双击 </th>
</tr>

例如旋转实例如下：

var angle = 30;
touch.on('#rotation .target', 'touchstart', function(ev){
ev.startRotate();
ev.originEvent.preventDefault();
ev.originEvent.stopPropagation();
});
touch.on('#rotation .target', 'rotate', {interval: 10}, function(ev){
var totalAngle = angle + ev.rotation;
if(ev.fingerStatus === 'end'){
  angle = angle + ev.rotation;
}

this.style.webkitTransform = 'rotate(' + totalAngle + 'deg)';
});

更多使用实例请查看http://code.baidu.com/

options(可选): 目前可配置的参数为:

  {
     //采样频率
     interval: 10,//性能参数，值越小，实时性越好， 但性能可能略差， 值越大， 性能越好。遇到性能问题时，可以将值设大调优，建议值设置为10。
     //swipe加速度因子（swipe事件专用）
     swipeFactor: 5 //(int: 1-10)值越大，速率更快。
  }

callback: 事件处理函数，该函数接受的参数为一个gesture event object, 可访问的属性有：
- originEvent //触发某事件的原生对象
- type //事件的名称
- rotation //旋转角度
- scale //缩放比例
- direction //操作的方向属性
- fingersCount //操作的手势数量
- position //相关位置信息, 不同的操作产生不同的位置信息。
- distance //swipe类两点之间的位移
- distanceX //swipe类事件x方向的位移
- distanceY //swipe类事件y方向的位移
- angle //swipe类事件触发时偏移角度
- factor //swipe事件加速度因子
- startRotate //启动单指旋转方法，在某个元素的touchstart触发时调用。

touch.live

语法：touch.live(selector, types, options, callback)

使用方法基本上与on相同，live的第一个参数只接受css3选择器。通过live()方法附加的事件处理程序适用于匹配选择器的当前及未来的元素（比如由脚本创建的新元素）

touch.off

语法：touch.off(element,types,callback)

解除某元素上的事件绑定。

参数描述：

element：元素对象或选择器
types：事件的类型
callback：时间处理函数

Publish/Subscribe

subscribe

订阅被发布的数据，与pubilsh配合使用

不带参数 env.subscribe(publishName, function(collection){});
```
  env.subscribe("pub-allStudents", function(studentCollection){

  });
```
- pulishName
  
  所定义的Publish的唯一名称，在一个App内全局唯一，该参数与sumeru.publish(modelName, publishName,function(callback))中的publishName名称需要保持一致。
- function(Collection){}
  
  Subscribe成功获得数据时，被调用的响应方法。

带参数 env.subscribe(publishName,arg1,arg2, ... , function(collection){});

  env.subscribe("pub-StudentsWithGender", "male", function(msgCollection){

  });

subscribeByPage

分页订阅数据
- 不带参数 env.subscribeByPage(publishName, options, function(collection){});
```
  var pageOption{
  	pagesize : 1, 
  	page : 2,
  	uniqueField : 'time'
  };
  
  env.subscribeByPage("pub-allStudents", pageOption, function(studentCollection){

  });
```
  - options
    
    分页设置
    - pageSize
      
      每页数据的数量
    - page
      
      页码
    - uniqueField
      
      排序的唯一字段名
- 带参数 env.subscribeByPage(publishName, options, arg1,arg2, ... , function(collection){});
```
  env.subscribeByPage("pub-StudentsWithGender", pageOption, "male", function(msgCollection){

  });
```
prioritySubscribe

在断线重新连接的情况下，使用prioritySubscribe方法订阅数据优先被调用，使用方式与subscribe相同。

publish

发布数据的方法，其运行在Server上。

不带参数 sumeru.publish(modelName,pubName,function(callback){},options)
- modelName
  
  被发布数据所属的Model名称
- pubName
  
  所定义的Publish的唯一名称，在一个App内全局唯一，该参数与Controller中subscribe()成对使用。
- function(callback)
  
  描述数据发布规则的自定义函数，在这里定义被发布数据所需要符合的条件。
- options
  
  可在此添加以下六种事件
  - beforeInsert
    
    在实际插入数据到数据库前的事件
```
  beforeInsert : function(serverCollection, structData, userinfo, callback){
      callback(structData);
  }
```
    - structData
      
      需要插入到数据库的数据，我们可以对该数据进行操作，然后将数据插入到数据库中，如果对数据没有修改，则将原数据添加到数据库中。
    - callback
      
      before系列的事件中如果不添加 callback()，将阻止数据对数据库的影响。
    - callback(structData)
      
      如果需要对原数据进行修改，可以传入参数structData
  - afterInsert
    
    在实际插入数据到数据库后的事件
```
  afterInsert : function(serverCollection, structData){
  }
```
  - beforeUpdate
    
    在实际更新数据库数据前的事件
```
  beforeUpdate : function(serverCollection, structData, userinfo, callback){
      callback();
  }
```
  - afterUpdate
    
    在实际更新数据库数据后的事件
```
  afterUpdate : function(serverCollection, structData){
  }
```
  - beforeDelete
    
    在实际删除数据库数据前的事件
```
  beforeDelete : function(serverCollection, structData, userinfo, callback){
      callback();
  }
```
  - afterDelete
    
    在实际删除数据库数据后的事件
```
  afterDelete : function(serverCollection, structData){
  }
```
实例：
```
  module.exports = function(sumeru){
      sumeru.publish('student', 'pub-allStudents', function(callback){
          var collection = this;

          collection.find({}, function(err, items){
              callback(items);
          });
      });
  }
```

带参数 sumeru.publish(modelName,pubName,function(arg1, ..., callback){},options)

实例：

  module.exports = function(sumeru){
      sumeru.publish('student', 'pub-allStudents', function(gender,callback){
          var collection = this;

          collection.find({'gender':gender}, function(err, items){
              callback(items);
          });
      });
  }

publishByPage

分页发布数据

  sumeru.publishByPage(modelName,pubName,function(arg1,arg2,...,pageOptions, callback){},options)

options

分页设置，有Controller中subscribeByPage()传入。

实例：

  sumeru.publishByPage('student', 'pub-allStudents', function(gender,options,callback){
      var collection = this;
      collection.find({ sort    :{'time':-1},
                        limit   : options.pagesize,
                        skip    : (options.page-1)*options.pagesize,
                        "gender": gender
                       }, function(err, items){
          callback(items);
      });
  });

sort

排序
limit

每页显示的个数
skip

当前页与起始页间隔的个数

详细的使用情况请查看《Example》文档中的实例。

publishPlain

用于发布简单对象，而非Collection。

  sumeru.publishPlain(modelName,pubName,function(callback){},options)

实例：

如果需要发布Collection中数据的总数量，可使用下面方法：

  fw.publishPlain('student', 'pub-allStudents', function(callback){
      var collection = this;

      collection.count({},function(err, count){
          callback(count);
      });
  });

下面的三种方法是包含权限中心的身份验证的Publish。

securePublish

在身份验证成功的情况下发布数据

  sumeru.publish(modelName,pubName,function(userinfo, callback){},options)

securePublishByPage

在身份验证成功的情况下分页发布数据

  sumeru.securePublishByPage(modelName,pubName,function(pageOptions,userinfo, callback){},options)

securePublishPlain

在身份验证成功的情况下发布简单对象

  sumeru.securePublishPlain(modelName,pubName,function(userinfo, callback){},options)

external

实现了三方数据同步的方法，用来满足从三方网站/三方接口获取和同步数据的需求。

extfind(pubName,callback)

在publish文件中发布第三方数据

  fw.publish('news','pubnews',function(callback){
      var collection = this;

      collection.extfind('pubnews',callback);
  });

使用该方法需要在publish下添加一个如何获取第三方数据的配置文件

config[pubname]

pubname

与publish中collection.extfind(pubname,callback)方法pubname一致，全局唯一
uniqueColumn

uniqueColumn为三方数据唯一标识，类型为String
```
  uniqueColumn : "name",
```
fetchUrl: function((/** arg1, arg2, arg3 */)){}

指定抓取的URL。arg1,arg2为传递的参数
```
  fetchUrl : function(/** arg1, arg2, arg3 */){
      return 'http://some.host.com';
  }
```
resolve : function(originData){}

resolve方法作用是将抓取回来的原始数据(originData)转化成为符合Model定义的数据(resolved)
```
  resolve : function(originData){
      var j = JSON.parse(originData);
      var resolved = j;
      return resolved;
  }
```
fetchInterval

fetchInterval为可选参数，用来指定抓取时间间隔，单位为ms
buffer

buffer为可选参数，值为true时表示获取原始Buffer，否则获取原始数据字符串

type

声明此模块为归属为'external'

  return {
      type : 'external',
      config : config
  }

实例如下：

  /**
   * 获取三方数据信息，由开发者自定义
   */
  function runnable(){
      //{Object} config是所有三方publish配置的容器
      var config = {};

      config['pubext'] = {
          //{String} uniqueColumn为三方数据唯一标识
          uniqueColumn : "name",

          //{Function} fetchUrl的参数就是订阅时发起的参数，返回值为pubext所抓取的url地址
          fetchUrl : function(/** arg1, arg2, arg3 */){
              return 'http://some.host.com';
          },

          //{Function} resolve方法作用是将抓取回来的原始数据(originData)转化成为符合Model定义的数据(resolved)
          resolve : function(originData){
              var j = JSON.parse(originData);
              var resolved = j;

              return resolved;
          },

          //{Number} fetchInterval为可选参数，用来指定抓取时间间隔，单位为ms
          fetchInterval : 60 * 1000,

          //{Boolean} buffer为可选参数，值为true时表示获取原始Buffer，否则获取原始数据字符串
          buffer : false
      }

      //最后需要声明此模块为归属为'external'
      return {
          type : 'external',
          config : config
      }

  }

  module.exports = runnable;

指定三方增/删/改接口以及数据

当数据发生变化时，如何使用Clouda达到三方数据同步的效果，具体实现方法如下：

较为紧凑的声明方式

postUrl

postUrl方法用来指定三方post接口的地址信息, 参数type为增量类型，增量类型为'insert','update','delete'三者之一;
prepare

prepare方法用来将增量数据转化成为符合三方POST接口要求的post数据，参数type同为增量类型，参数data为增量的实际数据。

实例如下：

  /**
   *	三方数据POST请求信息，由开发者自定义
   */
  function runnable(){

      var config = {}

      config['pubext'] = {

          /**
           * 声明三方POST接口地址
           * {String} type为'delete', 'insert', 'update'其中之一
           * 如果subscribe时带参数，参数会按照subscribe顺序接在postUrl的参数中
           */
          postUrl : function(type /** arg1, arg2, arg3... */){
              var options = {
                  host : 'some.host.com',
                  path : '/' + type ,
                  headers: {
                      //在此自定义header内容，clouda默认的 'Content-Type': 'application/x-www-form-urlencoded'
                      'Content-Type': ...
                  }
              }
              return options;
          },

          /**
           * prepare方法将增量数据转化为符合三方要求的post数据。
           * {String} type为增量操作，值为'delete', 'insert', 'update'其一;
           * {Object} data为增量数据，如：{ name : 'user1', age : 26 }。
           */
          prepare : function(type, data){
              var prepareData = {};  //prepareData为三方post所需的data
              if(type === "delete"){
                  prepareData.name = data.name;
              }else if(type === "insert"){
                  prepareData.name = data.name;
                  prepareData.age = data.age;
              }else{
                  prepareData.name = data.name;
                  prepareData.age = data.age;
              }

              return prepareData;
          }
      }

      return {
          type : 'external',
          config : config
      }

  }

  module.exports = runnable;

较为工整的声明方式

deleteUrl，insertUrl，updateUrl

三个方法作用等同于postUrl，返回不同操作下三方接口url信息
onDelete，onInsert，onUpdate

三个方法作用等同于prepare方法, 返回经过处理，传给三方接口的post数据

实例如下：

  function runnable(){

      var config = {};

      config['pubext'] = {
          //arg1, arg2, arg3是subscribe时输入的参数
          deleteUrl : function(/** arg1, arg2, arg3... */){
              return {
                  host : 'some.host.com',
                  path : '/delete'
              }
          },

          insertUrl : function(/** arg1, arg2, arg3... */){
              return {
                  host : 'some.host.com',
                  path : '/insert'
              }
          },

          updateUrl : function(/** arg1, arg2, arg3... */){
              return {
                  host : 'some.host.com',
                  path : '/update'
              }
          },

          onInsert : function(data){
              var prepareData = {};
              prepareData.name = data.name;
              prepareData.age = data.age;
              return prepareData;
          },

          onUpdate : function(data){
              var prepareData = {};
              prepareData.name = data.name;
              prepareData.age = data.age;
              return prepareData;
          },

          onDelete : function(data){
              var prepareData = {}
              prepareData.name = data.name;
              return prepareData;
          }
      }

      return {
          type : 'external',
          config : config
      }

  }

  module.exports = runnable;

sumeru.external.get

向第三方发送get请求

  var url = "http://some.host.com";
  var getCallback = function(data){
  	console.log(data);
  }
  sumeru.external.get(url, getCallback);

sumeru.external.post

向第三方发送post请求

  var options = {
      host : "some.host.com",
      path : "/insert"
  }

  var postData = {
      name : sumeru.utils.randomStr(8),
      age : parseInt( 100 * Math.random())
  }

  var postCallback = function(data){
      console.log(data);
  }

  sumeru.external.post(options, postData, postCallback);

sumeru.external.sync

将抓取最新的三方数据，并将新数据推送至前端

  var cb = function(data){
      console.log(data);
  }
  var url = "some.host.com";
  sumeru.external.sync(modelName, pubName, url, cb);

具体使用请查看《Example》文档中的SpiderNews实例。

Auth

create

创建一个auth对象

  sumeru.auth.create(env)

实例：

  var myAuth = sumeru.auth.create(env);

Auth对象的方法

on

增加一个用户系统相关的事件监听器

  on(type,handle);

参数说明：

type

每次认证状态变化时被触发，类型string，目前只支持一个事件类型,即 “statusChange”
handle

事件处理函数. 可接收两个参数err与status
- err
有错误产生时的错误对像
- status
  
  表示当前认证状态的字符串
  - not_login
    
    当前未登陆
  - logined
    
    已登陆
  - doing_login
    
    正在登陆过程中

实例：

  var myAuth = sumeru.auth.create(env);

  var statusChangeHandle = function(err,status){
      if(err){
          // err.code | err.msg
          return;
      };

      switch(status){
          case "not_login" :
              // do something
              break;
          case "logined" :
              // do something
              break;
          case "doing_login" :
              // do something
              break;
          default:
              // do something
      }
  }

  myAuth.on('statusChange',statusChangeHandle);

removeListener

移除由on方法增加的监听器
```
  removeListener(type,handle)
```
参数说明：
- type
  
  事件名称, 目前只支持一个事件,即“statusChange”
- handle
  
  事件处理函数
removeAllListener

一次性移除所有已添加的监听器事件
```
  removeAllListener(type)
```
参数说明：
- type
  
  事件名称, 目前只支持一个事件,即“statusChange”
实例：
```
  var myAuth = sumeru.auth.create(env);
  myAuth.removeAllListener('statusChange');
```

login

根据token,pwd登陆由authMethod所指定的类型用户系统. 不提供authMethod时默认为local. 登陆过程中的每次状态变化将触发statusChange事件

  login(token,pwd,[args],[authMethod])

参数说明：

token

用户的用户名，类型为string
pwd

用户的密码，类型为string
args

登陆时需附加的其它信息,具体内容根据authMethod的不同传入内容将不同.如不提供默认为{},类型为map，所有除用户名和密码外需要传入的其它数据（如验证码等），都需要通过这个args参数传入
authMethod

登陆用户的类型，默认为“local”，类型为string

实例：

  var myAuth = sumeru.auth.create(env);

  var statusChangeHandle = function(err,status){
      if(err){
          // err.code | err.msg
          return;
      };

      switch(status){
          case "not_login" :
              // do something
              break;
          case "logined" :
              // do something
              break;
          case "doing_login" :
              // do something
              break;
          default:
              // do something
      }
  }

  myAuth.on('statusChange',statusChangeHandle);

  // 完整的调用方式
  myAuth.login('userName','pwd',{a:100,b:200,c:[1,2,3]},'authMehtod_XXX');

  // 也可使用以下不完整的参数调用方式。
  // 1.省略authMethod认为 authMethod = 'local'
  // myAuth.login('userName',’pwd‘,{a:100,b:200});

  // 2.同时省略args与authMethod时，认为args={},authMethod='local'
  // myAuth.login('userName','pwd');

logout

登出，并触发statusChange变化

  logout()

实例：

  var myAuth = sumeru.auth.create(env);
  myAuth.logout();

getStatus

取得当前的认证状态. 返回值为String类型
```
  getStatus()
```
返回值如下：
- not_login
  
  当前未登陆
- logined
  
  已登陆
- doing_login
  
  正在登陆过程中
实例：
```
  var myAuth = sumeru.auth.create(env);
  myAuth.getStatus();
```
getLastError

取得最后一个操作发生的错误信息，每一个新操作产生时，上一次的错误信息将被清空
```
  getLastError()
```
实例：
```
  var myAuth = sumeru.auth.create(env);
  var errObj = myAuth.getLastError();

  console.log(errObj);
```

getUserInfo

取得当前认证用户的信息,如果未登陆则返回null

  getUserInfo()

实例：

  var myAuth = sumeru.auth.create(env);
  myAuth.getUserInfo();

userInfo结构如下：

  userInfo = {
      "token":"token",
      "info":{"param1":"modify1","param2":"modify2","param3":["1","2"]},
      "status":"online",
      "smr_id":"5253a5aa546610001200014a",
      "__clientId":"7qgj3s1grr",
      "userId":"5253a5a95466100012000148",
      "clientId":"183ou3qrg_QZKUYDxapKFO",
      "authMethod":"local",
      "expires":1381213910081
  }

注意：其中info字段的内容，来源于register时提供的userInfo

register

注册一个用户
```
  register(token,pwd,userInfo, authMethod, callback)
```
参数说明：
- token
  
  用户的登陆标识，类型为string
- pwd
  
  登陆密码，类型为string
- userInfo
  
  新的用户信息对像，类型为object
- authMethod
  
  目标的用户类型，类型为string
- callback
  
  注册完成后的回调方法,可接收一个err参数,当产生错误时返回对应的错误对像,如果成功,返回null
实例：
```
  var myAuth = sumeru.auth.create(env);
  myAuth.register('user123','pwd',{age:100},local,function(err){
      if(err){
          // 注册失败
          return；
      }
      // 注册成功
      // do something ..
  });
```
注意：在注册前，尽量使用sumeru.auth.registerValidate() 进行验证，可以有效减少错误发生。

registerValidate

测试一个注册信息是否可用

  registerValidate(userInfo,authMethod,callback)

参数说明：

userInfo

待测试的注册信息，类型为object
authMethod

用户类型，类型为string

callback

测试完成后的回调函数，可接收err与isUsefull参数

  * err

      产生错误是传入对应的错误对像

  * isUserfull

      值为`true`时表示测试的用户可以使用

实例：

  var myAuth = sumeru.auth.create(env);
  myAuth.registerValidate({token:'user123',age:100},'local',function(err,isUsefull){
      if(isUserfull){
          // 注册信息验证成功，可以进行注册
          myAuth.register('user123','pwd',{age:100},local,function(err){
              if(err){
                  // 注册失败
                  return；
              }
              // 注册成功
              // do something ..
          });
      }else{
          // 注册信息验证失败
          //err.code || err.msg
      }
  });

modifyUserInfo

修改用户信息
```
  modifyUserInfo(token,pwd,userInfo,authMethod,callback)
```
参数说明：
- token
  
  用户的登陆标识
- pwd
  
  登陆密码
- userInfo
  
  用户信息对像
- authMethod
  
  用户类型
- callback
  
  用户信息修改完成后的回调函数，可接受一个err参数，当修改信息发生错误时，返回产生的错误信息，如果修改成功，则返回null
modifyPassword

修改用户登陆密码信息
```
  modifyPassword(token,oldPwd,newPwd,authMethod,callback)
```
参数说明：
- token
  
  用户的登陆标识
- oldPwd
  
  当前密码
- newPwd
  
  新密码
- authMethod
  
  目标的用户类型
- callback
  
  修改完成后的回调函数，可接收一个err参数,当修改信息发生错误时，返回产生的错误信息,如果修改成功,则为null

Library

create

  语法：create(factory)

创建一个Library库，sumeru.Library.create(factory);

  Library.timeUtils = sumeru.Library.create(function(exports){	
  	exports.formatDate = function(time){
  		return time.getFullYear();
  	};
  });

getter

使用一个Library

  Library.timeUtils.formatDate(new Date());

Reachability

查看网络连接状态

getStatus

  语法：getStatus()

获取当前网络状态

  sumeru.reachability.getStatus();

网络状态有以下三种：

STATUS_OFFLINE

当前处于离线状态
```
  sumeru.reachability.STATUS_OFFLINE;
```
STATUS_CONNECTING

当前处于网络连接状态
```
  sumeru.reachability.STATUS_CONNECTING;
```

STATUS_CONNECTED

当前已连接到网络

  sumeru.reachability.STATUS_CONNECTED;

File Uploading

Library.fileUploader.init()

完成端上上传文件的初始化

具体方法：

var myUploader = Library.fileUploader.init({
    routerPath:"/files",
    onSuccess:function(urlLink){//成功之后的处理，此处有保存文件的逻辑

    },
    fileSelect:function(e){//用户选择文件之后的处理

    },
    onProgress:function(e){//进度更新

    },
    onError:function(e){//出错

    },
    onAbort:function(e){//中断

    },
});

routerPath

与router中的pattern对应
onSuccess:function(urlLink)

成功之后的处理，此处有保存文件的逻辑
fileSelect:function(e)

用户选择文件之后的处理
onProgress:function(e)

进度更新
onError:function(e)

当上传出错时在该方法中处理
onAbort:function(e)

当出现中断时在该方法中处理
startUpload()

端上上传文件的方法
```
  myUploader.startUpload();
```

package.js

package.js用于将文件之间的依赖关系添加到Clouda中，我们可以使用下面的语法编写该文件：

 sumeru.packages(
 	'student.js',
 	'class/',
 	..... ,

 	'studentList.js'
 )

如果参数为文件夹，则Clouda会加载相应文件夹下的package.js。

并不是在所有文件夹下新建文件或者文件夹后需要修改package.js文件，view文件夹和publish文件夹例外。

Files

step4_API_Documentation.md

Latest commit

History

step4_API_Documentation.md

File metadata and controls

API 文档

add

setDefault

externalProcessor.add(processor);

Model

属性

name

type

relation

defaultValue

validation

addRule

create

setter

set

setData

getter

get

getId

getData

destroy

onValidation

Collection

create

size

add

update

remove

destroy

setData

find

addSorters

clearSorters

applyStorters

get

toJSON

getData

save

pluck

hold

releaseHold

where

orWhere

clearWheres

View

view中引入view

view中使用JS

foreach

compare

sumeru.config.view.set

Transition

push

rotate

fade

shake

none

Controller

create

env

redirect

refresh

onload

onrender

onready

onsleep

onresume

ondestroy

onerror

subscribe

session

set

get

bind

event