Ajax Ajax.Updater - Prototype JavaScript 框架

Ajax.Updater

new Ajax.Updater(container, url[, options])

执行一个 AJAX 请求，并将响应内容更新到指定容器。

Ajax.Updater 是一个特殊的 Ajax.Request：后者所具备的功能，前者同样拥有。如果你不熟悉 Ajax.Request，请先阅读与之相关的文档，然后再回到本章。

new Ajax.Updater('items', '/items', { 
	parameters: { text:　$F('text') } 
});

更新完成后，onComplete 回调将会被调用。

因为 Ajax.Updater 的目标是使用 AJAX 请求所返回的响应文本更新指定 DOM 元素（容器）的内容，因此，除公用选项外，它还具有一些新的特定选项：

选项	默认值	描述
`evalScripts`	`false`	指出是否执行响应文本中包含的 `<script>` 元素下的脚本。
`insertion`	None	默认情形下，通过 Element.update 将指定容器的内容替换为响应文本。你可能希望插入响应文本到已有的内容中，在 1.6.0 以前的版本，你必须传入一个有效的 Insertion，例如 Insertion.Bottom。在 1.6.0 中，不再推荐使用这种标记方法。现在，你只需简单的传入 `'top'`，`'bottom'`，`'before'` 或 `'after'` 即可。

在下面的样例中，假设需要通过一个 AJAX 返回的 XHTML 片断创建新的条目，并放置到列表容器已有内容的后面：

new Ajax.Updater('items', '/items', 
	{ parameters: { text: $F('text') }, 
	insertion: Insertion.Bottom 
});

如果你使用 evalScripts: true，那么所有的 <script> 块将被执行。执行的意思不是仅仅将脚本放置在页面中，而是将它们的内容直接传递给原生的 eval() 函数，因此需要注意两点：

脚本块中脚本的作用域被限定在 Prototype 内部，在脚本块中使用 var 定义的变量在执行后马上被销毁，页面上其它地方的脚本永远无法访问到它。
译注：若要使用脚本块返回可在页面其它地方使用的变量，请直接使用变量名，而不要用 var 定义或预先声明，如 myVariant = 'this is a example'。
如果你在脚本块中定义了函数，你需要实际的创建它，否则页面上其它地方的脚本无法访问这个函数，这意味着下面的脚本不会执行：

//如果是通过 Ajax.Updater 处理，这种类型的脚本不能工作：
function coolFunc() {
	// Amazing stuff!
}

需要使用下面的语法（译注：请注意，coolFunc 前面没有 var）：

//如果通过 Ajax.Updater 处理，需要这种类型的脚本才会正常工作
coolFunc = function() {
	// Amazing stuff!
}

对于初学者而言，这是一个常见的陷井，因此，请注意！

上面所有的样例都假定无论请求成功还是失败，都将响应更新到同一个容器。有时，你可能希望只有在请求成功时才更新内容，或者在请求失败时更新到另一个容器。

为达到这个目的，需要为 container 参数传递一个 DOM 元素的替代对象，替代对象必须具有 success 属性，属性值为请求成功时需要更新的容器。如果你同时提供 failure 属性，则当请求失败时会更新该属性指定的容器。

下述代码中，仅在请求成功时才更新容器：

new Ajax.Updater({ success: 'items' }, '/items', {
	parameters: { text: $F('text') }, 
	insertion: Insertion.Bottom
});

下面的样例假设请求失败后在响应文本中会返回一条错误信息，并将错误信息更新到另一个元素（可能是一个状态区域）。

new Ajax.Updater({ success: 'items', failure: 'notice' },
	'/items',
	{ parameters: { text: $F('text') }, insertion: Insertion.Bottom }
);