template_streaming 0.0.1

data/CHANGELOG

@@ -0,0 +1,3 @@
+== 0.0.1 2010-04-13
+
+ * Hi.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 George Ogata
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,163 @@
+# Template Streaming
+
+Rails plugin which enables progressive rendering for templates.
+
+## Background
+
+A typical Rails client-side profile looks something like this:
+
+<img
+  alt="Typical Rails Profile"
+  src="http://github.com/oggy/template_streaming/raw/master/doc/slow-profile.png"
+  style="width: 100%"
+/>
+
+In almost all cases, this is highly suboptimal, as many resources, such as
+external stylesheets, are static and could be loaded by the client while it's
+waiting for the server response.
+
+The trick is to output the response *progressively*--flushing the stylesheet
+link tags out to the client before it has rendered the rest of the
+page. Depending on how other external resources such javascripts and images are
+used, they too may be flushed out early, significantly reducing the time for the
+page to become interactive.
+
+The problem is Rails has never been geared to allow this. Most Rails
+applications use layouts, which require rendering the content of the page before
+the layout. Since the global stylesheet tag is usually in the layout, we can't
+simply flush the rendering buffer from a helper method.
+
+Until now.
+
+Template Streaming circumvents the template rendering order by introducing
+*prelayouts*. A prelayout wraps a layout, and is rendered *before* the layout
+and its content. By using the provided `flush` helper prior to yielding in the
+prelayout, one can now output content early in the rendering process, giving
+profiles that look more like:
+
+<img
+  alt="Progressive Rendering Profile"
+  src="http://github.com/oggy/template_streaming/raw/master/doc/fast-profile.png"
+  style="width: 100%"
+/>
+
+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.
+
+## Example
+
+Conventional wisdom says to put your external stylesheets in the HEAD of your
+page, and your external javascripts at the bottom of the BODY (markup in
+[HAML][haml]):
+
+### `app/views/prelayouts/application.html.haml`
+
+    !!! 5
+    %html
+      %head
+        = stylesheet_link_tag 'one'
+        = stylesheet_link_tag 'two'
+     - flush
+     = yield
+
+### `app/views/layouts/application.html.haml`
+
+    %body
+      = yield
+      = javascript_include_tag 'one'
+      = javascript_include_tag 'two'
+
+With progressive rendering, however, this could be improved. As [Stoyan Stefanov
+writes][stefanov], you can put your javascripts in the HEAD of your page if you
+fetch them via AJAX and append them to the HEAD of your page dynamically. This
+also reduces the time for the page to become interactive (e.g., scrollable),
+giving an even greater perceived performance boost.
+
+Of course, rather than using an external library for the AJAX call, we can save
+ourselves a roundtrip by defining a `getScript` function ourselves in a small
+piece of inline javascript. This is done by `define_get_script`
+below. `get_script` then includes a call to this function which fetches the
+script asynchronously, and then appends the script tag to the HEAD.
+
+### `app/views/prelayouts/application.html.haml`
+
+    !!! 5
+    %html
+      %head
+        = define_get_script
+        = stylesheet_link_tag 'one'
+        = stylesheet_link_tag 'two'
+        = get_script 'one'
+        = get_script 'two'
+     - flush
+     = yield
+
+### `app/views/layouts/application.html.haml`
+
+    %body
+      = yield
+
+### `app/helpers/application_helper.rb`
+
+    module ApplicationHelper
+      def define_get_script
+        javascript_tag do
+          File.read(Rails.public_path + '/javascripts/get_script.js')
+        end
+      end
+
+      def get_script(url)
+        javascript_tag do
+          "$.getScript('#{javascript_path(url)}');"
+        end
+      end
+    end
+
+### `public/javascripts/get_script.js`
+
+    //
+    // Written by Sam Cole. See http://gist.github.com/364746 for more info.
+    //
+    window.$ = {
+      getScript: function(script_src, callback) {
+        var done = false;
+        var head = document.getElementsByTagName("head")[0] || document.documentElement;
+        var script = document.createElement("script");
+        script.src = script_src;
+        script.onload = script.onreadystatechange = function() {
+          if ( !done && (!this.readyState ||
+              this.readyState === "loaded" || this.readyState === "complete") ) {
+            if(callback) callback();
+
+            // Handle memory leak in IE
+            script.onload = script.onreadystatechange = null;
+            if ( head && script.parentNode ) {
+              head.removeChild( script );
+            }
+
+            done = true;
+          }
+        };
+        head.insertBefore( script, head.firstChild );
+      }
+    };
+
+The second profile was created using this code.
+
+[haml]: http://haml-lang.com
+[stefanov]: http://www.yuiblog.com/blog/2008/07/22/non-blocking-scripts
+[get-script]: http://gist.github.com/364746
+
+## Note on Patches/Pull Requests
+
+ * Bug reports: http://github.com/oggy/template_streaming/issues
+ * Source: http://github.com/oggy/template_streaming
+ * Patches: Fork on Github, send pull request.
+   * Ensure patch includes tests.
+   * Leave the version alone, or bump it in a separate commit.
+
+## Copyright
+
+Copyright (c) 2010 George Ogata. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,22 @@
+gem 'ritual'
+require 'ritual'
+
+spec_task :spec do |t|
+  t.libs << 'lib' << 'spec'
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+spec_task :rcov do |t|
+  t.libs << 'lib' << 'spec'
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rcov = true
+end
+
+rdoc_task do |t|
+  t.rdoc_dir = 'rdoc'
+  t.title = "Template Streaming #{version}"
+  t.rdoc_files.include('README*')
+  t.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :spec

data/lib/template_streaming.rb

@@ -0,0 +1,172 @@
+module TemplateStreaming
+  module Controller
+    def self.included(base)
+      base.alias_method_chain :render, :template_streaming
+      base.helper_method :flush, :push
+    end
+
+    def render_with_template_streaming(*args, &block)
+      # Only install our StreamingBody in the toplevel #render call.
+      @render_stack_height ||= 0
+      @render_stack_height += 1
+      begin
+        if @render_stack_height == 1
+          @performed_render = true
+          @streaming_body = StreamingBody.new(progressive_rendering_threshold) do
+            @performed_render = false
+            last_piece = render_without_template_streaming(*args, &block)
+            # The original render will clobber our response.body, so
+            # we must push the buffer ourselves.
+            push last_piece
+          end
+          response.body = @streaming_body
+          response.prepare!
+        else
+          render_without_template_streaming(*args, &block)
+        end
+      ensure
+        @render_stack_height -= 1
+      end
+    end
+
+    #
+    # Flush the current template's output buffer out to the client
+    # immediately.
+    #
+    def flush
+      unless @template.output_buffer.nil?
+        push @template.output_buffer.slice!(0..-1)
+      end
+    end
+
+    #
+    # Push the given data to the client immediately.
+    #
+    def push(data)
+      @streaming_body.push(data)
+    end
+
+    private # --------------------------------------------------------
+
+    #
+    # The number of bytes that must be received by the client before
+    # anything will be rendered.
+    #
+    def progressive_rendering_threshold
+      response.header['Content-type'] =~ %r'\Atext/html' or
+        return 0
+
+      case request.env['HTTP_USER_AGENT']
+      when /MSIE/
+        255
+      when /Chrome/
+        # Note: Chrome's UA string includes "Safari", so it must precede.
+        2048
+      when /Safari/
+        1024
+      else
+        0
+      end
+    end
+  end
+
+  # Only prepare once.
+  module Response
+    def self.included(base)
+      base.alias_method_chain :prepare!, :template_streaming
+      base.alias_method_chain :set_content_length!, :template_streaming
+    end
+
+    def prepare_with_template_streaming!
+      return if defined?(@prepared)
+      prepare_without_template_streaming!
+      @prepared = true
+    end
+
+    def set_content_length_with_template_streaming!
+      if body.is_a?(StreamingBody)
+        # pass
+      else
+        set_content_length_without_template_streaming!
+      end
+    end
+  end
+
+  module View
+    def self.included(base)
+      base.alias_method_chain :_render_with_layout, :template_streaming
+    end
+
+    def _render_with_layout_with_template_streaming(options, local_assigns, &block)
+      with_prelayout prelayout_for(options), local_assigns do
+        _render_with_layout_without_template_streaming(options, local_assigns, &block)
+      end
+    end
+
+    def with_prelayout(prelayout, locals, &block)
+      if prelayout
+        begin
+          @_proc_for_layout = lambda do
+            # nil out @_proc_for_layout else rendering with the layout will call it again.
+            @_proc_for_layout, original_proc_for_layout = nil, @_proc_for_layout
+            begin
+              block.call
+            ensure
+              @_proc_for_layout = original_proc_for_layout
+            end
+          end
+          render(:file => prelayout, :locals => locals)
+        ensure
+          @_proc_for_layout = nil
+        end
+      else
+        yield
+      end
+    end
+
+    def prelayout_for(options)
+      layout = options[:layout] or
+        return nil
+      # Views can call #render with :layout to render a layout
+      # *partial* which we don't want to interfere with. Only the
+      # interlal toplevel #render calls :layout with an
+      # ActionView::Template
+      layout.is_a?(ActionView::Template) or
+        return nil
+      view_paths.find_template('pre' + layout.path_without_format_and_extension, layout.format)
+    rescue ActionView::MissingTemplate
+    end
+  end
+
+  class StreamingBody
+    def initialize(threshold, &block)
+      @process = block
+      @bytes_to_threshold = threshold
+    end
+
+    def each(&block)
+      @push = block
+      @process.call
+    end
+
+    def push(data)
+      if @bytes_to_threshold > 0
+        @push.call(data + padding)
+        @bytes_to_threshold = 0
+      else
+        @push.call(data)
+      end
+    end
+
+    private  # -------------------------------------------------------
+
+    def padding
+      content_length = [@bytes_to_threshold - 7, 0].max
+      "<!--#{'-'*content_length}-->"
+    end
+  end
+
+  ActionView::Base.send :include, View
+  ActionController::Base.send :include, Controller
+  ActionController::Response.send :include, Response
+end

data/lib/template_streaming/version.rb

@@ -0,0 +1,3 @@
+module TemplateStreaming
+  VERSION = [0, 0, 1]
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: template_streaming
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- George Ogata
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-13 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: |
+  Adds a #flush helper to Rails which lets you flush the output
+  buffer to the client early, allowing the client to begin fetching
+  external resources while the server is rendering the page.
+
+email: 
+- george.ogata@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- doc/fast-profile.png
+- doc/slow-profile.png
+- lib/template_streaming/version.rb
+- lib/template_streaming.rb
+- LICENSE
+- README.markdown
+- Rakefile
+- CHANGELOG
+has_rdoc: true
+homepage: http://github.com/oggy/template_streaming
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Rails plugin which enables progressive rendering.
+test_files: []
+