pagelet_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7868690d26811fd0be59cc8e007923e113a32a43
+  data.tar.gz: 205efc19edefe7b723e6c48cb1818e3cd94dc127
+SHA512:
+  metadata.gz: 0ea8943752cd56f0d4b0eea71d1750b7524b1327cd5451b9e40a2140ccea980b7d4dff27532d37a5e123c2461bcc4080f2663759f3d468a3d17af2cb13db16e5
+  data.tar.gz: e3a2532c559637364cff3a0bb1fbc6b1696b8fb53590ed9fa27792b38bf2ab4044abdab25e228b6c00746e4ccf5a4e99538692ee75e3109e7183aaf397fd1607

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Anton Katunin
+
+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

@@ -0,0 +1,402 @@
+# PageletRails
+
+[Demo](https://polar-river-18908.herokuapp.com)
+
+## Why?
+
+* Do you have pages with a lot of information? 
+* The pages where you need to get data from 5 or 10 different sources?
+* What if one of them is slow?
+* Does this mean your users have to wait?
+
+Don't make your users wait for page to load.
+ 
+## Example
+ 
+![](https://camo.githubusercontent.com/50f4078cc4015e3df89afc753a5ff79828ac0e8e/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f662e636c2e6c792f6974656d732f303031323133314d324b3147335831483276314f2f313433303033383036373738372e6a7067)
+
+For example let's take facebook user home page. It has A LOT of data, but it loads very quickly. How? The answer is [perceived performance](https://en.wikipedia.org/wiki/Perceived_performance). It's not about in how many milliseconds you can serve request, but how fast it **feels** to the user. 
+
+The page body is served instantly and all the data is loaded after. Even for facebook it takes multiple seconds to fully load the page. But it feels instant, that it's all about.
+
+## Who is doing that?
+
+Originally I saw such solution implemented at Facebook and Linkedin. Each page consists of small blocks, where each is responsible for it's own functionality and does not depend on the page where it's included. You can read more on that below.
+
+* [BigPipe: Pipelining web pages for high performance](https://www.facebook.com/notes/facebook-engineering/bigpipe-pipelining-web-pages-for-high-performance/389414033919/)
+* [Engineering the New LinkedIn Profile](https://engineering.linkedin.com/profile/engineering-new-linkedin-profile)
+* [Play Framework & SF Scala: Jim Brikman, Composable Applications in Play, 7/23/14](https://www.youtube.com/watch?v=4b1XLka0UIw)
+
+## What is Pagelet?
+
+You can break a web page into number of sections, where each one is responsible for its own functionality. Pagelet is the name for each section. It is a part of the page which has it's own route, controller and view. 
+
+The closest alternative in ruby is [cells gem](https://github.com/apotonick/cells). After using it for long time I've faced many limitations of its approach. Cells has a custom Rails-like syntax but not quite. That is frustrating as you have to learn and remember those differences. The second issue, and the biggest, cells are internal only and not designed to be routable. This stops many great possibilities for improving perceived performance, as request has to wait for all cells to render.  
+ 
+Pagelet_rails is built on top of Rails and uses it as much as possible. The main philosophy: **Do not reinvent the wheel, build on shoulders of giants.**
+ 
+
+# Usage
+
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pagelet_rails'
+```
+
+Or install it yourself as:
+```bash
+$ gem install pagelet_rails
+```
+
+## Structure
+
+```
+app
+├── pagelets
+│   ├── current_time
+│   │   ├── current_time_controller.rb
+│   │   ├── views
+│   │   │   ├── show.erb
+```
+
+## Example
+
+```ruby
+# app/pagelets/current_time/current_time_controller.rb
+class CurrentTime::CurrentTimeController < ApplicationController
+  include PageletRails::Concerns::Controller  
+  
+  # add pagelets_current_time_path route
+  # which gives "/pagelets/current_time" url route
+  pagelet_resource only: [:show] 
+
+  def show
+  end
+end
+``` 
+
+
+```erb
+<!-- Please note view path -->
+<!-- app/pagelets/current_time/views/show.erb -->
+<div class="panel-heading">Current time</div>
+
+<div class="panel-body">
+  <p><%= Time.now %></p>
+  <p>
+    <%= link_to 'Refresh', pagelets_current_time_path, remote: true %>
+  </p>
+</div>
+```
+
+And now use it anywhere in your view
+
+```erb
+<!-- app/views/dashboard/show.erb -->
+<%= pagelet :pagelets_current_time %>
+```
+ 
+## Pagelet view helper
+
+`pagelet` helper allows you to render pagelets in views. Name of pagelet is its path. 
+
+For example pagelet with route `pagelets_current_time_path` will have `pagelets_current_time` name.
+
+### remote
+
+Example
+```erb
+<%= pagelet :pagelets_current_time, remote: true %>
+```
+
+Options for `remote`:
+* `true`, `:ajax` - always render pagelet through ajax
+* `:turbolinks`  - same as `:ajax` but inline for turbolinks page visit
+* `false` or missing - render inline
+* `:stream` - (aka BigPipe) render placeholder and render full version at the end of html. See streaming for more info.
+
+### params
+
+Example
+```erb
+<%= pagelet :pagelets_current_time, params: { id: 123 } %>
+```
+
+`params` are the parameters to pass to pagelet path. Same as `pagelets_current_time_path(id: 123)`
+
+### html
+
+```erb
+<%= pagelet :pagelets_current_time, html: { class: 'panel' } %>
+```
+
+You can specify html attributes to pagelet with `html` option
+
+### placeholder
+
+```erb
+<%= pagelet :pagelets_current_time, placeholder: { text: 'Loading...', height: 300 } %>
+```
+
+Configuration for placeholder before pagelet is loaded.
+
+
+### other
+
+You can pass any other data and it will be available in `pagelet_options`
+
+```erb
+<%= pagelet :pagelets_current_time, title: 'Hello' %>
+```
+
+```ruby
+# ...
+  def show
+    @title = pagelet_options.title
+  end
+#...
+```
+
+
+## Pagelet options
+
+`pagelet_options` is similar to `params` object, but for private data and config. Options can be global for all actions or specific actions only.
+
+```ruby
+class CurrentTime::CurrentTimeController < ::ApplicationController
+  include PageletRails::Concerns::Controller
+  
+  # Set default option for all actions
+  pagelet_options remote: true 
+  
+  # set option for :show and :edit actions only
+  pagelet_options :show, :edit, remote: :turbolinks 
+  
+  def show
+  end
+  
+  def new
+  end
+  
+  def edit
+  end
+  
+end
+```
+
+```erb
+<%= pagelet :new_pagelets_current_time %><!-- defaults to remote: true -->
+<%= pagelet :pagelets_current_time %> <!-- defaults to remote: turbolinks -->
+
+<%= pagelet :pagelets_current_time, remote: false %> <!-- force remote: false -->
+```
+
+## Inline routes
+
+Because pagelets are small you will have many of them. In order to keep them under control pagelet_rails provides helpers. 
+
+You can inline routes inside you controller.
+
+```ruby
+class CurrentTime::CurrentTimeController < ::ApplicationController
+  include PageletRails::Concerns::Controller
+  
+  pagelet_resource only: [:show]
+  # same as in config/routes.rb:
+  #
+  # resource :current_time, only: [:show]
+  #
+  
+  pagelet_resources
+  # same as in config/routes.rb:
+  #
+  # resources :current_time
+  #
+    
+  pagelet_routes do
+    # this is the same context as in config/routes.rb:
+    get 'show_me_time' => 'current_time/current_time#show'
+  end
+  
+end
+```
+
+## Pagelet cache
+
+Cache of pagelet rails is built on top of [actionpack-action_caching gem](https://github.com/rails/actionpack-action_caching). 
+
+Simple example
+
+```ruby
+# app/pagelets/current_time/current_time_controller.rb
+class CurrentTime::CurrentTimeController < ::ApplicationController
+  include PageletRails::Concerns::Controller
+  
+  pagelet_options expires_in: 10.minutes
+
+  def show
+  end
+
+end
+```
+
+### cache_path
+
+Is a hash of additional parameters for cache key. 
+
+* `Hash` - static hash
+* `Proc` - dynamic params, it must return hash. Eg. `Proc.new { params.permit(:sort_by) }`
+* `Lambda` - same as `Proc` but accepts `controller` as first argument
+* `String` - any custom identifier
+
+### expires_in
+
+Set the cache expiry. For example `expires_in: 1.hour`. 
+
+Warning: if `expires_in` is missing, it will be cached indefinitely.
+
+### cache
+
+This is toggle to enable caching without specifying options. `cache_defaults` options will be used (see below).
+
+If any of `cache_path`, `expires_in` and `cache` is present then cache will be enabled.
+
+
+### cache_defaults
+
+You can set default options for caching.
+
+```ruby
+class PageletController < ::ApplicationController
+  include PageletRails::Concerns::Controller
+
+  pagelet_options cache_defaults: {
+    expires_in: 5.minutes,
+    cache_path: Proc.new {
+      { user_id: current_user.id }
+    }
+  }
+end
+```
+
+In the example above cache will be scoped per `user_id` and for 5 minutes unless it is overwritten in pagelet itself.
+
+
+## Advanced functionality
+
+### Partial update
+
+```erb
+<!-- app/pagelets/current_time/views/show.erb -->
+<div class="panel-heading">Current time</div>
+
+<div class="panel-body">
+  <p><%= Time.now %></p>
+  <p>
+    <%= link_to 'Refresh', pagelets_current_time_path, remote: true %>
+  </p>
+</div>
+```
+Please note `remote: true` option for `link_to`. 
+
+This is default Rails functionality with small addition. If that link is inside pagelet, than controller response will be replaced in that pagelet.
+
+```ruby
+# app/pagelets/current_time/current_time_controller.rb
+class CurrentTime::CurrentTimeController < ::ApplicationController
+  include PageletRails::Concerns::Controller
+  
+  pagelet_resource only: [:show]
+
+  def show
+  end
+
+end
+``` 
+
+This will partially update the page and replace only that pagelet.
+
+
+### Streaming
+
+This is the most efficient way to deliver data with minimum delays. The placeholder will be rendered first and the full version will be delivered at the end of page and replaced with Javascript code. Everything is delivered in the same request.
+
+This mode requires rendering of templates with [streaming mode](http://api.rubyonrails.org/classes/ActionController/Streaming.html) enabled.
+
+```ruby
+  #...
+  def show
+    render :show, stream: true
+  end
+  #...  
+```
+
+In you layout add `pagelet_stream` right before `</body>` tag.
+
+```erb
+<!-- app/views/layouts/application.erb -->
+
+<body>
+<%= yield %>
+
+<% pagelet_stream %>
+</body>
+```
+
+Usage: 
+
+```erb
+<%= pagelet :pagelets_current_time, remote: :stream %>
+```
+
+**Warning!!!** You also should have webserver compatible for streaming like puma, passenger or unicorn (requires special config).
+
+**Warning!!!** you need to have multiple threads/processes configured in the web server. This is required so the page could fetch assets while content is streaming. 
+ 
+Finally if everything is done right you should see significant rendering speed improvements especially on old browsers, slow network or with cold cache. 
+
+
+### Super smart caching
+
+Probably one of the coolest functionality of pagelet_rails is "super smart caching". It allows you to render pagelets through ajax and cache them, but if page is reloaded the pagelet is rendered instantly from cache.
+ 
+ So on the first page load user sees "Loading..." blocks, but after the content is instant.
+
+The best thing, it's enabled by default if pagelet has caching enabled and is rendering through ajax request.
+
+### Ajax Batching
+
+Only relevant for `remote: true` and `remote: :turbolinks` when request is loaded through ajax. Loading each pagelet with a separate request is inefficient if you need to do make many requests. That's why you need to group multiple requests into one. By default all ajax requests are grouped into single request. But you can have full control of it. You can specify how to group requests with `ajax_group` option.
+
+```erb
+<%= pagelet :pagelets_current_time, remote: true, ajax_group: 'main' %>
+<%= pagelet :pagelets_current_time, remote: true, ajax_group: 'leftpanel' %>
+```
+
+There will be one request per group. Missing value is considered a separate group as well.
+
+ 
+## Todo
+
+* package as gem
+* assets support
+* ~~batch request~~
+  * ~~each pagelet makes a separate http call, it's very inefficient for pages with many pagelets. Goal is to group multiple pagelets into single http request.~~ 
+* ~~streaming of components at the end of body~~
+  * ~~goal is to serve the page with placeholders but hold connection and render pagelets in the same request before `</body>` tag~~
+* ~~partial updates~~
+* ~~turbolinks support~~
+* ~~smart caching~~
+* delay load of not visible pagelets (aka. below the fold)
+  * do not load pagelets which are not visible to the user until user scrolls down. For example like Youtube comments.
+* fix streaming with nested layouts (rails bug?)
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,37 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PageletRails'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+load 'rails/tasks/statistics.rake'
+
+
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/assets/javascripts/pagelet_rails/jquery.ajaxprogress.js

@@ -0,0 +1,76 @@
+/*!
+ * jQuery ajaxProgress Plugin v0.5.0
+ * Requires jQuery v1.5.0 or later
+ *
+ * http://www.kpozin.net/ajaxprogress
+ *
+ * (c) 2011, Konstantin Pozin
+ * Licensed under MIT license.
+ */
+(function($) {
+
+  // Test whether onprogress is supported
+  var support = $.support.ajaxProgress = ("onprogress" in $.ajaxSettings.xhr());
+
+  // If it's not supported, we can't do anything
+  if (!support) {
+    return;
+  }
+
+  var NAMESPACE = ".ajaxprogress";
+
+  // Create global "ajaxProgress" event
+  $.fn.ajaxProgress = function (f) {
+    return this.bind("ajaxProgress", f);
+  };
+
+  // Hold on to a reference to the jqXHR object so that we can pass it to the progress callback.
+  // Namespacing the handler with ".ajaxprogress"
+  $("html").bind("ajaxSend" + NAMESPACE, function(event, jqXHR, ajaxOptions) {
+    ajaxOptions.__jqXHR = jqXHR;
+  });
+
+  /**
+   * @param {XMLHttpRequestProgressEvent} evt
+   * @param {Object} options jQuery AJAX options
+   */
+  function handleOnProgress(evt, options) {
+
+    // Trigger the global event.
+    // function handler(jqEvent, progressEvent, jqXHR) {}
+    if (options.global) {
+      $.event.trigger("ajaxProgress", [evt, options.__jqXHR]);
+    }
+
+    // Trigger the local event.
+    // function handler(jqXHR, progressEvent)
+    if (typeof options.progress === "function") {
+      options.progress(options.__jqXHR, evt);
+    }
+  }
+
+
+  // We'll work with the original factory method just in case
+  var makeOriginalXhr = $.ajaxSettings.xhr.bind($.ajaxSettings);
+
+  // Options to be passed into $.ajaxSetup;
+  var newOptions = {};
+
+  // Wrap the XMLHttpRequest factory method
+  newOptions.xhr = function () {
+
+    // Reference to the extended options object
+    var s = this;
+
+    var newXhr = makeOriginalXhr();
+    if (newXhr) {
+      newXhr.addEventListener("progress", function(evt) {
+        handleOnProgress(evt, s);
+      });
+    }
+    return newXhr;
+  };
+
+  $.ajaxSetup(newOptions);
+
+})(jQuery);