实战IBM Lotus Sametime 8.5 Web Client API
IBM Lotus Sametime 8.5 Web 客户端
Lotus Sametime 8.5 版本开始支持纯网页版的客户端，并且提供了灵活的网页版客户端的定制方式。这就让企业应用开发人员可以通过一些公共 API 将 Lotus Sametime 的即时聊天，会议等功能绑定到企业应用中，企业应用因此能使其用户具有实时沟通协作的能力。
Sametime Web 版公共 API 从架构上自底向上可以分为三个层次：REST API，基本功能模块以及 UI API。
REST API 是一些底层的与 Sametime 服务器交互数据的 API，这一层比较复杂并且不影响 Sametime Web 端的 UI 展现，不建议用户在这一层做任何修改。
REST API 上面一层就是由一些 Javascript 对象包装起来的基本功能模块，这些模块封装了 REST API 的低层调用，并构成了 Sametime UI 的基础，但不包含任何 UI 的展现。
UI API 是 Sametime 8.5 Web 版本的核心部件，它们实际上是由一系列的 Dojo 类组成。用户可以有选择性的引入部分 Dojo 组件来将 Sametime 8.5 的 Web 版本引入到各种 Web 应用中。
引入 Sametime Web 版主要是通过加载一些 Javascript 文件。清单 1 是一段示例的代码。
清单 1. 加载 Sametime Web 版
<script type="text/javascript" src="http://www.yoursametimeproxy.com:port /stbaseapi/baseComps.js"></script> <script type="text/javascript"> var stproxyConfig = { server: "http://www.yoursametimeproxy.com:portnumber" } // Dojo configuration: see Dojo Toolkit documentation var djConfig = { parseOnLoad: true }; </script> |
另外，为了保证 Sametime Web 版能正常显示，需要在 HTML 的 body 元素上加上一个 class=”tundra”，因为 Sametime Web 版是基于 Dojo toolkit 来构建的。
通常登陆到 Sametime 服务器需要用户提供用户名密码，但是在企业应用环境中一般都会有 SSO 的配置，就 Sametime Web 版的登陆方式而言，有三种方式都可以进行登陆。
- loginByPassword(username, password, initialStatus, initialStatusMessage, callBack, errorCallBack, clientId);
- loginByToken(username, initialStatus, initialStatusMessage, callBack, errorCallBack, clientId);
- loginAsAnon(username, initialStatus, initialStatusMessage, callBack, errorCallBack, clientId);
其中以 loginByToken 最为常见，这种登陆方式就是以 SSO 为基础的，这里需要将配置用户当前在开发的 Web 应用，使之与 Sametime proxy 服务器建立 SSO。清单２是一段使当前用户登陆到 Sametime 的示例。
清单 2. 登陆 Sametime Web 版
function loginUser() { stproxy.login.loginByToken(null, stproxy.status.AVAILABLE,'I am online'); } stproxy.addOnLoad(loginUser); |
当用户在运行完清单１中引入 Sametime Web 版的代码后，stproxy 作为一个全局变量在浏览器中就可以使用了，这个对象是用户代码访问 Sametime Web 版的各种功能的入口，本文后面提到的各种 Sametime 功能都需从该对象进入。类似的也可以用 stproxy.login.loginByPassword 和 stproxy.login.loginAsAnon 来登陆 Sametime Web。表１列出了这几个登陆函数中的参数意义以及期待的值。
表 1. 登陆参数
| 参数 | 类型 | 描述 |
|---|---|---|
| username | String | 登陆用户名 |
| password | String | 登陆的密码 |
| initialStatus | Numeric | 用户登陆 Sametime 后的初始状态，可以是： stproxy.awareness.OFFLINE stproxy.awareness.AVAILABLE or stproxy.awareness.ONLINE stproxy.awareness.AWAY stproxy.awareness.DND stproxy.awareness.NOT_USING stproxy.awareness.IN_MEETING stproxy.awareness.AVAILABLE_MOBILE or stproxy.awareness.ONLINE_MOBILE stproxy.awareness.AWAY_MOBILE stproxy.awareness.DND_MOBILE stproxy.awareness.IN_MEETING_MOBILE stproxy.awareness.UNKNOWN |
| initialStatusMessage | String | 初始状态的信息 |
| callback | Function | 登陆成功以后执行的 Javascript 方法 |
| errorCallBack | Function | 登陆失败以后执行的 Javascript 方法 |
| clientId | Numeric | 指出哪个应用在申请登陆 Sametime，一般无特殊需要可以置为空 |
登出 Sametime 可以调用 stproxy.login.logout(false, loggedOut, generalErrorHandler)；其参数及意义见表２所示。
表 2. 登出参数
| 参数 | 类型 | 描述 |
|---|---|---|
| isRealLogout | Boolean | true: 用户登出时所有 Sametime 窗口都是关闭；false: 用户登出时只有当前 Sametime 窗口是打开的 |
| callBack | Function | 登出成功以后执行的 Javascript 方法 |
| errorCallBack | Function | 登出失败以后执行的 Javascript 方法 |
对 Sametime 中联系人的管理几乎都可以由 Web 版中的 Javascript API 来完成。比如：获得当前登陆用户的所有联系人，查询所有的群组或某个特定的群组，添加新联系人到某个群组等等。下面依次列出了一些关键的完成这些操作的 Javascript API。
查询所有联系人
stproxy.buddylist.get(isWatchList/*Boolean*/, isWatchLocation/*Boolean*/, callBack/*function*/, errorCallBack/*function*/); |
添加一个群组
stproxy.buddylist.addGroup(groupId/*String*/,isPrivate/*Boolean*/, callBack/*function*/,errorCallBack/*function*/); |
从联系人中删除一个群组
stproxy.buddylist.removeGroup(groupId/*String*/, isPrivate/*Boolean*/, callBack/*function*/, errorCallBack/*function*/); |
重命名某一个群组
stproxy.buddylist.renameGroup(oldGroupId/*String*/, newGroupId/* String */, callBack/*function*/, errorCallBack/*function*/); |
查询所有群组
stproxy.buddylist.getGroups(isPrivate/*Boolean*/, callBack/*function*/, errorCallBack/*function*/); |
查询一个群组
stproxy.buddylist.getGroup(groupId/*String*/, isPrivate/*Boolean*/, callBack/*function*/, errorCallBack/*function*/); |
添加新联系人到某群组
stproxy.buddylist.addUser(userId/*String*/, groupId/*String*/, callBack/*function*/, errorCallBack/*function*/); |
从群组删除联系人
stproxy.buddylist.removeUser(userId/*String*/, groupId/*String*/, callBack/*function*/, errorCallBack/*function*/); |
Sametime Web 端 API 对于聊天窗口的行为同样也有相应的封装。比如打开一个与某个联系人的聊天窗口，或者打开一个与多个联系人同时聊天的窗口。
stproxy.openChat(userId/*String*/); stproxy.openGroupChat(userIds/*Array*/, topic/*String*/); |
Sametime 强大的在线会议功能为很多企业提供了便利的协作工作。在 Web 端 API 中对会议的支持也相当全面。用户可以从以下函数列表中找到大部分的会议操作。
1. 邀请联系人加入现有的在线会议，inviteList 数组包含所有被邀联系人的 id，url 表示该在线会议的地址。
stproxy.meeting.inviteToMeetingRoom(topic/*String*/, inviteList/*Array*/, url/*String*/, callBack/*function*/, errorCallBack/*function*/); |
2. 邀请联系人加入新的在线会议
stproxy.buddylist.createInstantMeeting(topic/*String*/, inviteList/*Array*/, callBack/*function*/, errorCallBack/*function*/); |
3. 获得当前所有可用的会议
stproxy.buddylist.getRooms(callBack/*function*/, errorCallBack/*function*/); |
1. 修改用户 Sametime 的状态，status 是一个整数，请参考表 1 中 initialStatus 的值来设置。
stproxy.status.set(status/*Numeric*/, statusMessage/*String*/, callBack/*function*/, errorCallBack/*function*/); |
2. 对联系人的模糊查询。
stproxy.quickfind.get(searchstring/*String*/, callBack/*function*/, errorCallBack/*function*/); |
3. 获得某联系人的详细信息。
stproxy.person.getUserInfo(user/*String*/, callBack/*function*/, errorCallBack/*function*/); |
4. 发送一个信息给某些联系人，receivers 是一个包含联系人 id 的数组。
stproxy.buddylist.sendAnnouncement(receivers/*Array*/, message/*String*/, isAllowed/*Boolean*/, callBack/*function*/, errorCallBack/*function*/) |
如果说之前的一些 API 介绍的是 Sametime 核心的功能，那么从这一部分开始就是直接操纵或者定制 Sametime UI 了。Sametime 8.5 Web 版 UI 是基于 Dojo 开发的，所有 Sametime 默认提供的 Web UI 组件都具有了 Dojo 组件可扩展的优点。用户可以通过初始化以下这些 Sametime Dojo 类来生成相应的 Sametime UI。
- sametime.WebClient
- sametime.Awareness
- sametime.QuickFind
- sametime.LiveName
- sametime.Chat
- sametime.GroupChat
- sametime.UserInfo
- sametime.BusinessCard
当然，一些额外的 Javascript 库以及 css 还需要在用户的页面上提前加载，如清单 3 所示。
清单 3. 加载 widget 所需资源
<link rel="stylesheet" type="text/css" href="/stwebclient/dojo_1.2.3/sametime/themes/ WebClientAll.css" /> <script type="text/javascript" src="/stbaseapi/baseComps.js"></script> <script type="text/javascript" src="/stwebclient/dojo_1.2.3/dojo/dojo.js"></script> <script type="text/javascript" src="/stwebclient/widgets.js"></script> |
这里以 sametime.Chat 为例来看该类是如何使用的。sametime.Chat 封装了一个聊天窗口的 UI 以及部分主要的窗口行为。用户可以使用 HTML 的方式来初始化该类，也可以用 Javascript 来创建该类的实例。
1. HTML 声明方式：
<div dojoType="sametime.Chat" userid="foo"></div> |
2. 用 Javascript 代码创建实例：
var client = new sametime.Chat({}); |
运行任意一种方式都可以得到如图 1 所示 UI。
图 1. Sametime Web 版聊天窗口示例
对上述 UI widget 的扩展跟一般的 Dojo widget 扩展没有本质区别，都是需要对一些 Javascript 方法进行覆盖，或者在加载 widget 前修改部分参数。这里限于篇幅，我们来讨论几个具体的例子来看看在实战中如何扩展 UI widget。
配置 Sametime UI
全局对象 stproxyConfig 是用于修改用户需要的默认 Sametime Web UI 的。该对象中有几个属性非常有用：
- cssUrl：用户想加载的额外的 CSS 文件路径。
- jsUrl：用户想加载的额外的 Javascript 文件路径。
- plugins：定义当前 UI 可以加载的各个 plugin 及其是否启用。具体形式为：
plugins: { "mmpFile": false, "cmpTools": false, "lnmpRemove": false }其中 mmpFile 即为一个 plugin。Sametime 自带的所有 plugin 请查阅参考资料中的相关产品文档。
在聊天窗口中增加一个自定义的菜单
默认的聊天窗口上面有三个菜单，如图 1 所示，分别是 File, Tools, Help。分别对应的菜单 ID 是 stproxy_fileMenu，stproxy_toolsMenu，stproxy_helpMenu。通过以下两个步骤，用户可以很轻松的做到在其中某个菜单下增加新的菜单项：
1. 修改 stproxyConfig 对象，使之加载一个额外的 Javascript 文件，该文件将提供定制聊天窗口的 Javascript 代码
清单 4. 修改 stproxyConfig
<script type="text/javascript"> var stproxyConfig = {server:" http://www.yoursametimeproxy.com", jsUrl: "myChatWindow.js"} </script> |
2. 编辑 myChatWindow.js 的内容，将该菜单项加入到现有的 Tools (stproxy_toolsMen) 下面。
清单 5. myChatWindow 示例代码
stproxy.uiControl.addChatMenuPlugin({ id:"myMenuId", label: "my Menu Label", menuId: "stproxy_toolsMenu", isShowEntry: function(widgets) {}, onClick: function(mainWindow) {} }); |
用户可以根据自己的逻辑需要来加入 Javascript 代码在 isShowEntry 和 onClick 中。isShowEntry 将会判断是否需要显示该菜单项，onClick 方法将会在用户点击菜单项时触发。在这两个方法中，用户可以调用 Dojo 基础的一些 API。
把聊天窗口嵌在当前页面
当用户调用到 sametime.WebClient 时，Sametime 的默认行为是把聊天窗口在一个新的浏览器窗口展现出来，要想做到把聊天窗口嵌入到当前页面，用户需要把聊天窗口的打开方法重写掉。
1. 创建一个 Dojo 的 tab container 来包住用户想嵌入的聊天窗口
清单 6. tab container
<div dojoType="dojo.layout.TabContainer"> <div dojoType="dijit.layout.ContentPane"> <div dojoType="sametime.WebClient"></div> </div> </div> |
2. 将 stproxy.createChat 方法覆写，这段 Javascript 代码可以放在页面加载的过程中。
清单 7. 覆盖 createChat 方法
stproxy.createChat = function(partnerId) { var chat = new sametime.Chat({partnerId: partnerId}); var tab = new dijit.layout.ContentPane({ closable: true, title:stproxy.STProxy.getDisplayName(partnerId) }); tab.containerNode.appendChild(chat.domNode); tabContainer.addChild(tab); tabContainer.selectChild(tab); return chat; } |
学习
- 阅读 使用 IBM Lotus Sametime 监控可用性、性能和基础架构以及其他要素。
- 阅读 IBM Lotus Sametime Server 故障诊断与排除。
- 参考 IBM Lotus Sametime wiki。
- 参考 IBM Lotus Sametime 主页。
- 在 Sametime 论坛中获得帮助。
- 访问 developerWorks Lotus 专区。
- 随时关注 developerWorks 技术活动和网络广播。
