vendor/rails/actionpack/lib/action_controller/flash.rb

   1 module ActionController #:nodoc:
   2   # The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed
   3   # to the very next action and then cleared out. This is a great way of doing notices and alerts, such as a create
   4   # action that sets <tt>flash[:notice] = "Successfully created"</tt> before redirecting to a display action that can
   5   # then expose the flash to its template. Actually, that exposure is automatically done. Example:
   6   #
   7   #   class WeblogController < ActionController::Base
   8   #     def create
   9   #       # save post
  10   #       flash[:notice] = "Successfully created post"
  11   #       redirect_to :action => "display", :params => { :id => post.id }
  12   #     end
  13   #
  14   #     def display
  15   #       # doesn't need to assign the flash notice to the template, that's done automatically
  16   #     end
  17   #   end
  18   #
  19   #   display.erb
  20   #     <% if flash[:notice] %><div class="notice"><%= flash[:notice] %></div><% end %>
  21   #
  22   # This example just places a string in the flash, but you can put any object in there. And of course, you can put as
  23   # many as you like at a time too. Just remember: They'll be gone by the time the next action has been performed.
  24   #
  25   # See docs on the FlashHash class for more details about the flash.
  26   module Flash
  27     def self.included(base)
  28       base.class_eval do
  29         include InstanceMethods
  30         alias_method_chain :assign_shortcuts, :flash
  31         alias_method_chain :process_cleanup,  :flash
  32         alias_method_chain :reset_session,    :flash
  33       end
  34     end
  35
  36
  37     class FlashNow #:nodoc:
  38       def initialize(flash)
  39         @flash = flash
  40       end
  41
  42       def []=(k, v)
  43         @flash[k] = v
  44         @flash.discard(k)
  45         v
  46       end
  47
  48       def [](k)
  49         @flash[k]
  50       end
  51     end
  52
  53     class FlashHash < Hash
  54       def initialize #:nodoc:
  55         super
  56         @used = {}
  57       end
  58
  59       def []=(k, v) #:nodoc:
  60         keep(k)
  61         super
  62       end
  63
  64       def update(h) #:nodoc:
  65         h.keys.each { |k| keep(k) }
  66         super
  67       end
  68
  69       alias :merge! :update
  70
  71       def replace(h) #:nodoc:
  72         @used = {}
  73         super
  74       end
  75
  76       # Sets a flash that will not be available to the next action, only to the current.
  77       #
  78       #     flash.now[:message] = "Hello current action"
  79       #
  80       # This method enables you to use the flash as a central messaging system in your app.
  81       # When you need to pass an object to the next action, you use the standard flash assign (<tt>[]=</tt>).
  82       # When you need to pass an object to the current action, you use <tt>now</tt>, and your object will
  83       # vanish when the current action is done.
  84       #
  85       # Entries set via <tt>now</tt> are accessed the same way as standard entries: <tt>flash['my-key']</tt>.
  86       def now
  87         FlashNow.new(self)
  88       end
  89
  90       # Keeps either the entire current flash or a specific flash entry available for the next action:
  91       #
  92       #    flash.keep            # keeps the entire flash
  93       #    flash.keep(:notice)   # keeps only the "notice" entry, the rest of the flash is discarded
  94       def keep(k = nil)
  95         use(k, false)
  96       end
  97
  98       # Marks the entire flash or a single flash entry to be discarded by the end of the current action:
  99       #
 100       #     flash.discard              # discard the entire flash at the end of the current action
 101       #     flash.discard(:warning)    # discard only the "warning" entry at the end of the current action
 102       def discard(k = nil)
 103         use(k)
 104       end
 105
 106       # Mark for removal entries that were kept, and delete unkept ones.
 107       #
 108       # This method is called automatically by filters, so you generally don't need to care about it.
 109       def sweep #:nodoc:
 110         keys.each do |k|
 111           unless @used[k]
 112             use(k)
 113           else
 114             delete(k)
 115             @used.delete(k)
 116           end
 117         end
 118
 119         # clean up after keys that could have been left over by calling reject! or shift on the flash
 120         (@used.keys - keys).each{ |k| @used.delete(k) }
 121       end
 122
 123       private
 124         # Used internally by the <tt>keep</tt> and <tt>discard</tt> methods
 125         #     use()               # marks the entire flash as used
 126         #     use('msg')          # marks the "msg" entry as used
 127         #     use(nil, false)     # marks the entire flash as unused (keeps it around for one more action)
 128         #     use('msg', false)   # marks the "msg" entry as unused (keeps it around for one more action)
 129         def use(k=nil, v=true)
 130           unless k.nil?
 131             @used[k] = v
 132           else
 133             keys.each{ |key| use(key, v) }
 134           end
 135         end
 136     end
 137
 138     module InstanceMethods #:nodoc:
 139       protected
 140         def reset_session_with_flash
 141           reset_session_without_flash
 142           remove_instance_variable(:@_flash)
 143           flash(:refresh)
 144         end
 145
 146         # Access the contents of the flash. Use <tt>flash["notice"]</tt> to read a notice you put there or
 147         # <tt>flash["notice"] = "hello"</tt> to put a new one.
 148         # Note that if sessions are disabled only flash.now will work.
 149         def flash(refresh = false) #:doc:
 150           if !defined?(@_flash) || refresh
 151             @_flash =
 152               if session.is_a?(Hash)
 153                 # don't put flash in session if disabled
 154                 FlashHash.new
 155               else
 156                 # otherwise, session is a CGI::Session or a TestSession
 157                 # so make sure it gets retrieved from/saved to session storage after request processing
 158                 session["flash"] ||= FlashHash.new
 159               end
 160           end
 161
 162           @_flash
 163         end
 164
 165       private
 166         def assign_shortcuts_with_flash(request, response) #:nodoc:
 167           assign_shortcuts_without_flash(request, response)
 168           flash(:refresh)
 169         end
 170
 171         def process_cleanup_with_flash
 172           flash.sweep if @_session
 173           process_cleanup_without_flash
 174         end
 175     end
 176   end
 177 end