request.md.svn-base

一款开源强大的javascript控件

Class: Request {#Request}
=========================

对XMLHttpRequest的功能包装类

### 实现:

[Chain](/Class/Class.Extras#Chain), [Events](/Class/Class.Extras#Events), [Options](/Class/Class.Extras#Options)

### 语法:

	var myRequest = new Request([options]);

### 参数:

2. options - (*object*, 可选) 参见下列可选项

###	可选项:

* url        - (*string*: 默认为 null) 请求的目标URL
* method     - (*string*: 默认为 'post') HTTP请求方法, 可以是: 'post' 或 'get'
* data       - (*string*: 默认为 '') 为[Request:send][]方法提供的默认请求参数
* async      - (*boolean*: 默认为 true) 如果为false, 则请求将以同步方式进行
* encoding   - (*string*: 默认为 "utf-8") 请求的编码方式
* link       - (*string*: 默认为 ignore) 可以为'ignore', 'cancel' 或 'chain'
	* 'ignore' - 当请求正在执行之中时,新的请求将被忽略
	* 'cancel' - 当请求正在执行之中时,将立即取消当前执行中的请求,开始执行新的请求
	* 'chain'  - 当请求正在执行之中时,将会把新的请求链接在当前请求之后,依次执行所有请求
* headers    - (*object*) 请求头数据
* isSuccess  - (*function*) 可覆盖内置的isSuccess函数,可自定义请求成功的规则


Request 事件: events {#Request:events}
----------------------------------------

### request

(*function*) 当请求发送时触发

#### 标识:

	onRequest(instance)

#### 参数:

1. instance - (Request) Request实例

### success

(*function*) 当请求完成时触发

#### 标识:

	onSuccess(responseText, responseXML)

#### 参数:

1. responseText - (*string*) 请求响应的文本数据
2. responseXML  - (*mixed*)  请求响应的XML对象

### failure

(*function*) 当请求失败时触发(根据http请求错误代码判断)

#### 标识:

	onFailure(instance)

#### 参数:

instance - (Request) Request实例

### exception

(*function*) 当请求头被设置成失败时触发

#### 标识:

	onException(headerName, value)

#### 参数:

1. headerName - (*string*) 失败请求头的名字
2. value      - (*string*) 失败请求头的值

###	cancel

(*function*) 当请求被取消时触发

#### 标识:

	onCancel()

### 属性:

* running  - (*boolean*) 请求是否正在执行
* response - (*object*)  包含了text和XML两个键的对象. 在success事件中可以访问此属性

### 返回值:

* (*object*) Request实例

### 示例:

	var myRequest = new Request({
		method: 'get', 
		url: 'http://site.com/requestHandler.php'
	}).send('name=john&lastname=dorian');

### 另参考:

 - [Wikipedia: XMLHttpRequest](http://en.wikipedia.org/wiki/XMLHttpRequest)


Request 方法: setHeader {#Request:setHeader}
--------------------------------------

增加或修改请求头数据. 

本方法不会覆盖创建请求时给出的可选项中的请求头信息.

###	语法:

	myRequest.setHeader(name, value);

###	参数:

1. name  - (*string*) 请求头名
2. value - (*string*) 请求头值

###	返回值:

* (*object*) Request实例

###	示例:

	var myRequest = new Request({
		url: 'getData.php', 
		method: 'get', 
		headers: {'X-Request': 'JSON'}
	});
	
	myRequest.setHeader('Last-Modified','Sat, 1 Jan 2005 05:00:00 GMT');


Request 方法: getHeader {#Request:getHeader}
--------------------------------------

获取请求头数据

###	语法:

	myRequest.getHeader(name);

###	参数:

1. name - (*string*) 请求头名

### 返回值:

* (*string*) 请求头值
* (*null*) 未找到指定值,则返回null

### 示例:

	var myRequest = new Request(url, {
		method: 'get', 
		headers: {'X-Request': 'JSON'}
	});
	
	var headers = myRequest.getHeader('X-Request'); //返回 'JSON'.


Request 方法: send {#Request:send}
----------------------------

打开连接, 发送请求

###	语法:

	myRequest.send([options]);

###	参数:

1. options - (*object*, 可选) 发送请求时的可选项. 也可以是一个查询字符串(提供该功能仅仅是为了兼容之前版本的用法)

###	返回值:

* (*object*) Request实例

###	示例:

	var myRequest = new Request({
		url: 'http://localhost/some_url'
	}).send("save=username&name=John");

Request 方法: cancel {#Request:cancel}
--------------------------------

取消执行中的请求

###	语法:

	myRequest.cancel();

###	返回值:

* (*object*) Request实例

###	示例:

	var myRequest = new Request({
		url: 'mypage.html', 
		method: 'get'
	}).send('some=data');
	
	myRequest.cancel();



Hash: Element.Properties {#Element-Properties}
==============================================

参见[Element.Properties](/Element/Element/#Element-Properties)

Element 属性: send {#Element-Properties:send}
-------------------------------------------------

### 设置

为元素设置一个Request实例(在使用ajax方式处理表单时非常有用)

#### 语法:

	el.set('send'[, options]);

#### 参数:

1. options - (*object*) Request的可选项

#### 返回值:

* (*element*) 主调元素

#### 示例:

	//myForm是一个表单
	myForm.set('send', {
		url: 'contact.php', 
		method: 'get'
	});
	
	myForm.send(); //发送表单数据

### 获取

获取先前设置的Request实例(或者使用默认可选项来创建的新实例)


#### 语法:

	el.get('send'[, options]);

#### 参数:

1. options - (*object*, 可选) Request可选项. 如果给出了该项, 则将总是返回一个根据给出的可选项创建的一个新Request实例

### 返回值:

* (*object*) Request实例

#### 示例:

	el.get('send', {method: 'get'});
	el.send();
	el.get('send'); //返回Request实例
	

Native: Element {#Element}
==========================

Element 方法: send {#Element:send}
------------------------------------

将一个表单元素或一个含有数据输入元素的容器元素进行发送

### 语法:

	myElement.send(url);

### 参数:

1. url - (*string*, 可选) 发送的目标URL. 如果发送的是表单元素, 若省略该URL, 则表单上的action属性值将作为该URL的值. 如果是其他容器元素,则不能省略该URL.

### 返回值:

* (element) 主调元素

### 示例:

##### HTML

	<form id="myForm" action="submit.php">
		<p>
			<input name="email" value="[e-mail]">
			<input name="zipCode" value="90210">
		</p>
	</form>

##### JavaScript

	$('myForm').send();

### 备注:

* URL将尝试从表单元素的action属性上自动获取



[$]: /Element/Element/#dollar
[Request:send]: #Request:send