Ajax - 人人网开放平台Wiki

[编辑] 功能描述

XNJS提供的Ajax对象，供app开发者使用JavaScript完成Ajax的各种操作。

[编辑] 工作原理

校内开放平台在用户浏览器和app服务器之间提供代理功能。当用户向app服务器发送Ajax请求时，请求会通过校内Ajax代理服务器转发；同样，app服务器的应答也通过校内Ajax代理服务器转发到用户浏览器。

[编辑] Ajax请求类型

出于安全考虑，校内Ajax对象只支持POST类型的请求。

[编辑] Ajax应答类型

校内Ajax对象支持三种应答类型：RAW、XNML和JSON。

Ajax应答类型	编码	描述
RAW	1	app服务器返回一段纯文本。
XNML	3	app服务器返回一段XNML片段，并以一个XNML_String对象的格式传递给XNJS Ajax对象的ondone函数（开发者定义的callback函数）。可以通过DOM节点的setInnerXNML设置为元素内容，或用来装饰Dialog。
JSON	2	app服务器返回JSON（JavaScript Object Notation）格式的一段文本。如果JSON对象的某个属性以“xnml_”开头，则属性值是一段XNML文本，同样该属性会成为一个XNML_String对象，传递给XNJS Ajax对象的ondone函数。

[编辑] Ajax API

构造函数

var ajax = new Ajax(Number responseType);

参数名	类型	描述	是否可选	默认值
responseType	Number	Ajax应答类型，可以是Ajax.RAW、Ajax.XNML或Ajax.JSON。	必选。	n/a

发送Ajax请求

void post(String url [, Object query, url_mode]);

出于安全考虑，校内Ajax只支持POST类型的请求。

参数名	类型	描述	是否可选	默认值
url	String	处理ajax请求的URL，根据参数url_mode的取值不同而有不同的限制。当url_mode=false时，它只能是app服务器的URL，即必须和app注册的canvas URL在同一个域下；当url_mode=true时，它必须是canvas URL，即以"http://apps.xiaonei.com/appalias/"开头的URL。在url参数中不推荐使用包含?开头的query string，要提交给app服务器的参数建议请使用第二个参数query来指定，如果url参数中包含?开头的query string，则一律由校内Ajax代理服务器转为POST请求发送给app服务器。	必选。	n/a
query	Object	浏览器提交的post参数是用&隔开的“name=value”的格式。query对象的属性名表示name，属性值表示value。query对象的属性值仍然可以是一个对象，并且支持多级嵌套，提交的post请求则以数组的形式发送给app服务器，详见示例。	可选。	默认为空。
url_mode	Boolean	设置Ajax的URL模式：如果为false，表示normal模式；如果为true，表示canvas模式。在normal模式下，Ajax只能向与app的callback URL同一域下的URL提交post请求，这种模式对开发者而言更接近真实的Ajax操作；而在canvas URL模式下，则必须向app的canvas URL，即http://apps.xiaonei.com/appalias/...提交post请求，这种模式则可以防止app的callback url暴露给用户。	可选。	默认为false。

处理Ajax应答

ajax.ondone(data);

校内Ajax要求开发者为Ajax对象定义callback函数，即ondone函数，当成功得到Ajax应答时会被调用。对于不同的应答类型，参数data有不同的格式，见下表ondone函数的参数介绍。

Ajax应答类型	参数data的类型	描述
RAW	String	由app服务器返回的未经过任何处理的字符串。
XNML	XNML_String	由app服务器返回的XNML片段，经过了校内XNML解析引擎的处理，表示为一个XNML_String对象。
JSON	Object	由app服务器返回的JSON文本生成的一个JSON对象。如果这个JSON对象的某个属性以“xnml_”开头，则属性值是代表一段XNML片段的XNML_String对象。

错误处理

ajax.onerror(errobj);

校内Ajax要求开发者为出错情况定义callback函数，即onerror函数，当Ajax请求出错时会被调用。

参数errobj是一个对象，它的属性包含了出错相关的信息。

参数errobj的属性	类型	描述
error	Number	错误码。
error_message	String	错误描述字符串。

[编辑] 示例

<script type="text/javascript">
<!--
  function app_ajax(type) {
    var ajax = new Ajax(type);
    ajax.ondone = function(data) {
      var ajax_display = document.getElementById('ajax_display');
      var json_display = document.getElementById('json_display');
      switch (type) {
        case Ajax.RAW:
          ajax_display.setTextValue(data);
          json_display.setTextValue('');
          break;
        case Ajax.JSON:
          var text =  'json.message = ' + data.message;
          text += '; json.type = ' + data.type;
          text += '; json.user_id = ' + data.user_id;
          ajax_display.setTextValue(text);
          json_display.setInnerXNML(data.xnml_user);
          break;
        case Ajax.XNML:
          ajax_display.setInnerXNML(data);
          json_display.setTextValue('');
          break;
      }
    }

    ajax.onerror = function(errobj) {
      var ajax_display = document.getElementById('ajax_display');
      var errmsg = '!!!<ERROR> error code: ' + errobj.error + '; error description: ' + errobj.error_message;
      ajax_display.setTextValue(errmsg);
    }

    var params = {
      type: type,
      user_id: Session.getUser(),
      param3: {in_param1: '333_111', in_param2: '333_222'}
    };
    ajax.post('http://www.leo.com/xnmlshell/demo/ajax_handler/ajax_all.jsp', params);
  }
//-->
</script>

<p><a href="#" onclick="app_ajax(Ajax.RAW); return false;">RAW</a></p>
<p><a href="#" onclick="app_ajax(Ajax.XNML); return false;">XNML</a></p>
<p><a href="#" onclick="app_ajax(Ajax.JSON); return false;">JSON</a></p>

<div id="ajax_display"></div>
<div id="json_display"></div>

点击上面的链接就会发送ajax请求，发送到app服务器的POST请求会是与下面类似的格式：

type=1&user_id=1234567&param3[in_param1]=333_111&param3[in_param2]=333_222

下面是一段jsp的代码样例，用于处理ajax请求。

<%
  String type = request.getParameter("type");
  if (type == null) {
  	type = "";
  }
  
  String user_id = request.getParameter("user_id");
  if (user_id == null) {
  	user_id = "";
  }
  
  String param3_in1 = request.getParameter("param3[in_param1]");
  if (param3_in1 == null) {
  	param3_in1 = "";
  }
  String param3_in2 = request.getParameter("param3[in_param2]");
  if (param3_in2 == null) {
  	param3_in2 = "";
  }
  
  StringBuffer value = new StringBuffer(128);
  if (type.equals("1")){//RAW
  	value.append("返回RAW字符串，type = ");
  	value.append(type);
  	value.append("; user_id = ");
  	value.append(user_id);
  	value.append("; param3[in_param1] = ");
  	value.append(param3_in1);
  	value.append("; param3[in_param2] = ");
  	value.append(param3_in2);
  	out.println(value);
  }
  else if (type.equals("2")){//JSON
  	value.append("{\"type\": ");
  	value.append(type);
  	value.append(", \"user_id\": ");
  	value.append(user_id);
  	value.append(", \"message\": \"返回了JSON对象\"");
  	value.append(", \"xnml_user\": \"你好，这是你的个人主页： <xn:profile-pic uid=\\\"loggedinuser\\\" 
             linked=\\\"true\\\"/>\"");
  	value.append("}");
  	out.println(value);
  }
  else if (type.equals("3")){//XNML
  	value.append("返回XNML片段，type = ");
  	value.append(type);
  	value.append("; param3[in_param1] = ");
  	value.append(param3_in1);
  	value.append("; param3[in_param2] = ");
  	value.append(param3_in2);
  	value.append("；你好，<xn:name uid=\"");
  	value.append(user_id);
  	value.append("\" linked=\"true\"/>");
  	out.println(value);
  }
  else {//Unknown type
  	out.println("Unknown type detected!");
	}
%>

[编辑] 相关章节

XNML_String

[编辑] 参考内容

有关JSON的信息请参考http://json.org

取自"http://dev.xiaonei.com/wiki/Ajax"

目录