Rails Ajax

2、form_remote_tag(options = {})

我们经常需要用Ajax技术来获取用户与表单间交互的结果，接着会把它post到服务器上，再将返回的结果呈现在页面。设想一个在blog上发表评论的场景，输入你的Email以及评论内容，然后点击提交，这时你评论就神奇般地添加到最后。要实现这种效果，必须通过一些JavaScript将表单上的元素序列化成一个能够通过XMLHttpRequest传递的参数。

要在Rails中创建一个支持Ajax的表单，得使用form_remote_tag()来替换form_tag()调用。用它创建表单，将会把onsubmit事件改成调用一个自定义的JavaScript函数。该函数将使用Prototype的Ajax.Request(或Ajax.Updater)来实现向服务器发送表单字段。除了初始化的文本参数之外，其它参数都与link_to_remote一样，同样可以包括表单中不可见元素。

例如：

<%= form_remote_tag :url => {:controller => ‘my_controller’,

:action => ‘my_action’} , :update => ‘my_element’ %>

这个Helper方法还将自动使用Prototype中的Form.serialize方法，它用来将表单上的所有输入框元素的值收集到某个字符格式的哈希表中，该哈希表将做为参数值传给该请求。

3、observe_field(field_id, options = {}) 字段观察者。监听由field_id指定的DOM ID字段，并且在字段内容被修改时生成一个Ajax调用。

也就是说，它可以监控某个字段的变化(采用周期性监控或使用基于事件触发的方式)，并将该变化发送到服务器端。周期性轮询是指每隔n秒钟就对目标字段取值一次，然后将值发送到服务器(不管在这个间隔时间内该值是否发生变化)。而基于事件的轮询则是使用onblur事件，即仅当用户使焦点离开目标字段时才发送变化值。照此说，周期性轮询对于类似字段自动填充的应用而言是十分有用的，它将根据字段的内容显示出一个可选列表。而基于事件的轮询则对于希望用户在字段中输入完整值后触发一个往返于服务端和客户端之间的交互的应用很有效。

下面两个选项必须被指定一个：

1）:url 当字段被更改时调用的动作，它使用url_for格式。

2）:function 你可以指定一个被调用的JS函数来代替前面的:url选项。

额外的选项是：

1）:frequency 侦测可被更改字段的频率(以秒为单位)。如果没有设置值或设置的 值小于等于零，则使用基于事件的观察来代替基于时间的观察。

2）:update 指定需要用XMLHttpReuqest响应的文本来更新的DOM ID 的元素的innerHTML。

3）:with 为XMLHttpRequest指定参数的一个JavaScript表达式。

4）:on 指定哪个事件处理程序被监听。缺省地，用于有"changed"事件处理程序的text字段，文本区域和有"click" 事件处理程序的单选按钮及检查框。你可以用它来替 换"blur"或"focus"或任何其它事件。

另外，你也可以指定link_to_remote内的任何选项。

例如：

<%= text_field ‘my_object’, ‘my_property’ %>

<%= observe_field ‘my_object_my_property’,

:url => { :controller => ‘my_controller’, :action => ‘my_action’},

:update => ‘display_target’,

:frequency => 0.5,

:with => “’my_param = ‘ + value” %>

默认情况下，observer把字段值作为原始的post数据发送给服务器。可在控制器内使用reuqest.raw_post或request.query_string来访问这个数据。不过，经常会需要把这些值标记为特定的已命名参数。Rails针对这些observer对象提供了一个可选的参数 :with。你可以通过一小段JavaScript代码来为请求生成参数列表。

4、observe_form(form_id, options = {}) 如果页面要监控的是整个表单，而非单一的字段，就要使用这个方法。使用时需将指定表单id而非字段id，这样就可监控表单中所有输入框。和字段观察者一样，表单观察者也分为周期性的和基于事件的两种。它将使用Prototype提供的Form.serialize方法来获取表单的所有值，也可像字段观察者一样通过可选的:with参数来构造请求的参数。

5、periodically_call_remote(options = {}) 每隔options[:frequency]秒数(缺省值是10秒)就调用指定的url(options[:url)一次。通常，用于用远程调用的结果更新指定的div(options[:update])。:url和定义的回调函数与link_to_remote一样。

6、evaluate_remote_response() 返回 ‘eval(request.responseText)’ ，它是个能在form_remote_tag的:complete内调用的JavaScript函数，以计算使用update_element_function调用返回文档的多个更新。

7、remote_function(options) 为一个远程函数返回需要的JavaScript。接受与link_to_remote一样的参数。

例如：

<select id="options" onchange="<%= remote_function(:update => "options",

:url => { :action => :update_options }) %>">

<option value="0">Hello</option>

<option value="1">World</option>

</select>

8、submit_to_remote(name, value, options = {}) 返回一个按钮input标记，它在后台使用XMLHttpRequest提供表单而不是通常的POST。Options参数与form_remote_tag是一样的。

9、update_element_function(element_id, options = {}, &block) 返回一个JavaScript函数(或表达式)，它根据options选项来更新一个DOM元素。

1）:content 用于更新的内容。

2）:action 有效的选项是 :update (缺省值)，:empty， :remove

3）:position 如果 :action 是 :update，那么你可以选择这些位置中的一个： :before, :top, :bottom, :after.

例如：

<%= javascript_tag(update_element_function("products",

:position => :bottom, :content => "<p>New product!</p>")) %>

<% replacement_function = update_element_function("products") do %>

<p>Product 1</p>

<p>Product 2</p>

<% end %>

<%= javascript_tag(replacement_function) %>

This method can also be used in combination with remote method call where the result is evaluated afterwards to cause multiple updates on a page. Example:

# Calling view

<%= form_remote_tag :url => { :action => "buy" },

:complete => evaluate_remote_response %>

all the inputs here...

# Controller action

def buy

@product = Product.find(1)

end

# Returning view

<%= update_element_function(

"cart", :action => :update, :position => :bottom,

:content => "<p>New Product: #{@product.name}</p>")) %>

<% update_element_function("status", :binding => binding) do %>

You've bought a new product!

<% end %>

Notice how the second call doesn’t need to be in an ERb output block since it uses a block and passes in the binding to render directly. This trick will however only work in ERb (not Builder or other template forms).

See also JavaScriptGenerator and update_page.

10、update_page(&block) 调用一个JavaScriptGenerator并返回被生成的JavaScript代码。使用它来在一个Ajax应答内更新页面内的多个元素。查看JavaScriptGenerator 。

11、update_page_tag(&block) 与update_page工作类似，但在<script>标记内包装被生成的JavaScript代码。使用它以在一个ERB模板内包含被生成的JavaScript代码。查看JavaScriptGenerator 。

三、JavaScriptMacrosHelper

四、ScriptaculousHelper

1、draggable_element(element_id, options = {}) Makes the element with the DOM ID specified by element_id draggable.

Example:

<%= draggable_element("my_image", :revert => true)

You can change the behaviour with various options, see script.aculo.us for more documentation.

2、drop_receiving_element(element_id, options = {}) Makes the element with the DOM ID specified by element_id receive dropped draggable elements (created by draggable_element). and make an AJAX call By default, the action called gets the DOM ID of the element as parameter.

Example:

<%= drop_receiving_element("my_cart", :url =>

{ :controller => "cart", :action => "add" }) %>

You can change the behaviour with various options, see script.aculo.us for more documentation.

3、sortable_element(element_id, options = {}) Makes the element with the DOM ID specified by element_id sortable by drag-and-drop and make an Ajax call whenever the sort order has changed. By default, the action called gets the serialized sortable element as parameters.

Example:

<%= sortable_element("my_list", :url => { :action => "order" }) %>

In the example, the action gets a "my_list" array parameter containing the values of the ids of elements the sortable consists of, in the current order.

You can change the behaviour with various options, see script.aculo.us for more documentation.

4、visual_effect(name, element_id = false, js_options = {}) Returns a JavaScript snippet to be used on the Ajax callbacks for starting visual effects.

Example:

<%= link_to_remote "Reload", :update => "posts",

:url => { :action => "reload" },

:complete => visual_effect(:highlight, "posts", :duration => 0.5)

If no element_id is given, it assumes "element" which should be a local variable in the generated JavaScript execution context. This can be used for example with drop_receiving_element:

<%= drop_receving_element (...), :loading => visual_effect(:fade) %>

This would fade the element that was dropped on the drop receiving element.

For toggling visual effects, you can use :toggle_appear, :toggle_slide, and :toggle_blind which will alternate between appear/fade, slidedown/slideup, and blinddown/blindup respectively.

You can change the behaviour with various options, see script.aculo.us for more documentation.

五、GeneratorMethods

Page对象只是JavaScriptGenerator类的一个实例，是Prototype集成代码的一部分。其目的是为Ajax页面所需的，不同标准的JavaScript程序块提供一个单一提供者。通过RJS模板，将成为与当前页面中DOM元素交互的媒介。Page对象提供了两类方法：一类只需要客户端的JavaScript，另一部分则是需要Prototype程序库的支持。

JavaScriptGenerator 生成的代码块允许你修改多个DOM元素的内容与表现。可在你的AJAX块内，<script>标记或是带有”text/javascript”的Content-type内的JavaScript内。

可以使用PrototypeHelper#update_page或ActionController::Base#render创建个新实例，然后调用insert_html，replace_html，remove，show，hide，visual_effect，或其它任何生成器中内建的方法，以便你可以修改当前页的内容和外观。

例如：

update_page do |page|

page.insert_html :bottom, 'list', "<li>#{@item.name}</li>"

page.visual_effect :highlight, 'list'

page.hide 'status-indicator', 'cancel-link'

end

生成下面JavaScript代码：

new Insertion.Bottom("list", "<li>Some item</li>");

new Effect.Highlight("list");

["status-indicator", "cancel-link"].each(Element.hide);

Helper方法可以与JavaScriptGenerator关联。当一个helper方法在page对象上的一个内部更新块被调用时，方法也可以访问page对象。

例如：

module ApplicationHelper

def update_time

page.replace_html 'time', Time.now.to_s(:db)

page.visual_effect :highlight, 'time'

end

end

# Controller action

def poll

render :update { |page| page.update_time }

end

你也可以使用PrototypeHelper#update_page_tag代替PrototypeHelper#update_page来包装在<script>标记内生成的JavaScript代码。