template_streaming 0.0.3 → 0.0.4

data/CHANGELOG

@@ -1,3 +1,9 @@
+== 0.0.4 2010-04-26
+
+ * Add when_streaming_template callback. Called after an action that
+   streams a template.
+ * Ensure flash is swept before headers are output.
+
 == 0.0.3 2010-04-23
 
  * Fix #render calls which don't render templates (e.g. :text => '').

data/README.markdown

@@ -33,14 +33,50 @@ profiles that look more like:
 
 ![Progressive Rendering Profile][fast-profile]
 
-Also provided is a `#push(data)` method which can be used to send extra tags to
-the client as their need becomes apparent. For instance, you may wish to `push`
-out a stylesheet link tag only if a particular partial is reached which contains
-a complex widget.
-
 [slow-profile]: http://github.com/oggy/template_streaming/raw/master/doc/slow-profile.png
 [fast-profile]: http://github.com/oggy/template_streaming/raw/master/doc/fast-profile.png
 
+## API
+
+The API is simple, but it's important to understand the change in control flow
+when a template is streamed. A controller's `render` no longer results in
+rendering templates immediately; instead, `response.body` is set to a
+`StreamingBody` object which will render the template when the server calls
+`#each` on the body *after* the action returns, as per the Rack specification.
+This has several implications:
+
+ * Anything that needs to inspect or modify the body should be moved to a
+   middleware.
+ * Modifications to cookies (this includes the flash and session if using the
+   cookie store!) should not be made in the view.
+ * An exception during rendering cannot simply replace the body with a
+   stacktrace or 500 page. (Solution to come.)
+
+### Helpers
+
+ * `flush` - flush what has been rendered in the current template out to the
+    client immediately.
+ * `push(data)` - send the given data to the client immediately.
+
+These can only do their job if the underlying web server supports progressive
+rendering via Rack. This has been tested successfully with [Mongrel][mongrel]
+and [Passenger][passenger]. [Thin][thin] is only supported if the [Event Machine
+Flush][event-machine-flush] gem is installed. WEBrick does not support
+progressive rendering. [Please send me][contact] reports of success with other
+web servers!
+
+[mongrel]: http://github.com/fauna/mongrel
+[passenger]: http://www.modrails.com
+[thin]: http://github.com/macournoyer/thin
+[event-machine-flush]: http://github.com/oggy/event_machine_flush
+[contact]: mailto:george.ogata@gmail.com
+
+### Controller
+
+ * `when_streaming_template` - defines a callback to be called during a `render`
+   call when a template is streamed. This is *before* the body is rendered, or
+   any data is sent to the client.
+
 ## Example
 
 Conventional wisdom says to put your external stylesheets in the HEAD of your

data/lib/template_streaming.rb

@@ -1,8 +1,25 @@
 module TemplateStreaming
+  class << self
+    def configure(config)
+      config.each do |key, value|
+        send "#{key}=", value
+      end
+    end
+
+    attr_accessor :autosweep_flash
+  end
+
+  self.autosweep_flash = true
+
   module Controller
     def self.included(base)
-      base.alias_method_chain :render, :template_streaming
-      base.helper_method :flush, :push
+      base.class_eval do
+        alias_method_chain :render, :template_streaming
+        helper_method :flush, :push
+
+        include ActiveSupport::Callbacks
+        define_callbacks :when_streaming_template
+      end
     end
 
     def render_with_template_streaming(*args, &block)
@@ -19,6 +36,20 @@ module TemplateStreaming
           end
           response.body = @streaming_body
           response.prepare!
+          flash if TemplateStreaming.autosweep_flash
+          run_callbacks :when_streaming_template
+
+          # Normally, @_flash is removed after #perform_action, which
+          # means calling #flash in the view would cause a new
+          # FlashHash to be constructed. On top of that, the flash is
+          # swept on construction, which results in sweeping the flash
+          # twice, obliterating its contents.
+          #
+          # So, we preserve the flash here under a different ivar, and
+          # override the #flash helper to return it.
+          if defined?(@_flash)
+            @template_streaming_flash = @_flash
+          end
         else
           render_without_template_streaming(*args, &block)
         end
@@ -43,6 +74,10 @@ module TemplateStreaming
       flush_thin
     end
 
+    def template_streaming_flash # :nodoc:
+      @template_streaming_flash
+    end
+
     private # --------------------------------------------------------
 
     #
@@ -136,6 +171,7 @@ module TemplateStreaming
   module View
     def self.included(base)
       base.alias_method_chain :_render_with_layout, :template_streaming
+      base.alias_method_chain :flash, :template_streaming
     end
 
     def _render_with_layout_with_template_streaming(options, local_assigns, &block)
@@ -177,6 +213,11 @@ module TemplateStreaming
       view_paths.find_template('pre' + layout.path_without_format_and_extension, layout.format)
     rescue ActionView::MissingTemplate
     end
+
+    def flash_with_template_streaming # :nodoc:
+      # Override ActionView::Base#flash to prevent a double-sweep.
+      controller.instance_eval { @template_streaming_flash || flash }
+    end
   end
 
   class StreamingBody

data/lib/template_streaming/version.rb

@@ -1,3 +1,11 @@
 module TemplateStreaming
-  VERSION = [0, 0, 3]
+  VERSION = [0, 0, 4]
+
+  class << VERSION
+    include Comparable
+
+    def to_s
+      join('.')
+    end
+  end
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - George Ogata
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-23 00:00:00 -04:00
+date: 2010-04-26 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency