# 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 字段的数据类型，包括一下数据类型：
类型 意义
int 整形
datetime 日期
string 字符串数
object 对象
array 数组
model 数据模型
collection 数据集合
* ### 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包括以下方法：
方法 意义
length[min,max] 字段值的长度在min-max的范围。
minlength(min) 字段值不小于min
maxlength(min) 字段值不大于min
required 字段值不能为空
unique 字段值必须唯一
telephone 字段值必须为电话号码格式
mobilephone 字段值必须为手机号码格式,长度为11位且必须为数字
email 字段值必须为email格式
onlyletter 字段值必须是字母
nospecialchars 字段值不能包含特殊字符
date 字段值必须是日期格式
url 字段值必须是URL
chinese 字段值必须是中文
注：多个验证条件之间使用" | "连接 {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}} 用法示例：

{{#foreach customObj}} {{key}} : {{value}} {{/foreach}}

* ### 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: 事件的类型, 可接受多个事件以空格分开，支持原生事件的透传, 支持的一些事件类型有:
pinchstart 双指缩放动作开始
pinchend 双指缩放动作结束
pinch 双指缩放事件
pinchin 双指向里缩小
pinchout 双指向外放大
rotateleft 向左旋转
rotateright 向右旋转
rotate 旋转事件
swipestart 单指滑动动作开始
swiping 单指滑动事件
swipeend 单指滑动动作结束
swipeleft 单指向左滑动
swiperight 单指向右滑动事件
swipeup 单指向上滑动
swipedown 单指向下滑动
swipe 单指滑动事件
drag 单指向左右拖动
hold 单指按住不放事件
tap 单指点击
doubletap 单指双击
例如旋转实例如下： 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)'; }); 更多使用实例请查看 * 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文件夹例外。