bivouac 0.0.6 → 0.0.7

data/lib/bivouac/helpers/view/goh/javascript.rb

@@ -0,0 +1,532 @@
+# bivouac/helpers/view/javascript
+require 'active_support'
+
+class JavaScriptGenerator
+  def initialize( context, &block ) #:nodoc:
+    @context = context
+    @source = ""
+    yield( self )
+  end
+  
+  def to_s #:nodoc:
+    javascript = "try {\n#{@source}\n} catch (e) "
+    javascript << "{ alert('RJS error:\\n\\n' + e.toString()); alert('#{@source.gsub('\\','\0\0').gsub(/\r\n|\n|\r/, "\\n").gsub(/["']/) { |m| "\\#{m}" }}'); throw e }"
+    
+    return javascript
+  end
+  
+  # Returns a element reference by finding it through +id+ in the DOM. This element can then be
+  # used for further method calls. Examples:
+  #
+  #   page['blank_slate']                  # => $('blank_slate');
+  #   page['blank_slate'].show             # => $('blank_slate').show();
+  #   page['blank_slate'].show('first').up # => $('blank_slate').show('first').up();
+  def []( id )
+    # JavaScriptElementProxy.new(self, id)
+  end
+  
+  # Returns a collection reference by finding it through a CSS +pattern+ in the DOM. This collection can then be
+  # used for further method calls. Examples:
+  #
+  #   page.select('p')                      # => $$('p');
+  #   page.select('p.welcome b').first      # => $$('p.welcome b').first();
+  #   page.select('p.welcome b').first.hide # => $$('p.welcome b').first().hide();
+  # 
+  # You can also use prototype enumerations with the collection.  Observe:
+  # 
+  #   page.select('#items li').each do |value|
+  #     value.hide
+  #   end 
+  #   # => $$('#items li').each(function(value) { value.hide(); });
+  #
+  # Though you can call the block param anything you want, they are always rendered in the 
+  # javascript as 'value, index.'  Other enumerations, like collect() return the last statement:
+  # 
+  #   page.select('#items li').collect('hidden') do |item|
+  #     item.hide
+  #   end
+  #   # => var hidden = $$('#items li').collect(function(value, index) { return value.hide(); });
+  def select(pattern)
+    # JavaScriptElementCollectionProxy.new(self, pattern)
+  end
+  
+  # Writes raw JavaScript to the page.
+  def <<(javascript)
+    @source << javascript
+  end
+  
+  # Displays an alert dialog with the given +message+.
+  def alert(message)
+    call( "alert", message )
+  end
+  
+  # Assigns the JavaScript +variable+ the given +value+.
+  def assign( variable, value )
+    record "#{variable} = #{value.inspect}"
+  end
+  
+  # Creates a script.aculo.us draggable element.
+  # See ActionView::Helpers::ScriptaculousHelper for more information.
+  def draggable( id, options = {} )
+    record @context.draggable_element_js( id, options ) + ";\n"
+  end
+  
+  # Creates a script.aculo.us drop receiving element.
+  # See ActionView::Helpers::ScriptaculousHelper for more information.
+  def drop_receiving( id, options = {} )
+    record @context.drop_receiving_element_js( id, options ) + ";\n"
+  end
+  
+  # Hides the visible DOM elements with the given +ids+.
+  def hide( *ids )
+    loop_on_multiple_args 'Element.hide', ids
+  end
+  
+  # Inserts HTML at the specified +position+ relative to the DOM element
+  # identified by the given +id+.
+  # 
+  # +position+ may be one of:
+  # 
+  # <tt>:top</tt>::    HTML is inserted inside the element, before the 
+  #                    element's existing content.
+  # <tt>:bottom</tt>:: HTML is inserted inside the element, after the
+  #                    element's existing content.
+  # <tt>:before</tt>:: HTML is inserted immediately preceeding the element.
+  # <tt>:after</tt>::  HTML is inserted immediately following the element.
+  #
+  # +data+ may be a string of HTML to insert.
+  def insert_html(position, id, data)
+    insertion = position.to_s.camelize
+    call "new Insertion.#{insertion}", id, data
+  end
+  
+  # Calls the JavaScript +function+, optionally with the given +arguments+.
+  def call(function, *arguments)
+    record "#{function}(#{arguments_for_call(arguments)});\n"
+  end
+  
+  # Redirects the browser to the given +location+.
+  def redirect_to(location)
+    assign 'window.location.href', location
+  end
+  
+  # Removes the DOM elements with the given ids from the page.
+  def remove(*ids)
+    loop_on_multiple_args 'Element.remove', ids
+  end
+  
+  # Replaces the inner HTML of the DOM element with the given +id+.
+  #
+  # +data+ may be a string of HTML to insert
+  #
+  #   # Replace the HTML of the DOM element having ID 'person-45' with the
+  #   # 'person' partial for the appropriate object.
+  #   replace_html 'person-45', render( 'person', :object => @person )
+  #
+  def replace_html(id, data)
+    call 'Element.update', id, data
+  end
+  
+  # Replaces the "outer HTML" (i.e., the entire element, not just its
+  # contents) of the DOM element with the given +id+.
+  #
+  # +data+ may be a string of HTML to insert.
+  # For example:
+  #
+  #   # Replace the DOM element having ID 'person-45' with the
+  #   # 'person' partial for the appropriate object.
+  #   replace 'person-45', render( 'person', :object => @person )
+  def replace(id, data)
+    call 'Element.replace', id, data
+  end
+  
+  # Shows hidden DOM elements with the given +ids+.
+  def show(*ids)
+    loop_on_multiple_args 'Element.show', ids
+  end
+  
+  # Creates a script.aculo.us sortable element. Useful to recreate 
+  # sortable elements after items get added or deleted.
+  def sortable(id, options = {})
+    record @context.sortable_element_js( id, options ) + ";\n"
+  end
+
+  # Creates a script.aculo.us unsortable element. Useful to recreate 
+  # unsortable elements after items get added or deleted.  
+  def unsortable( id )
+    record @context.unsortable_element_js( id ) + ";\n"
+  end
+  
+  # Toggles the visibility of the DOM elements with the given +ids+.
+  def toggle(*ids)
+    loop_on_multiple_args 'Element.toggle', ids
+  end
+  
+  # Starts a http://script.aculo.us visual effect.
+  def visual_effect(name, element_id = false, js_options = {})
+    record( @context.visual_effect( name, element_id, js_options ) + ";\n" )
+  end
+  
+  # Executes the content of the block after a delay of +seconds+. Example:
+  #
+  #   page.delay(20) do
+  #     page.visual_effect :fade, 'notice'
+  #   end
+  def delay(seconds = 1)
+    record "setTimeout(function() {\n\n"
+    yield
+    record "}, #{(seconds * 1000).to_i})"
+  end
+  
+  private
+  def record( line )
+    self << line
+  end
+  
+  def arguments_for_call(arguments)
+    arguments.map { |argument| argument.inspect }.join ', '
+  end
+  
+  def loop_on_multiple_args(method, ids)
+    record( ids.size>1 ?
+      "#{ids.inspect}.each(#{method});\n" : 
+      "#{method}(#{ids.first.inspect});\n" )
+  end
+end
+
+module BivouacHelpers
+  module JavaScriptView
+    CALLBACKS = [ :uninitialized, :loading, :loaded, :interactive, :complete, :failure, :success ] + ('100'..'599').to_a
+    
+    # Escape carrier returns and single and double quotes for JavaScript segments.
+    def escape_javascript(javascript)
+      (javascript || '').gsub('\\','\0\0').gsub(/\r\n|\n|\r/, "\\n").gsub(/["']/) { |m| "\\#{m}" }
+    end
+    
+    # Returns a JavaScript tag with the +block+ inside. 
+    # Example:
+    #
+    #   javascript_tag( "alert('Hello World!')", :defer => 'true' )
+    #
+    # Returns:
+    #
+    #   <script defer="true" type="text/javascript">
+    #   //<![CDATA[
+    #     alert('Hello World!')
+    #   //]]>
+    #   </script>
+    def javascript_tag( content, options = {} )
+      options[:type] = "text/javascript"
+      script( options ) do
+        "//<![CDATA[\n" + content + "\n//]]>"
+      end
+    end
+    
+    # Yields a JavaScriptGenerator and returns the generated JavaScript code. 
+    # Use this to update multiple elements on a page in an Ajax response. See 
+    # JavaScriptGenerator for more information.
+    def update_page( &block )
+      JavaScriptGenerator.new( self, &block ).to_s
+    end
+    
+    # Works like update_page but wraps the generated JavaScript in a <script> 
+    # tag. See JavaScriptGenerator for more information.
+    def update_page_tag( options = {}, &block )
+      javascript_tag update_page( &block ), options
+    end
+    
+    # Returns a link that will trigger a JavaScript function using the onclick 
+    # handler and return false after the fact.
+    # 
+    # The function argument can be omitted in favor of an update_page block, 
+    # which evaluates to a string when the template is rendered (instead of 
+    # making an Ajax request first).
+    # 
+    # Examples:
+    # 
+    #   link_to_function "Greeting", "alert('Hello world!')"
+    # Produces:
+    #   <a onclick="alert('Hello world!'); return false;" href="#">Greeting</a>
+    # 
+    #   link_to_function(image_tag("delete"), "if (confirm('Really?')) do_delete()")
+    # Produces:
+    #   <a onclick="if (confirm('Really?')) do_delete(); return false;" href="#">
+    #     <img src="/images/delete.png?" alt="Delete"/>
+    #   </a>
+    # 
+    #   link_to_function("Show me more", nil, :id => "more_link") do |page|
+    #     page[:details].visual_effect  :toggle_blind
+    #     page[:more_link].replace_html "Show me less"
+    #   end
+    # Produces:
+    #   <a href="#" id="more_link" onclick="try {
+    #     $(&quot;details&quot;).visualEffect(&quot;toggle_blind&quot;);
+    #     $(&quot;more_link&quot;).update(&quot;Show me less&quot;);
+    #   }
+    #   catch (e) {
+    #     alert('RJS error:\n\n' + e.toString());
+    #     alert('$(\&quot;details\&quot;).visualEffect(\&quot;toggle_blind\&quot;);
+    #     \n$(\&quot;more_link\&quot;).update(\&quot;Show me less\&quot;);');
+    #     throw e
+    #   };
+    #   return false;">Show me more</a>
+    def link_to_function( name, *args, &block )
+      html_options = args.last.is_a?(Hash) ? args.pop : {}
+      function = args[0] || ''
+      
+      function = update_page( &block ) if block_given?
+      
+      a( html_options.merge({ 
+          :href => html_options[:href] || "#", 
+          :onclick => (html_options[:onclick] ? "#{html_options[:onclick]}; " : "") + "#{function}; return false;" 
+        }) ) do
+          name
+      end
+    end
+    
+    # Returns a link to a remote action defined by <tt>options[:url]</tt> 
+    # 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. 
+    #
+    # Examples:
+    #   link_to_remote "Delete this post", :update => "posts", 
+    #     :url => R(Destroy, 1)
+    #   link_to_remote(image_tag("refresh"), :update => "emails", 
+    #     :url => R(ListEmails)
+    #
+    # You can also specify a hash for <tt>options[:update]</tt> to allow for
+    # easy redirection of output to an other DOM element if a server-side 
+    # error occurs:
+    #
+    # Example:
+    #   link_to_remote "Delete this post",
+    #     :url => R(Destroy, 1)
+    #     :update => { :success => "posts", :failure => "error" }
+    #
+    # Optionally, you can use the <tt>options[:position]</tt> parameter to 
+    # influence how the target DOM element is updated. It must be one of 
+    # <tt>:before</tt>, <tt>:top</tt>, <tt>:bottom</tt>, or <tt>:after</tt>.
+    #
+    # To access the server response, use <tt>request.responseText</tt>, to
+    # find out the HTTP status, use <tt>request.status</tt>.
+    #
+    # Example:
+    #   link_to_remote word,
+    #     :url => R(Undo, word_counter)
+    #     :complete => "undoRequestCompleted(request)"
+    #
+    # The callbacks that may be specified are (in order):
+    #
+    # <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>:success</tt>::       Called when the XMLHttpRequest is completed,
+    #                           and the HTTP status code is in the 2XX range.
+    # <tt>:failure</tt>::       Called when the XMLHttpRequest is completed,
+    #                           and the HTTP status code is not in the 2XX
+    #                           range.
+    # <tt>:complete</tt>::      Called when the XMLHttpRequest is complete 
+    #                           (fires after success/failure if they are 
+    #                           present).
+    #                     
+    # You can further refine <tt>:success</tt> and <tt>:failure</tt> by 
+    # adding additional callbacks for specific status codes.
+    #
+    # Example:
+    #   link_to_remote word,
+    #     :url => R(Action),
+    #     404 => "alert('Not found...? Wrong URL...?')",
+    #     :failure => "alert('HTTP Error ' + request.status + '!')"
+    #
+    # A status code callback overrides the success/failure handlers if 
+    # present.
+    #
+    # 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>.
+    #
+    # You can customize further browser side call logic by passing in
+    # JavaScript code snippets via some optional parameters. In their order 
+    # of use these are:
+    #
+    # <tt>:confirm</tt>::      Adds confirmation dialog.
+    # <tt>:condition</tt>::    Perform remote request conditionally
+    #                          by this expression. Use this to
+    #                          describe browser-side conditions when
+    #                          request should not be initiated.
+    # <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
+    
+    # Periodically calls the specified url (<tt>options[:url]</tt>) every 
+    # <tt>options[:frequency]</tt> seconds (default is 10). Usually used to
+    # update a specified div (<tt>options[:update]</tt>) with the results 
+    # of the remote call. The options for specifying the target with :url 
+    # and defining callbacks is the same as link_to_remote.
+    def periodically_call_remote(options = {})
+       frequency = options[:frequency] || 10 # every ten seconds by default
+       code = "new PeriodicalExecuter(function() {#{remote_function(options)}}, #{frequency})"
+       javascript_tag(code)
+    end
+    
+    # Observes the field with the DOM ID specified by +field_id+ and makes
+    # an Ajax call when its contents have changed.
+    # 
+    # Required +options+ are either of:
+    # <tt>:url</tt>::       +url_for+-style options for the action to call
+    #                       when the field has changed.
+    # <tt>:function</tt>::  Instead of making a remote call to a URL, you
+    #                       can specify a function to be called instead.
+    # 
+    # Additional options are:
+    # <tt>:frequency</tt>:: The frequency (in seconds) at which changes to
+    #                       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.
+    # <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. If you specify a
+    #                       string without a "=", it'll be extended to mean
+    #                       the form key that the value should be assigned to.
+    #                       So :with => "term" gives "'term'=value". If a "=" is
+    #                       present, no extension will happen.
+    # <tt>:on</tt>::        Specifies which event handler to observe. By default,
+    #                       it's set to "changed" for text fields and areas and
+    #                       "click" for radio buttons and checkboxes. With this,
+    #                       you can specify it instead to be "blur" or "focus" or
+    #                       any other event.
+    #
+    # Additionally, you may specify any of the options documented in
+    # link_to_remote.
+    def observe_field(field_id, options = {})
+      if options[:frequency] && options[:frequency] > 0
+        build_observer('Form.Element.Observer', field_id, options)
+      else
+        build_observer('Form.Element.EventObserver', field_id, options)
+      end
+    end
+    
+    # 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 => R(Update), 
+    #                                         :onSuccess => visual_effect( :highlight, 'my_element' ) 
+    #                                       ) 
+    #         ) do
+    #     option( "Hello", :value => 0 )
+    #     option( "World", :value => 1 )
+    #   end
+    def remote_function(options)
+      javascript_options = options_for_ajax(options)
+
+      update = ''
+      if options[:update] && options[:update].is_a?(Hash)
+        update  = []
+        update << "success:'#{options[:update][:success]}'" if options[:update][:success]
+        update << "failure:'#{options[:update][:failure]}'" if options[:update][:failure]
+        update  = '{' + update.join(',') + '}'
+      elsif options[:update]
+        update << "'#{options[:update]}'"
+      end
+
+      function = update.empty? ? 
+        "new Ajax.Request(" :
+        "new Ajax.Updater(#{update}, "
+
+      function << "'#{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]
+      function = "if (confirm('#{escape_javascript(options[:confirm])}')) { #{function}; }" if options[:confirm]
+
+      return function
+    end
+       
+    private
+    
+    def options_for_javascript(options) #:nodoc:
+      '{' + 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)
+    
+      js_options['asynchronous'] = options[:type] != :synchronous
+      js_options['method']       = method_option_to_s(options[:method]) if options[:method]
+      js_options['insertion']    = "Insertion.#{options[:position].to_s.camelize}" if options[:position]
+      js_options['evalScripts']  = options[:script].nil? || options[:script]
+
+      if options[:form]
+        js_options['parameters'] = 'Form.serialize(this)'
+      elsif options[:submit]
+        js_options['parameters'] = "Form.serialize('#{options[:submit]}')"
+      elsif options[:with]
+        js_options['parameters'] = options[:with]
+      end
+    
+      options_for_javascript(js_options)
+    end
+    
+    def build_callbacks( options )
+      callbacks = {}
+      options.each do |callback, code|
+        if CALLBACKS.include?(callback)
+          name = 'on' + callback.to_s.capitalize
+          callbacks[name] = "function(request){#{code}}"
+        end
+      end
+      callbacks
+    end
+    
+    def build_observer(klass, name, options = {})
+      if options[:with] && !options[:with].include?("=")
+        options[:with] = "'#{options[:with]}=' + value"
+      else
+        options[:with] ||= "'#{name}=' + value" if options[:update]
+      end
+
+      callback = options[:function] || remote_function(options)
+      javascript  = "new #{klass}('#{name}', "
+      javascript << "#{options[:frequency]}, " if options[:frequency]
+      javascript << "function(element, value) {"
+      javascript << "#{callback}}"
+      javascript << ", '#{options[:on]}'" if options[:on]
+      javascript << ")"
+      javascript_tag(javascript)
+    end
+  end
+end