1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
require File.dirname(__FILE__) + '/tag_helper'
module ActionView
module Helpers
# Provides a set of helpers for calling Javascript functions and, most importantly, to call remote methods using what has
# been labelled Ajax[http://www.adaptivepath.com/publications/essays/archives/000385.php]. This means that you can call
# actions in your controllers without reloading the page, but still update certain parts of it using injections into the
# DOM. The common use case is having a form that adds a new element to a list without reloading the page.
#
# To be able to use the Javascript helpers, you must either call <%= define_javascript_functions %> (which returns all
# the Javascript support functions in a <script> block) or reference the Javascript library using
# <%= javascript_include_tag "prototype" %> (which looks for the library in /javascripts/prototype.js). The latter is
# recommended as the browser can then cache the library instead of fetching all the functions anew on every request.
#
# If you're the visual type, there's an Ajax movie[http://www.rubyonrails.com/media/video/rails-ajax.mov] demonstrating
# the use of form_remote_tag.
module JavascriptHelper
unless const_defined? :CALLBACKS
CALLBACKS = [:uninitialized, :loading, :loaded, :interactive, :complete]
JAVASCRIPT_PATH = File.join(File.dirname(__FILE__), 'javascripts')
end
# Returns a link that'll trigger a javascript +function+ using the
# onclick handler and return false after the fact.
#
# Examples:
# link_to_function "Greeting", "alert('Hello world!')"
# link_to_function(image_tag("delete"), "if confirm('Really?'){ do_delete(); }")
def link_to_function(name, function, html_options = {})
content_tag(
"a", name,
html_options.symbolize_keys.merge(:href => "#", :onclick => "#{function}; return false;")
)
end
# Returns a link to a remote action defined by <tt>options[:url]</tt>
# (using the url_for format) that's called in the background using
# XMLHttpRequest. The result of that request can then be inserted into a
# DOM object whose id can be specified with <tt>options[:update]</tt>.
# Usually, the result would be a partial prepared by the controller with
# either render_partial or render_partial_collection.
#
# Examples:
# link_to_remote "Delete this post", :update => "posts", :url => { :action => "destroy", :id => post.id }
# link_to_remote(image_tag("refresh"), :update => "emails", :url => { :action => "list_emails" })
#
# By default, these remote requests are processed asynchronous during
# which various callbacks can be triggered (for progress indicators and
# the likes).
#
# Example:
# link_to_remote word,
# :url => { :action => "undo", :n => word_counter },
# :complete => "undoRequestCompleted(request)"
#
# The callbacks that may be specified are:
#
# <tt>:loading</tt>:: Called when the remote document is being
# loaded with data by the browser.
# <tt>:loaded</tt>:: Called when the browser has finished loading
# the remote document.
# <tt>:interactive</tt>:: Called when the user can interact with the
# remote document, even though it has not
# finished loading.
# <tt>:complete</tt>:: Called when the XMLHttpRequest is complete.
#
# If you for some reason or another need synchronous processing (that'll
# block the browser while the request is happening), you can specify
# <tt>options[:type] = :synchronous</tt>.
def link_to_remote(name, options = {}, html_options = {})
link_to_function(name, remote_function(options), html_options)
end
# Returns a form tag that will submit using XMLHttpRequest in the background instead of the regular
# reloading POST arrangement. Even though it's using Javascript to serialize the form elements, the form submission
# will work just like a regular submission as viewed by the receiving side (all elements available in @params).
# The options for specifying the target with :url and defining callbacks is the same as link_to_remote.
def form_remote_tag(options = {})
options[:form] = true
options[:html] ||= { }
options[:html][:onsubmit] = "#{remote_function(options)}; return false;"
tag("form", options[:html], true)
end
def remote_function(options) #:nodoc: for now
javascript_options = options_for_ajax(options)
function = options[:update] ?
"new Ajax.Updater('#{options[:update]}', " :
"new Ajax.Request("
function << "'#{url_for(options[:url])}'"
function << ", #{javascript_options})"
function = "#{options[:before]}; #{function}" if options[:before]
function = "#{function}; #{options[:after]}" if options[:after]
function = "if (#{options[:condition]}) { #{function}; }" if options[:condition]
return function
end
# Includes the Action Pack Javascript library inside a single <script>
# tag.
#
# Note: The recommended approach is to copy the contents of
# lib/action_view/helpers/javascripts/ into your application's
# public/javascripts/ directory, and use +javascript_include_tag+ to
# create remote <script> links.
def define_javascript_functions
javascript = '<script type="text/javascript">'
Dir.glob(File.join(JAVASCRIPT_PATH, '*')).each do |filename|
javascript << "\n" << IO.read(filename)
end
javascript << '</script>'
end
# Observes the field with the DOM ID specified by +field_id+ and makes
# an Ajax when its contents have changed.
#
# Required +options+ are:
# <tt>:frequency</tt>:: The frequency (in seconds) at which changes to
# this field will be detected.
# <tt>:url</tt>:: +url_for+-style options for the action to call
# when the field has changed.
#
# Additional options are:
# <tt>:update</tt>:: Specifies the DOM ID of the element whose
# innerHTML should be updated with the
# XMLHttpRequest response text.
# <tt>:with</tt>:: A Javascript expression specifying the
# parameters for the XMLHttpRequest. This defaults
# to 'value', which in the evaluated context
# refers to the new field value.
#
# Additionally, you may specify any of the options documented in
# +link_to_remote.
def observe_field(field_id, options = {})
build_observer('Form.Element.Observer', field_id, options)
end
# Like +observe_field+, but operates on an entire form identified by the
# DOM ID +form_id+. +options+ are the same as +observe_field+, except
# the default value of the <tt>:with</tt> option evaluates to the
# serialized (request string) value of the form.
def observe_form(form_id, options = {})
build_observer('Form.Observer', form_id, options)
end
private
def escape_javascript(javascript)
(javascript || '').gsub('"', '\"')
end
def options_for_ajax(options)
js_options = build_callbacks(options)
js_options['asynchronous'] = options[:type] != :synchronous
js_options['method'] = options[:method] if options[:method]
if options[:form]
js_options['parameters'] = 'Form.serialize(this)'
elsif options[:with]
js_options['parameters'] = options[:with]
end
'{' + js_options.map {|k, v| "#{k}:#{v}"}.join(', ') + '}'
end
def build_observer(klass, name, options = {})
options[:with] ||= 'value' if options[:update]
callback = remote_function(options)
javascript = '<script type="text/javascript">'
javascript << "new #{klass}('#{name}', "
javascript << "#{options[:frequency]}, function(element, value) {"
javascript << "#{callback}})</script>"
end
def build_callbacks(options)
CALLBACKS.inject({}) do |callbacks, callback|
if options[callback]
name = 'on' + callback.to_s.capitalize
code = escape_javascript(options[callback])
callbacks[name] = "function(request){#{code}}"
end
callbacks
end
end
end
end
end
|
