RubyGems - render-later - Versions diffs - 0.1.0 - Mend

render-later 0.1.0

Files changed (13) hide show

checksums.yaml +7 -0
data/.gitignore +12 -0
data/.travis.yml +13 -0
data/Gemfile +4 -0
data/LICENSE.txt +21 -0
data/README.md +131 -0
data/Rakefile +10 -0
data/app/helpers/render_later/view_helper.rb +44 -0
data/lib/render-later.rb +6 -0
data/lib/render-later/engine.rb +4 -0
data/lib/render-later/version.rb +3 -0
data/render-later.gemspec +28 -0
metadata +141 -0

checksums.yaml ADDED

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3ed24ef6ef278f6b32265a03b669da4dfd2d89a5
+  data.tar.gz: 679cb4db160e2f287656ccfe4ef1b8e05484af3f
+SHA512:
+  metadata.gz: ce8efe885bf50f0cb29b4070d739f812a1049109567198b39fd4f90e76d80def1b7c2771c5ea8fe658051673ad67c8f3af5cc61d46b883d6ac6cc06b79fcb8ec
+  data.tar.gz: 6db85e49c804372d9e887e288ce9390075410e2123e7e6089f57b128ac389f87fc5a86a4f5a848fe9bd5f177d15554787eb853369127b423de6c35df6de94af4

data/.gitignore ADDED

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/test/dummy/tmp
+/test/dummy/log
+/test/gemfiles/*.lock

data/.travis.yml ADDED

@@ -0,0 +1,13 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
+gemfile:
+  - test/gemfiles/rails-4.1.gemfile
+  - test/gemfiles/rails-4.2.gemfile
+matrix:
+  include:
+    - rvm: 2.3.0
+      gemfile: test/gemfiles/rails-5.0.gemfile

data/Gemfile ADDED

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+# Specify your gem's dependencies in render-later.gemspec
+gemspec

data/LICENSE.txt ADDED

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+Copyright (c) 2016 Adrien Jarthon
+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.md ADDED

@@ -0,0 +1,131 @@
+# render-later [![Build Status](https://travis-ci.org/jarthod/render-later.svg?branch=master)](https://travis-ci.org/jarthod/render-later)
+render-later is a Rails helper allowing you to **defer** the rendering of slow parts of your views to the end of the page, drastically improving the time to first paint and thus the perceived performance.
+![render-later-demo-gif](https://cloud.githubusercontent.com/assets/201687/12373435/779addfc-bc79-11e5-8863-64e985387d48.gif)
+It works pretty simply by storing the blocks to render later and putting an invisible span with a unique ID instead. Then at the end of the page (right before `</body>`) it'll execute these blocks and insert inline javascript tags to replace the invisible spans with the real content. The trick is to enable HTTP streaming so the browser can render all the page quickly and add the deferred parts as they are received.
+I've been using this since May 2015 on [updown.io](https://updown.io) without any trouble and decided it is time to extract it as a gem so everyone can use it. It is easy to use and pretty low-tech as it only requires HTTP/1.1 and DOM level 2 (IE6+). See the [compatibility section](#compatibility) for more details.
+## Usage
+Add the gem to your application's Gemfile:
+```ruby
+gem 'render-later'
+```
+In your views, simply wrap a slow piece of code into a `render_later` block, and gives it a unique key as argument, like you would do with `cache`. Example:
+```erb
+<div class="server">
+  <%= server.name %>
+  <%= render_later "srv-uptime-#{server.id}" do %>
+    <%= server.uptime %>
+  <% end %>
+</div>
+```
+It's important to use the `<%=` erb tag here, as the helper will render a hidden span tag.
+In your layout, before the end of the body tag, add a call to `render_now`:
+```erb
+<body>
+  <%= yield %>
+  <%= render_now %>
+</body>
+```
+This is where the deferred blocks will be rendered and injected into the page using inline javascript.
+## Performance
+Performance-wise, this approach is quite interesting, let me explain why:
+We know for a time that with bandwidth always increasing, web performance is getting more and more constrained by latency.
+For cases like this, there is usually two ways:
+1. Render everything inline and slow down the page load.
+2. Load the slow data with Ajax, after the initial page is loaded.
+The first solution is, IMO, decent **if using streaming**, because the browser can start loading css and js while the rest of the page is being streamed. But let's be honest, nobody does streaming, especially in the rails world, often leading to 1s+ page generation time (= 2s+ white screen for the user).
+The second solution gets the first page rendered quickly but is much more complex to setup (needs another endpoint to expose the data, an Ajax call to fetch them, and some js to put the data back where it belongs, handle loading spinner, errors, etc.). It is also much **slower to load**, because the browser needs to load & parse all the javascript, wait to the entire page to be ready (domready), and only then it will start the ajax call, adding the whole round-trip time once again to the page loading.
+Whereas with async-render, you leverage the existing open socket currently downloading the document to stream the deferred data:
+- You don't have to handle errors, because it's the same request. So if it fails at this point, the browser will simply show it's native error page.
+- You don't have to show any kind of spinner because the browser is still showing it's native loading indicator.
+- You don't increase latency because the additional data start streaming right after the page is sent. And even better, the deferred data **starts rendering even if the browser didn't receive a single byte yet**, so if you're on a slow network (ex: 3G, 500ms rtt), instead of delaying even more (Ajax call), you'll actually receive the document **already complete**, because while the network lagged, the server was working :)
+So in the end, this solutions is the best of both world: you get the first paint time of the Ajax version, but with the simplicity and time-to-full-document of the simple inline version.
+The only downside of this approach is that the domeady event will only be executed at the end of the request, once the body is complete. See the [Gotcha section](#gotcha) for more details.
+## Compatibility
+On the server side, the gem is tested against `ruby 2.1+` and `rails 4.1+`.
+The dependency is not strictly enforced though and it may work with others versions but we don't guaranty anything.
+The generated javascript is a simple inline function using nothing else than DOM Core level 2 properties, so it should work flawlessly on IE6+, Firefox 2+, Chrome 1+, Edge, Safari, etc.
+## Gotcha
+#### domready
+The domeady event will only be executed at the end of the request, once the body is complete. So if you have a lot of javascript on domready, which for example bind clicks to popups and ajax actions, there will be a timeframe during which the user will be able to click and the js isn't executed yet.
+This is actually an issue with streaming or async javascript loading and has nothing to do with render-later, but as render-later pushes you to use streaming it feels right to warn you about this.
+To circumvent this you can use event delegation and bind outside the domready event for example, and/or make sure your links won't lead to an error page if clicked without javascript.
+#### Web server
+Not all ruby web servers supports HTTP streaming unfortunately. So you obviously need to use one which does. Here is a non-exhaustive list of servers along with their support:
+Server            | Supported  | Comment
+------------------|------------| -------
+Phusion Passenger | ✔️         |
+Unicorn           | ✔️         | _with `tcp_nopush: false`_
+puma              | ✔️         |
+WEBrick           | ❌         | _default for `rails s`_
+To try it in development I recommend simply adding `gem 'puma'` to your `Gemfile` and `rails s` will use it. Though it's totally fine to work with a server which doesn't support streaming, you just won't benefit from the speed.
+#### Template Engine
+Like for web servers, some template engine in Rails doesn't support streaming and requires to generate the entire page before sending it on the wire. You will need to avoid them at least for the layout page which will contain the `render_now` statement.
+Template engine | Supported  | Comment
+----------------|------------| -------
+ERB             | ✔️         | _rails default_
+Slim            | ✔️         |
+Haml            | ❌         |
+#### Flash message & CSRF token
+There is currently an [issue with Rails i'm trying to revive](https://github.com/rails/rails/issues/11476) about streaming causing trouble with flash messages and CSRF tokens. This is because rails waits the end of the request to check if you have used the flash message, if so it is removed from the store, otherwise it stays for the next request. But with streaming on, rails considers the requests as ended very early, before the flash message ever gets a change to be rendered. So this logic fails and keeps the flash message forever. The problem is exactly the same with the CSRF token.
+The best **workaround** we currently have is to fool rails by accessing the flash message and CSRF token before the render call:
+```ruby
+  # in the controller, before every streaming render.
+  def index
+    form_authenticity_token; flash
+    render stream: true
+  end
+```
+#### Caching
+Finally, before your scratch your head, be careful not to put fragment caching **outside** a `render_later` block, because that would actually cache the empty span but not the inline script (which is generated by `render_now`), so it would be a waste and the real content will never be injected. It's totally **fine/recommended** to use fragment caching **inside** the `render_later` block.
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/jarthod/render-later.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake` to run the tests.
+## Ideas for improvement
+- Wider test coverage across browsers using [Sauce Labs](https://saucelabs.com/opensauce/)
+- Parallel rendering (I tried quickly but the `capture` helper isn't thread-safe)
+- Add options to do caching at the same time (with the same key)
+- Add options to customize the generated temporary element (could be used for loading indication or to avoid CSS conflict)
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile ADDED

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/render-later/*_test.rb']
+end
+task :default => :test

data/app/helpers/render_later/view_helper.rb ADDED

@@ -0,0 +1,44 @@
+module RenderLater
+  module ViewHelper
+    INSERT_FUNCTION = <<-JAVASCRIPT.freeze
+      function rl_insert(name, data) {
+        if (node = document.getElementById(name)) {
+          var div = document.createElement('div');
+          div.innerHTML = data;
+          var elements = div.childNodes;
+          for (var i = elements.length; i > 0; i--) {
+            node.parentNode.insertBefore(elements[0], node);
+          }
+          node.parentNode.removeChild(node);
+        }
+      };
+    JAVASCRIPT
+    def render_later key, &block
+      store_object(key, &block)
+      content_tag(:span, nil, id: "rl-#{key}", class: "rl-placeholder", style: 'display: none')
+    end
+    def render_now
+      return nil if deferred_objects.empty?
+      concat content_tag('script', raw(INSERT_FUNCTION))
+      deferred_objects.each do |key, block|
+        concat content_tag('script', raw("rl_insert('rl-#{key}', '#{j capture(&block)}');\n"))
+      end
+      nil
+    end
+    private
+    def store_object key, &block
+      objects = deferred_objects
+      raise Error, "duplicate key: #{key}" if objects.has_key?(key)
+      objects[key] = block
+      request.instance_variable_set(:@deferred_objects, objects)
+    end
+    def deferred_objects
+      request.instance_variable_get(:@deferred_objects) || {}
+    end
+  end
+end

data/lib/render-later.rb ADDED

@@ -0,0 +1,6 @@
+require "render-later/version"
+require "render-later/engine" if defined?(::Rails)
+module RenderLater
+  class Error < StandardError; end
+end

data/lib/render-later/engine.rb ADDED

@@ -0,0 +1,4 @@
+module RenderLater
+  class Engine < Rails::Engine
+  end
+end

data/lib/render-later/version.rb ADDED

@@ -0,0 +1,3 @@
+module RenderLater
+  VERSION = "0.1.0"
+end

data/render-later.gemspec ADDED

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'render-later/version'
+Gem::Specification.new do |spec|
+  spec.name          = "render-later"
+  spec.version       = RenderLater::VERSION
+  spec.authors       = ["Adrien Jarthon"]
+  spec.email         = ["me@adrienjarthon.com"]
+  spec.summary       = %q{Defer rendering of slow parts to the end of the page}
+  spec.description   = %q{Render-later allows you to defer the rendering of slow parts of your views to the end of the page, allowing you to drastically improve the time to first paint and perceived performance.}
+  spec.homepage      = "https://github.com/jarthod/render-later"
+  spec.license       = "MIT"
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rails", ">= 4.0"
+  spec.add_development_dependency "puma"
+  spec.add_development_dependency "poltergeist"
+end

metadata ADDED

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: render-later
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Adrien Jarthon
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2016-01-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: poltergeist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Render-later allows you to defer the rendering of slow parts of your
+  views to the end of the page, allowing you to drastically improve the time to first
+  paint and perceived performance.
+email:
+- me@adrienjarthon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/helpers/render_later/view_helper.rb
+- lib/render-later.rb
+- lib/render-later/engine.rb
+- lib/render-later/version.rb
+- render-later.gemspec
+homepage: https://github.com/jarthod/render-later
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.5.1
+signing_key:
+specification_version: 4
+summary: Defer rendering of slow parts to the end of the page
+test_files: []