actionpack 1.9.1 → 1.10.1

data/lib/action_view/helpers/java_script_macros_helper.rb

@@ -0,0 +1,188 @@
+require File.dirname(__FILE__) + '/tag_helper'
+
+module ActionView
+  module Helpers
+    # Provides a set of helpers for creating JavaScript macros that rely on and often bundle methods from JavaScriptHelper into
+    # larger units. These macros also rely on counterparts in the controller that provide them with their backing. The in-place
+    # editing relies on ActionController::Base.in_place_edit_for and the autocompletion relies on 
+    # ActionController::Base.auto_complete_for.
+    module JavaScriptMacrosHelper
+      # Makes an HTML element specified by the DOM ID +field_id+ become an in-place
+      # editor of a property.
+      #
+      # A form is automatically created and displayed when the user clicks the element,
+      # something like this:
+      # <form id="myElement-in-place-edit-form" target="specified url">
+      #   <input name="value" text="The content of myElement"/>
+      #   <input type="submit" value="ok"/>
+      #   <a onclick="javascript to cancel the editing">cancel</a>
+      # </form>
+      # 
+      # The form is serialized and sent to the server using an AJAX call, the action on
+      # the server should process the value and return the updated value in the body of
+      # the reponse. The element will automatically be updated with the changed value
+      # (as returned from the server).
+      # 
+      # Required +options+ are:
+      # <tt>:url</tt>::       Specifies the url where the updated value should
+      #                       be sent after the user presses "ok".
+      # 
+      # Addtional +options+ are:
+      # <tt>:rows</tt>::        Number of rows (more than 1 will use a TEXTAREA)
+      # <tt>:cancel_text</tt>:: The text on the cancel link. (default: "cancel")
+      # <tt>:ok_text</tt>::     The text on the save link. (default: "ok")
+      # <tt>:options</tt>::     Pass through options to the AJAX call (see prototype's Ajax.Updater)
+      # <tt>:with</tt>::        JavaScript snippet that should return what is to be sent
+      #                         in the AJAX call, +form+ is an implicit parameter
+      def in_place_editor(field_id, options = {})
+        function =  "new Ajax.InPlaceEditor("
+        function << "'#{field_id}', "
+        function << "'#{url_for(options[:url])}'"
+
+        js_options = {}
+        js_options['cancelText'] = options[:cancel_text] if options[:cancel_text]
+        js_options['okText'] = options[:save_text] if options[:save_text]
+        js_options['rows'] = options[:rows] if options[:rows]
+        js_options['ajaxOptions'] = options[:options] if options[:options]
+        js_options['callback']   = "function(form) { return #{options[:with]} }" if options[:with]
+        function << (', ' + options_for_javascript(js_options)) unless js_options.empty?
+        
+        function << ')'
+
+        javascript_tag(function)
+      end
+      
+      # Renders the value of the specified object and method with in-place editing capabilities.
+      #
+      # See the RDoc on ActionController::InPlaceEditing to learn more about this.
+      def in_place_editor_field(object, method, tag_options = {}, in_place_editor_options = {})
+        tag = ::ActionView::Helpers::InstanceTag.new(object, method, self)
+        tag_options = {:tag => "span", :id => "#{object}_#{method}_#{tag.object.id}_in_place_editor", :class => "in_place_editor_field"}.merge!(tag_options)
+        in_place_editor_options[:url] = in_place_editor_options[:url] || url_for({ :action => "set_#{object}_#{method}", :id => tag.object.id })
+        tag.to_content_tag(tag_options[:tag], tag_options) +
+        in_place_editor(tag_options[:id], in_place_editor_options)
+      end
+      
+      # Adds AJAX autocomplete functionality to the text input field with the 
+      # DOM ID specified by +field_id+.
+      #
+      # This function expects that the called action returns a HTML <ul> list,
+      # or nothing if no entries should be displayed for autocompletion.
+      #
+      # You'll probably want to turn the browser's built-in autocompletion off,
+      # su be sure to include a autocomplete="off" attribute with your text
+      # input field.
+      # 
+      # Required +options+ are:
+      # <tt>:url</tt>::       URL to call for autocompletion results
+      #                       in url_for format.
+      # 
+      # Addtional +options+ are:
+      # <tt>:update</tt>::    Specifies the DOM ID of the element whose 
+      #                       innerHTML should be updated with the autocomplete
+      #                       entries returned by the AJAX request. 
+      #                       Defaults to field_id + '_auto_complete'
+      # <tt>:with</tt>::      A JavaScript expression specifying the
+      #                       parameters for the XMLHttpRequest. This defaults
+      #                       to 'fieldname=value'.
+      # <tt>:indicator</tt>:: Specifies the DOM ID of an element which will be
+      #                       displayed while autocomplete is running.
+      # <tt>:tokens</tt>::    A string or an array of strings containing
+      #                       separator tokens for tokenized incremental 
+      #                       autocompletion. Example: <tt>:tokens => ','</tt> would
+      #                       allow multiple autocompletion entries, separated
+      #                       by commas.
+      # <tt>:min_chars</tt>:: The minimum number of characters that should be
+      #                       in the input field before an Ajax call is made
+      #                       to the server.
+      # <tt>:on_hide</tt>::   A Javascript expression that is called when the
+      #                       autocompletion div is hidden. The expression
+      #                       should take two variables: element and update.
+      #                       Element is a DOM element for the field, update
+      #                       is a DOM element for the div from which the
+      #                       innerHTML is replaced.
+      # <tt>:on_show</tt>::   Like on_hide, only now the expression is called
+      #                       then the div is shown.
+      def auto_complete_field(field_id, options = {})
+        function =  "new Ajax.Autocompleter("
+        function << "'#{field_id}', "
+        function << "'" + (options[:update] || "#{field_id}_auto_complete") + "', "
+        function << "'#{url_for(options[:url])}'"
+        
+        js_options = {}
+        js_options[:tokens] = array_or_string_for_javascript(options[:tokens]) if options[:tokens]
+        js_options[:callback]   = "function(element, value) { return #{options[:with]} }" if options[:with]
+        js_options[:indicator]  = "'#{options[:indicator]}'" if options[:indicator]
+        {:on_show => :onShow, :on_hide => :onHide, :min_chars => :min_chars}.each do |k,v|
+          js_options[v] = options[k] if options[k]
+        end
+        function << (', ' + options_for_javascript(js_options) + ')')
+
+        javascript_tag(function)
+      end
+      
+      # Use this method in your view to generate a return for the AJAX autocomplete requests.
+      #
+      # Example action:
+      #
+      #   def auto_complete_for_item_title
+      #     @items = Item.find(:all, 
+      #       :conditions => [ 'LOWER(description) LIKE ?', 
+      #       '%' + request.raw_post.downcase + '%' ])
+      #     render :inline => '<%= auto_complete_result(@items, 'description') %>'
+      #   end
+      #
+      # The auto_complete_result can of course also be called from a view belonging to the 
+      # auto_complete action if you need to decorate it further.
+      def auto_complete_result(entries, field, phrase = nil)
+        return unless entries
+        items = entries.map { |entry| content_tag("li", phrase ? highlight(entry[field], phrase) : h(entry[field])) }
+        content_tag("ul", items.uniq)
+      end
+      
+      # Wrapper for text_field with added AJAX autocompletion functionality.
+      #
+      # In your controller, you'll need to define an action called
+      # auto_complete_for_object_method to respond the AJAX calls,
+      # 
+      # See the RDoc on ActionController::AutoComplete to learn more about this.
+      def text_field_with_auto_complete(object, method, tag_options = {}, completion_options = {})
+        (completion_options[:skip_style] ? "" : auto_complete_stylesheet) +
+        text_field(object, method, tag_options) +
+        content_tag("div", "", :id => "#{object}_#{method}_auto_complete", :class => "auto_complete") +
+        auto_complete_field("#{object}_#{method}", { :url => { :action => "auto_complete_for_#{object}_#{method}" } }.update(completion_options))
+      end
+      
+      private
+        def auto_complete_stylesheet
+          content_tag("style", <<-EOT
+            div.auto_complete {
+              width: 350px;
+              background: #fff;
+            }
+            div.auto_complete ul {
+              border:1px solid #888;
+              margin:0;
+              padding:0;
+              width:100%;
+              list-style-type:none;
+            }
+            div.auto_complete ul li {
+              margin:0;
+              padding:3px;
+            }
+            div.auto_complete ul li.selected { 
+              background-color: #ffb; 
+            }
+            div.auto_complete ul strong.highlight { 
+              color: #800; 
+              margin:0;
+              padding:0;
+            }
+          EOT
+          )
+        end
+      
+    end
+  end
+end

data/lib/action_view/helpers/javascript_helper.rb

@@ -7,17 +7,27 @@ module ActionView
     # 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 <tt><%= define_javascript_functions %></tt> (which returns all
-    # the JavaScript support functions in a <script> block) or reference the JavaScript library using 
-    # <tt><%= javascript_include_tag "prototype" %></tt> (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.
+    # To be able to use the JavaScript helpers, you must include the Prototype JavaScript Framework and for some functions
+    # script.aculo.us (which both come with Rails) on your pages. Choose one of these options:
+    #
+    # * Use <tt><%= javascript_include_tag :defaults %></tt> in the HEAD section of your page (recommended):
+    #   The function will return references to the JavaScript files created by the +rails+ command in your
+    #   <tt>public/javascripts</tt> directory. Using it is recommended as the browser can then cache the libraries
+    #   instead of fetching all the functions anew on every request.
+    # * Use <tt><%= javascript_include_tag 'prototype' %></tt>: As above, but will only include the Prototype core library,
+    #   which means you are able to use all basic AJAX functionality. For the script.aculo.us-based JavaScript helpers,
+    #   like visual effects, autocompletion, drag and drop and so on, you should use the method described above.
+    # * Use <tt><%= define_javascript_functions %></tt>: this will copy all the JavaScript support functions within a single
+    #   script block.
+    #
+    # For documentation on +javascript_include_tag+ see ActionView::Helpers::AssetTagHelper.
     #
     # 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, :failure].push((100..599).to_a).flatten
+          [:uninitialized, :loading, :loaded, :interactive, :complete, :failure, :success].push((100..599).to_a).flatten
         AJAX_OPTIONS    = [ :before, :after, :condition, :url, :asynchronous, :method, 
           :insertion, :position, :form, :with, :update, :script ].concat(CALLBACKS)
         JAVASCRIPT_PATH = File.join(File.dirname(__FILE__), 'javascripts')
@@ -116,6 +126,11 @@ module ActionView
       # <tt>:before</tt>::       Called before request is initiated.
       # <tt>:after</tt>::        Called immediately after request was
       #                          initiated and before <tt>:loading</tt>.
+      # <tt>:submit</tt>::       Specifies the DOM element ID that's used
+      #                          as the parent of the form elements. By 
+      #                          default this is the current form, but
+      #                          it could just as well be the ID of a
+      #                          table row or any other DOM element.
       def link_to_remote(name, options = {}, html_options = {})  
         link_to_function(name, remote_function(options), html_options)
       end
@@ -126,7 +141,7 @@ module ActionView
       def periodically_call_remote(options = {})
          frequency = options[:frequency] || 10 # every ten seconds by default
          code = "new PeriodicalExecuter(function() {#{remote_function(options)}}, #{frequency})"
-         content_tag("script", code, options[:html_options] || {})
+         javascript_tag(code)
       end
 
       # Returns a form tag that will submit using XMLHttpRequest in the background instead of the regular 
@@ -137,6 +152,7 @@ module ActionView
       # A "fall-through" target for browsers that doesn't do JavaScript can be specified with the :action/:method options on :html
       #
       #   form_remote_tag :html => { :action => url_for(:controller => "some", :action => "place") }
+      # The Hash passed to the :html key is equivalent to the options (2nd) argument in the FormTagHelper.form_tag method.
       #
       # By default the fall-through action is the same as the one specified in the :url (and the default method is :post).
       def form_remote_tag(options = {})
@@ -153,7 +169,7 @@ module ActionView
       # Returns a button input tag that will submit form using XMLHttpRequest in the background instead of regular
       # reloading POST arrangement. <tt>options</tt> argument is the same as in <tt>form_remote_tag</tt>
       def submit_to_remote(name, value, options = {})
-        options[:with] = 'Form.serialize(this.form)'
+        options[:with] ||= 'Form.serialize(this.form)'
 
         options[:html] ||= {}
         options[:html][:type] = 'button'
@@ -235,7 +251,15 @@ module ActionView
         "eval(request.responseText)"
       end
 
-      def remote_function(options) #:nodoc: for now
+      # Returns the javascript needed for a remote function.
+      # Takes the same arguments as link_to_remote.
+      # 
+      # Example:
+      #   <select id="options" onchange="<%= remote_function(:update => "options", :url => { :action => :update_options }) %>">
+      #     <option value="0">Hello</option>
+      #     <option value="1">World</option>
+      #   </select>
+      def remote_function(options)
         javascript_options = options_for_ajax(options)
 
         update = ''
@@ -297,9 +321,10 @@ module ActionView
       # 
       # Additional options are:
       # <tt>:frequency</tt>:: The frequency (in seconds) at which changes to
-      #                       this field will be detected. Set this to a value
-      #                       greater than zero to use time based observation
-      #                       instead of event based observation.
+      #                       this field will be detected. Not setting this
+      #                       option at all or to a value equal to or less than
+      #                       zero will use event based observation instead of
+      #                       time based observation.
       # <tt>:update</tt>::    Specifies the DOM ID of the element whose 
       #                       innerHTML should be updated with the
       #                       XMLHttpRequest response text.
@@ -309,9 +334,9 @@ module ActionView
       #                       refers to the new field value.
       #
       # Additionally, you may specify any of the options documented in
-      # +link_to_remote.
+      # link_to_remote.
       def observe_field(field_id, options = {})
-        if options[:frequency]
+        if options[:frequency] and options[:frequency] > 0
           build_observer('Form.Element.Observer', field_id, options)
         else
           build_observer('Form.Element.EventObserver', field_id, options)
@@ -330,86 +355,11 @@ module ActionView
         end
       end
       
-           
-      # Adds AJAX autocomplete functionality to the text input field with the 
-      # DOM ID specified by +field_id+.
-      #
-      # This function expects that the called action returns a HTML <ul> list,
-      # or nothing if no entries should be displayed for autocompletion.
-      #
-      # You'll probably want to turn the browser's built-in autocompletion off,
-      # su be sure to include a autocomplete="off" attribute with your text
-      # input field.
-      # 
-      # Required +options+ are:
-      # <tt>:url</tt>::       Specifies the DOM ID of the element whose
-      #                       innerHTML should be updated with the autocomplete
-      #                       entries returned by XMLHttpRequest.
-      # 
-      # Addtional +options+ are:
-      # <tt>:update</tt>::    Specifies the DOM ID of the element whose 
-      #                       innerHTML should be updated with the autocomplete
-      #                       entries returned by the AJAX request. 
-      #                       Defaults to field_id + '_auto_complete'
-      # <tt>:with</tt>::      A JavaScript expression specifying the
-      #                       parameters for the XMLHttpRequest. This defaults
-      #                       to 'fieldname=value'.
-      # <tt>:indicator</tt>:: Specifies the DOM ID of an elment which will be
-      #                       displayed while autocomplete is running. 
-      def auto_complete_field(field_id, options = {})
-        function =  "new Ajax.Autocompleter("
-        function << "'#{field_id}', "
-        function << "'" + (options[:update] || "#{field_id}_auto_complete") + "', "
-        function << "'#{url_for(options[:url])}'"
-        
-        js_options = {}
-        if options[:tokens] and options[:tokens].kind_of?(Array)
-          js_options[:tokens] = "['#{options[:tokens].join('\',\'')}']"
-        elsif options[:tokens]
-          js_options[:tokens] = "'#{options[:tokens]}'" if options[:tokens]
-        end
-        js_options[:callback]   = "function(element, value) { return #{options[:with]} }" if options[:with]
-        js_options[:indicator]  = "'#{options[:indicator]}'" if options[:indicator]
-        function << (', ' + options_for_javascript(js_options) + ')')
-
-        javascript_tag(function)
-      end
-      
-      # Use this method in your view to generate a return for the AJAX automplete requests.
-      #
-      # Example action:
-      #
-      #   def auto_complete_for_item_title
-      #     @items = Item.find(:all, 
-      #       :conditions => [ 'LOWER(description) LIKE ?', 
-      #       '%' + request.raw_post.downcase + '%' ])
-      #     render :inline => '<%= auto_complete_result(@items, 'description') %>'
-      #   end
-      #
-      # The auto_complete_result can of course also be called from a view belonging to the 
-      # auto_complete action if you need to decorate it further.
-      def auto_complete_result(entries, field, phrase = nil)
-        return unless entries
-        items = entries.map { |entry| content_tag("li", phrase ? highlight(entry[field], phrase) : h(entry[field])) }
-        content_tag("ul", items)
-      end
-      
-      # Wrapper for text_field with added AJAX autocompletion functionality.
-      #
-      # In your controller, you'll need to define an action called
-      # auto_complete_for_object_method to respond the AJAX calls,
-      # 
-      # See the RDoc on ActionController::AutoComplete to learn more about this.
-      def text_field_with_auto_complete(object, method, tag_options = {}, completion_options = {})
-        (completion_options[:skip_style] ? "" : auto_complete_stylesheet) +
-        text_field(object, method, { :autocomplete => "off" }.merge!(tag_options)) +
-        content_tag("div", "", :id => "#{object}_#{method}_auto_complete", :class => "auto_complete") +
-        auto_complete_field("#{object}_#{method}", { :url => { :action => "auto_complete_for_#{object}_#{method}" } }.update(completion_options))
-      end
-      
       # Returns a JavaScript snippet to be used on the AJAX callbacks for starting
       # visual effects.
       #
+      # This method requires the inclusion of the script.aculo.us JavaScript library.
+      #
       # Example:
       #   <%= link_to_remote "Reload", :update => "posts", 
       #         :url => { :action => "reload" }, 
@@ -435,6 +385,8 @@ module ActionView
       # changed. By default, the action called gets the serialized sortable
       # element as parameters.
       #
+      # This method requires the inclusion of the script.aculo.us JavaScript library.
+      #
       # Example:
       #   <%= sortable_element("my_list", :url => { :action => "order" }) %>
       #
@@ -453,17 +405,16 @@ module ActionView
           options[option] = "'#{options[option]}'" if options[option]
         end
         
-        if options[:containment] and options[:containment].kind_of?(Array)
-          options[:containment] = "['#{options[:containment].join('\',\'')}']"
-        elsif options[:containment]
-          options[:containment] = "'#{options[:containment]}'" if options[:containment]
-        end
+        options[:containment] = array_or_string_for_javascript(options[:containment]) if options[:containment]
+        options[:only] = array_or_string_for_javascript(options[:only]) if options[:only]
         
         javascript_tag("Sortable.create('#{element_id}', #{options_for_javascript(options)})")
       end
       
       # Makes the element with the DOM ID specified by +element_id+ draggable.
       #
+      # This method requires the inclusion of the script.aculo.us JavaScript library.
+      #
       # Example:
       #   <%= draggable_element("my_image", :revert => true)
       # 
@@ -478,6 +429,8 @@ module ActionView
       # and make an AJAX call  By default, the action called gets the DOM ID of the
       # element as parameter.
       #
+      # This method requires the inclusion of the script.aculo.us JavaScript library.
+      #
       # Example:
       #   <%= drop_receiving_element("my_cart", :url => { :controller => "cart", :action => "add" }) %>
       #
@@ -488,12 +441,7 @@ module ActionView
         options[:onDrop]   ||= "function(element){" + remote_function(options) + "}"
         options.delete_if { |key, value| AJAX_OPTIONS.include?(key) }
         
-        if options[:accept] and options[:accept].kind_of?(Array)
-          options[:accept] = "['#{options[:accept].join('\',\'')}']"
-        elsif options[:accept]
-          options[:accept] = "'#{options[:accept]}'" if options[:accept]
-        end
-        
+        options[:accept] = array_or_string_for_javascript(options[:accept]) if options[:accept]    
         options[:hoverclass] = "'#{options[:hoverclass]}'" if options[:hoverclass]
         
         javascript_tag("Droppables.add('#{element_id}', #{options_for_javascript(options)})")
@@ -507,14 +455,27 @@ module ActionView
       # Returns a JavaScript tag with the +content+ inside. Example:
       #   javascript_tag "alert('All is good')" # => <script type="text/javascript">alert('All is good')</script>
       def javascript_tag(content)
-        content_tag("script", content, :type => "text/javascript")
+        content_tag("script", javascript_cdata_section(content), :type => "text/javascript")
       end
 
+      def javascript_cdata_section(content) #:nodoc:
+        "\n//#{cdata_section("\n#{content}\n//")}\n"
+      end
+      
     private
       def options_for_javascript(options)
         '{' + options.map {|k, v| "#{k}:#{v}"}.sort.join(', ') + '}'
       end
       
+      def array_or_string_for_javascript(option)
+        js_option = if option.kind_of?(Array)
+          "['#{option.join('\',\'')}']"
+        elsif !option.nil?
+          "'#{option}'"
+        end
+        js_option
+      end
+      
       def options_for_ajax(options)
         js_options = build_callbacks(options)
         
@@ -525,6 +486,8 @@ module ActionView
 
         if options[:form]
           js_options['parameters'] = 'Form.serialize(this)'
+        elsif options[:submit]
+          js_options['parameters'] = "Form.serialize(document.getElementById('#{options[:submit]}'))"
         elsif options[:with]
           js_options['parameters'] = options[:with]
         end
@@ -539,11 +502,11 @@ module ActionView
       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  = "new #{klass}('#{name}', "
         javascript << "#{options[:frequency]}, " if options[:frequency]
         javascript << "function(element, value) {"
-        javascript << "#{callback}})</script>"
+        javascript << "#{callback}})"
+        javascript_tag(javascript)
       end
             
       def build_callbacks(options)
@@ -557,34 +520,6 @@ module ActionView
         callbacks
       end
       
-      def auto_complete_stylesheet
-        content_tag("style", <<-EOT
-          div.auto_complete {
-            width: 350px;
-            background: #fff;
-          }
-          div.auto_complete ul {
-            border:1px solid #888;
-            margin:0;
-            padding:0;
-            width:100%;
-            list-style-type:none;
-          }
-          div.auto_complete ul li {
-            margin:0;
-            padding:3px;
-          }
-          div.auto_complete ul li.selected { 
-            background-color: #ffb; 
-          }
-          div.auto_complete ul strong.highlight { 
-            color: #800; 
-            margin:0;
-            padding:0;
-          }
-        EOT
-        )
-      end
     end
     
     JavascriptHelper = JavaScriptHelper unless const_defined? :JavascriptHelper