require 'set'
require 'active_support/json'
require 'active_support/core_ext/object/returning'
module ActionView
module Helpers
# Prototype[http://www.prototypejs.org/] is a JavaScript library that provides
# DOM[http://en.wikipedia.org/wiki/Document_Object_Model] manipulation,
# Ajax[http://www.adaptivepath.com/publications/essays/archives/000385.php]
# functionality, and more traditional object-oriented facilities for JavaScript.
# This module provides a set of helpers to make it more convenient to call
# functions from Prototype using Rails, including functionality to call remote
# Rails methods (that is, making a background request to a Rails action) using Ajax.
# 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. A common use case is having a form that adds
# a new element to a list without reloading the page or updating a shopping
# cart total when a new item is added.
#
# == Usage
# To be able to use these helpers, you must first include the Prototype
# JavaScript framework in your pages.
#
# javascript_include_tag 'prototype'
#
# (See the documentation for
# ActionView::Helpers::JavaScriptHelper for more information on including
# this and other JavaScript files in your Rails templates.)
#
# Now you're ready to call a remote action either through a link...
#
# link_to_remote "Add to cart",
# :url => { :action => "add", :id => product.id },
# :update => { :success => "cart", :failure => "error" }
#
# ...through a form...
#
# <% form_remote_tag :url => '/shipping' do -%>
#
<%= submit_tag 'Recalculate Shipping' %>
# <% end -%>
#
# As you can see, there are numerous ways to use Prototype's Ajax functions (and actually more than
# are listed here); check out the documentation for each method to find out more about its usage and options.
#
# === Common Options
# See link_to_remote for documentation of options common to all Ajax
# helpers; any of the options specified by link_to_remote can be used
# by the other helpers.
#
# == Designing your Rails actions for Ajax
# When building your action handlers (that is, the Rails actions that receive your background requests), it's
# important to remember a few things. First, whatever your action would normally return to the browser, it will
# return to the Ajax call. As such, you typically don't want to render with a layout. This call will cause
# the layout to be transmitted back to your page, and, if you have a full HTML/CSS, will likely mess a lot of things up.
# You can turn the layout off on particular actions by doing the following:
#
# class SiteController < ActionController::Base
# layout "standard", :except => [:ajax_method, :more_ajax, :another_ajax]
# end
#
# Optionally, you could do this in the method you wish to lack a layout:
#
# render :layout => false
#
# You can tell the type of request from within your action using the request.xhr? (XmlHttpRequest, the
# method that Ajax uses to make background requests) method.
# def name
# # Is this an XmlHttpRequest request?
# if (request.xhr?)
# render :text => @name.to_s
# else
# # No? Then render an action.
# render :action => 'view_attribute', :attr => @name
# end
# end
#
# The else clause can be left off and the current action will render with full layout and template. An extension
# to this solution was posted to Ryan Heneise's blog at ArtOfMission["http://www.artofmission.com/"].
#
# layout proc{ |c| c.request.xhr? ? false : "application" }
#
# Dropping this in your ApplicationController turns the layout off for every request that is an "xhr" request.
#
# If you are just returning a little data or don't want to build a template for your output, you may opt to simply
# render text output, like this:
#
# render :text => 'Return this from my method!'
#
# Since whatever the method returns is injected into the DOM, this will simply inject some text (or HTML, if you
# tell it to). This is usually how small updates, such updating a cart total or a file count, are handled.
#
# == Updating multiple elements
# See JavaScriptGenerator for information on updating multiple elements
# on the page in an Ajax response.
module PrototypeHelper
unless const_defined? :CALLBACKS
CALLBACKS = Set.new([ :create, :uninitialized, :loading, :loaded,
:interactive, :complete, :failure, :success ] +
(100..599).to_a)
AJAX_OPTIONS = Set.new([ :before, :after, :condition, :url,
:asynchronous, :method, :insertion, :position,
:form, :with, :update, :script, :type ]).merge(CALLBACKS)
end
# Returns a button with the given +name+ text that'll trigger a JavaScript +function+ using the
# onclick handler.
#
# The first argument +name+ is used as the button's value or display text.
#
# The next arguments are optional and may include the javascript function definition and a hash of html_options.
#
# 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).
#
# The +html_options+ will accept a hash of html attributes for the link tag. Some examples are :class => "nav_button", :id => "articles_nav_button"
#
# 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
#
# Examples:
# button_to_function "Greeting", "alert('Hello world!')"
# button_to_function "Delete", "if (confirm('Really?')) do_delete()"
# button_to_function "Details" do |page|
# page[:details].visual_effect :toggle_slide
# end
# button_to_function "Details", :class => "details_button" do |page|
# page[:details].visual_effect :toggle_slide
# end
def button_to_function(name, *args, &block)
html_options = args.extract_options!.symbolize_keys
function = block_given? ? update_page(&block) : args[0] || ''
onclick = "#{"#{html_options[:onclick]}; " if html_options[:onclick]}#{function};"
tag(:input, html_options.merge(:type => 'button', :value => name, :onclick => onclick))
end
# Returns the JavaScript needed for a remote function.
# Takes the same arguments as link_to_remote.
#
# Example:
# # Generates: