← Back to branch summary

~michaelforrest/use-case-mapper/trunk

« back to all changes in this revision

Viewing changes to vendor/rails/actionpack/lib/action_view/helpers/javascript_helper.rb

  • Committer: Michael Forrest
  • Date: 2010-10-15 16:28:50 UTC
  • Revision ID: michael.forrest@canonical.com-20101015162850-tj2vchanv0kr0dun
refroze gems

Show diffs side-by-side

added added

removed removed

Lines of Context:
vendor/rails/actionpack/lib/action_view/helpers/javascript_helper.rb
 
1
require 'action_view/helpers/tag_helper'
 
2
require 'action_view/helpers/prototype_helper'
 
3
 
 
4
module ActionView
 
5
  module Helpers
 
6
    # Provides functionality for working with JavaScript in your views.
 
7
    #
 
8
    # == Ajax, controls and visual effects
 
9
    #
 
10
    # * For information on using Ajax, see
 
11
    #   ActionView::Helpers::PrototypeHelper.
 
12
    # * For information on using controls and visual effects, see
 
13
    #   ActionView::Helpers::ScriptaculousHelper.
 
14
    #
 
15
    # == Including the JavaScript libraries into your pages
 
16
    #
 
17
    # Rails includes the Prototype JavaScript framework and the Scriptaculous
 
18
    # JavaScript controls and visual effects library.  If you wish to use
 
19
    # these libraries and their helpers (ActionView::Helpers::PrototypeHelper
 
20
    # and ActionView::Helpers::ScriptaculousHelper), you must do one of the
 
21
    # following:
 
22
    #
 
23
    # * Use <tt><%= javascript_include_tag :defaults %></tt> in the HEAD
 
24
    #   section of your page (recommended): This function will return
 
25
    #   references to the JavaScript files created by the +rails+ command in
 
26
    #   your <tt>public/javascripts</tt> directory. Using it is recommended as
 
27
    #   the browser can then cache the libraries instead of fetching all the
 
28
    #   functions anew on every request.
 
29
    # * Use <tt><%= javascript_include_tag 'prototype' %></tt>: As above, but
 
30
    #   will only include the Prototype core library, which means you are able
 
31
    #   to use all basic AJAX functionality. For the Scriptaculous-based
 
32
    #   JavaScript helpers, like visual effects, autocompletion, drag and drop
 
33
    #   and so on, you should use the method described above.
 
34
    #
 
35
    # For documentation on +javascript_include_tag+ see
 
36
    # ActionView::Helpers::AssetTagHelper.
 
37
    module JavaScriptHelper
 
38
      unless const_defined? :JAVASCRIPT_PATH
 
39
        JAVASCRIPT_PATH = File.join(File.dirname(__FILE__), 'javascripts')
 
40
      end
 
41
 
 
42
      include PrototypeHelper
 
43
 
 
44
      # Returns a link of the given +name+ that will trigger a JavaScript +function+ using the
 
45
      # onclick handler and return false after the fact.
 
46
      #
 
47
      # The first argument +name+ is used as the link text.
 
48
      #
 
49
      # The next arguments are optional and may include the javascript function definition and a hash of html_options.
 
50
      #
 
51
      # The +function+ argument can be omitted in favor of an +update_page+
 
52
      # block, which evaluates to a string when the template is rendered
 
53
      # (instead of making an Ajax request first).
 
54
      #
 
55
      # The +html_options+ will accept a hash of html attributes for the link tag. Some examples are :class => "nav_button", :id => "articles_nav_button"
 
56
      #
 
57
      # Note: if you choose to specify the javascript function in a block, but would like to pass html_options, set the +function+ parameter to nil
 
58
      #
 
59
      #
 
60
      # Examples:
 
61
      #   link_to_function "Greeting", "alert('Hello world!')"
 
62
      #     Produces:
 
63
      #       <a onclick="alert('Hello world!'); return false;" href="#">Greeting</a>
 
64
      #
 
65
      #   link_to_function(image_tag("delete"), "if (confirm('Really?')) do_delete()")
 
66
      #     Produces:
 
67
      #       <a onclick="if (confirm('Really?')) do_delete(); return false;" href="#">
 
68
      #         <img src="/images/delete.png?" alt="Delete"/>
 
69
      #       </a>
 
70
      #
 
71
      #   link_to_function("Show me more", nil, :id => "more_link") do |page|
 
72
      #     page[:details].visual_effect  :toggle_blind
 
73
      #     page[:more_link].replace_html "Show me less"
 
74
      #   end
 
75
      #     Produces:
 
76
      #       <a href="#" id="more_link" onclick="try {
 
77
      #         $(&quot;details&quot;).visualEffect(&quot;toggle_blind&quot;);
 
78
      #         $(&quot;more_link&quot;).update(&quot;Show me less&quot;);
 
79
      #       }
 
80
      #       catch (e) {
 
81
      #         alert('RJS error:\n\n' + e.toString());
 
82
      #         alert('$(\&quot;details\&quot;).visualEffect(\&quot;toggle_blind\&quot;);
 
83
      #         \n$(\&quot;more_link\&quot;).update(\&quot;Show me less\&quot;);');
 
84
      #         throw e
 
85
      #       };
 
86
      #       return false;">Show me more</a>
 
87
      #
 
88
      def link_to_function(name, *args, &block)
 
89
        html_options = args.extract_options!.symbolize_keys
 
90
 
 
91
        function = block_given? ? update_page(&block) : args[0] || ''
 
92
        onclick = "#{"#{html_options[:onclick]}; " if html_options[:onclick]}#{function}; return false;"
 
93
        href = html_options[:href] || '#'
 
94
 
 
95
        content_tag(:a, name, html_options.merge(:href => href, :onclick => onclick))
 
96
      end
 
97
 
 
98
      # Returns a button with the given +name+ text that'll trigger a JavaScript +function+ using the
 
99
      # onclick handler.
 
100
      #
 
101
      # The first argument +name+ is used as the button's value or display text.
 
102
      #
 
103
      # The next arguments are optional and may include the javascript function definition and a hash of html_options.
 
104
      #
 
105
      # The +function+ argument can be omitted in favor of an +update_page+
 
106
      # block, which evaluates to a string when the template is rendered
 
107
      # (instead of making an Ajax request first).
 
108
      #
 
109
      # The +html_options+ will accept a hash of html attributes for the link tag. Some examples are :class => "nav_button", :id => "articles_nav_button"
 
110
      #
 
111
      # Note: if you choose to specify the javascript function in a block, but would like to pass html_options, set the +function+ parameter to nil
 
112
      #
 
113
      # Examples:
 
114
      #   button_to_function "Greeting", "alert('Hello world!')"
 
115
      #   button_to_function "Delete", "if (confirm('Really?')) do_delete()"
 
116
      #   button_to_function "Details" do |page|
 
117
      #     page[:details].visual_effect :toggle_slide
 
118
      #   end
 
119
      #   button_to_function "Details", :class => "details_button" do |page|
 
120
      #     page[:details].visual_effect :toggle_slide
 
121
      #   end
 
122
      def button_to_function(name, *args, &block)
 
123
        html_options = args.extract_options!.symbolize_keys
 
124
 
 
125
        function = block_given? ? update_page(&block) : args[0] || ''
 
126
        onclick = "#{"#{html_options[:onclick]}; " if html_options[:onclick]}#{function};"
 
127
 
 
128
        tag(:input, html_options.merge(:type => 'button', :value => name, :onclick => onclick))
 
129
      end
 
130
 
 
131
      JS_ESCAPE_MAP = {
 
132
        '\\'    => '\\\\',
 
133
        '</'    => '<\/',
 
134
        "\r\n"  => '\n',
 
135
        "\n"    => '\n',
 
136
        "\r"    => '\n',
 
137
        '"'     => '\\"',
 
138
        "'"     => "\\'" }
 
139
 
 
140
      # Escape carrier returns and single and double quotes for JavaScript segments.
 
141
      def escape_javascript(javascript)
 
142
        if javascript
 
143
          javascript.gsub(/(\\|<\/|\r\n|[\n\r"'])/) { JS_ESCAPE_MAP[$1] }
 
144
        else
 
145
          ''
 
146
        end
 
147
      end
 
148
 
 
149
      # Returns a JavaScript tag with the +content+ inside. Example:
 
150
      #   javascript_tag "alert('All is good')"
 
151
      #
 
152
      # Returns:
 
153
      #   <script type="text/javascript">
 
154
      #   //<![CDATA[
 
155
      #   alert('All is good')
 
156
      #   //]]>
 
157
      #   </script>
 
158
      #
 
159
      # +html_options+ may be a hash of attributes for the <script> tag. Example:
 
160
      #   javascript_tag "alert('All is good')", :defer => 'defer'
 
161
      #   # => <script defer="defer" type="text/javascript">alert('All is good')</script>
 
162
      #
 
163
      # Instead of passing the content as an argument, you can also use a block
 
164
      # in which case, you pass your +html_options+ as the first parameter.
 
165
      #   <% javascript_tag :defer => 'defer' do -%>
 
166
      #     alert('All is good')
 
167
      #   <% end -%>
 
168
      def javascript_tag(content_or_options_with_block = nil, html_options = {}, &block)
 
169
        content =
 
170
          if block_given?
 
171
            html_options = content_or_options_with_block if content_or_options_with_block.is_a?(Hash)
 
172
            capture(&block)
 
173
          else
 
174
            content_or_options_with_block
 
175
          end
 
176
 
 
177
        tag = content_tag(:script, javascript_cdata_section(content), html_options.merge(:type => Mime::JS))
 
178
 
 
179
        if block_called_from_erb?(block)
 
180
          concat(tag)
 
181
        else
 
182
          tag
 
183
        end
 
184
      end
 
185
 
 
186
      def javascript_cdata_section(content) #:nodoc:
 
187
        "\n//#{cdata_section("\n#{content}\n//")}\n"
 
188
      end
 
189
 
 
190
    protected
 
191
      def options_for_javascript(options)
 
192
        if options.empty?
 
193
          '{}'
 
194
        else
 
195
          "{#{options.keys.map { |k| "#{k}:#{options[k]}" }.sort.join(', ')}}"
 
196
        end
 
197
      end
 
198
 
 
199
      def array_or_string_for_javascript(option)
 
200
        if option.kind_of?(Array)
 
201
          "['#{option.join('\',\'')}']"
 
202
        elsif !option.nil?
 
203
          "'#{option}'"
 
204
        end
 
205
      end
 
206
    end
 
207
  end
 
208
end