js_application_reloader 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MjE0MWUzNWUzMjEyMjE4N2E5N2U4ODZiZTk5ZTA3Y2FmM2YxMGVlZg==
+  data.tar.gz: !binary |-
+    Yjk3YzUwYjZkMzRiOWU4YzM2NWZhMjU1OTgxMTQ0MjU0MTE4NTk3ZQ==
+SHA512:
+  metadata.gz: !binary |-
+    NWRlNGY3YmQwMmYyMjUzN2JjNWQ0MDhiNTk2NGMwMTZmY2I2NTMzYjdhZDNj
+    MDUwMGM4MTc2NmJmZTE5NWVhZjk2NjAxNzJjZmNhM2FlN2NkMTgwYWFlYmE1
+    ZTM2MDE5MjA0ZGIzZDlmOGIyMzUwYjk0ZDA4ZmY1NjIxYThmMzQ=
+  data.tar.gz: !binary |-
+    ZTgxMDc0MzEwYjc2OTE1OWM2YzMxMDk1NGIxMmE4NjVkZTdjN2MyNWY4OGI4
+    NjgyZWQwYmI1MjhiZjhlYzc0MmY4YWI4NDFiOWMxOTUyMmQ0MzQ4OWZmMDRj
+    ODQxMjhmMjM2YTUwM2E5MzI2YTRkZjNlZWFiNGNiNTQ5OWFiODU=

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Clavis Insight
+
+MIT License
+
+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,220 @@
+# JsApplicationReloader
+
+# tl;dr
+Timestamps on your JS, CSS and other assets get bumped to ensure that your
+Javascript application is always running against the latest front-end code
+exposed by the server. But what happens if the user doesn't browse off your
+Single Page Application...
+
+# Goal
+JsApplicationReloader is a gem for enabling you to force the reload of a Single
+Page Applications Javascript (SPA) in production. It is useful for Rails
+applications which write an initial fragment of JSON into the Javascript to
+configure the application. Traditionally it has been hard to expire this part of
+the application's JS, along with the timestamps used in asset URLs such as
+Javascript and CSS includes.
+
+# How does it work?
+
+Every time the rails server is restarted, a token (usually a timestamp) is
+recorded on the server. This token is also written into the JSON fragment that
+is rendered when the SPA is first loaded. Subsequent AJAX requests from the
+front end send this token as an application specific header, which is compared
+with the token recorded on the server. If these don't match it means the
+server's Javascript has changed. This tells the server to send a token expired
+header back to the client, along with some HTML. The client detects the token
+expired header and displays the HTML to the user. This HTML contains a link
+that the user can user to refresh the application. Simples!
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'js_application_reloader'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install js_application_reloader
+
+## Usage
+
+After you install JsApplicationReloader and add it to your Gemfile, you need to
+run the generator:
+
+    $ rails generate js_application_reloader:install
+
+This will generate a file under
+config/initializers/js_application_reloader.rb which you can customise.
+
+Now is a good time to go and read that file for further details.
+
+Then in your ApplicationController include the following line
+
+    include JsApplicationReloader::ControllerExtensions
+
+... this will add a before filter to your controllers which checks
+whether the token is stale. It is recommended to put this line just
+after any authentication/authorisation before filters.
+
+In your app/views/layouts/application.html.erb file (or equivalent) include the
+line
+
+    <%=raw JsApplicationReloader::inject_script %>
+
+This will include the token and some Javascript code on your page.
+
+Optionally you can use JsApplicationReloader to manage the expiration of
+your stylesheet and javascript includes, eg.
+
+    <%= stylesheet_link_tag "/dist/stylesheets/application.css?version=#{JsApplicationReloader.token}" %>
+    <%= javascript_include_tag "/dist/javascriptions/main.css?version=#{JsApplicationReloader.token}" %>
+
+**Note: If you choose to use JsApplicationReloader to manage the expiration
+of your stylesheet and javascript includes, then ensure you include the
+```<%=raw JsApplicationReloader::inject_script %>``` line before the stylesheet
+and JS includes.**
+
+## Basic configuration for simple jQuery projects (ie. synchronous Javascript)
+
+You need to manually call the token expiration code in your callbacks, eg.
+
+      $.get(url, function(data, status, xhr) {
+        // You need to add these 3 lines
+        if (JsApplicationReloader.isTokenExpired(xhr)) {
+          return JsApplicationReloader.handleTokenExpiration(xhr);
+        }
+        // your normal callback handler code goes here...
+      });
+
+
+## Basic configuration for AMD/RequireJS projects (ie. asynchronous Javascript)
+
+This requires 3 steps.
+
+1) In config/initializers/js_application_reloader.rb you need to set
+```config.async_js_project = true```.
+
+2) Configure application requests. You need to manually add some ajaxSend()
+configuration to your application's JS codebase. Where you add this code depends
+on what front-end MVC framework you are using, if any.
+
+In BackboneJS you would insert this into the application's startup code, for example in application.js file. The only requirement is that Backbone is initialised.
+
+
+    // -- Wireup AJAX send calls --
+    $(document).ready(function() {
+        $(document).ajaxSend(function(event, request) {
+            if (JsApplicationReloader && JsApplicationReloader.token) {
+                request.setRequestHeader(JsApplicationReloader.tokenHeaderName, JsApplicationReloader.token);
+           }
+        });
+    });
+
+3) Configure application response handling. Again this depends on what front-end
+MVC framework you are using.
+
+In BackboneJS you would insert this into the application's startup code, for example in application.js file. The only requirement is that Backbone is initialised.
+
+    // -- Override Backbone sync() to handle expiration
+    // -- Do the equivalent for your chosen framework
+    var oldSyncMethod = Backbone.sync;
+    Backbone.sync = function(method, model, options) {
+        var oldError = options.error;
+        options.error = function(xhr, textStatus, errorThrown) {
+            // These are the important 3 lines
+            if (JsApplicationReloader.isTokenExpired(xhr)) {
+                return JsApplicationReloader.handleTokenExpiration(xhr);
+            }
+            if (oldError) { oldError(xhr, textStatus, errorThrown); }
+        };
+        return oldSyncMethod(method, model, options);
+    };
+
+**What about AJAX requests where I bypass the front-end MVC framework (eg. plain old jQuery AJAX requests)?**
+
+As these don't go through the MVC framework's machinary you need to manually
+call the token expiration code in your request callbacks. This has to be done
+everywhere that you skip going through your MVC framework. eg.
+
+      $.get(url, function(data, status, xhr) {
+        // You need to add these 3 lines
+        if (JsApplicationReloader.isTokenExpired(xhr)) {
+          return JsApplicationReloader.handleTokenExpiration(xhr);
+        }
+        // your normal callback handler code goes here...
+      });
+
+# How do I know it worked?
+Assuming that you are using the default strategy of reloading your application
+when the server is restarted (ie. ```config.token = Time.now.to_i```)
+then the following steps with verify it's working.
+
+1. Start your server
+2. Browse to a page that makes an AJAX request
+3. Optional - if you inspect the request headers (eg. in Chrome's Network tab) you
+   should see a header that looks like "X-Js-Application-Reloader-Current-Token".
+   If not, then something went wrong when installing or configuring.
+4. Stay on the same page in your Single Page Application
+5. Restart the server and wait for it to be fully up and running
+6. Without reloading the page, carry out an action that causing another AJAX
+   request
+7. If everything is working you should see "A new version of this application is
+   available. Please click here to load it."
+
+# Customising
+In addition to the config/initializers/js_application_reloader.rb settings you
+can also carry out the following customisations.
+
+## Disable JsApplicationReloader for certain controllers
+You can skip the before filter that JsApplicationReloader uses via
+
+    skip_before_filter :handle_js_application_reloader_token_expiration
+
+## Override what the server sends back to the client on token expiration
+
+    # Override this in your ApplicationController or on a per controller basis.
+    # The reload_required_http_status, application_name, redirect_url attributes
+    # are available to you on the JsApplicationReloader object.
+    def render_js_application_reloader_expiration
+      render :text => "A new version of #{JsApplicationReloader.application_name} is available. Please click <a href='#{JsApplicationReloader.redirect_url}'>here</a> to load it.", :status => JsApplicationReloader.reload_required_http_status
+    end
+
+## Override how the client handles the reloading of the application
+You can put this at the bottom of your
+config/initializers/js_application_reloader.rb (outside of the 'config' block).
+
+    def JsApplicationReloader.handle_reloader_token_expiration_on_client
+      <<-EOF
+          JsApplicationReloader.handleTokenExpiration = function(xhr) {
+            // $('body').html(xhr.responseText); // Original code
+            alert(xhr.responseText); // We change it to this
+            return false;
+          };
+      EOF
+    end
+
+## Future
+There's lots to improve
+* Usability: currently you are required to add a lot of code explicitly to your
+  application. It would be good if this could be avoided. For example, instead
+  of wiring up ajaxSend() calls perhaps we could do something with the
+  XMLHttpRequest object (thanks for the idea Stefan!)
+* Flexibility: cater for non-Rails applications and other JS frameworks
+* Tests: this gem has been tested manually; it needs some spec love
+
+So please fork and send a Pull Request.
+
+## Contributing
+
+1. Fork it ( https://github.com/theirishpenguin/js_application_reloader/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/js_application_reloader.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'js_application_reloader/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "js_application_reloader"
+  spec.version       = JsApplicationReloader::VERSION
+  spec.authors       = ["Declan McGrath"]
+  spec.email         = ["declan.mcgrath@clavisinsight.com"]
+  spec.summary       = %q{Force a full reload of your Single Page Application when a new version of it is available}
+  spec.description   = %q{Force a full reload of your Single Page Application when a new version of it is available}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/generators/js_application_reloader/install_generator.rb

@@ -0,0 +1,15 @@
+module JsApplicationReloader
+  class InstallGenerator < Rails::Generators::Base
+
+    TEMPLATE_FILENAME = 'js_application_reloader.rb'
+    DESTINATION_FILEPATH = 'config/initializers/js_application_reloader.rb'
+
+    desc "This generator creates an initializer file at #{DESTINATION_FILEPATH}"
+
+    source_root File.expand_path("../../templates", __FILE__)
+
+    def copy_initializer
+      copy_file TEMPLATE_FILENAME, DESTINATION_FILEPATH
+    end
+  end
+end

data/lib/generators/templates/js_application_reloader.rb

@@ -0,0 +1,31 @@
+JsApplicationReloader.configure do |config|
+
+  # Leave async_js_project is false for projects that don't asynchronously load their Javascript
+  # Set it to true if you use libraries such as RequireJS which do load asynchronously
+  config.async_js_project = false
+
+  # Here we determine the value of the token, which is set every time the Rails server is (re)started.
+  # A change in value of this token indicates that the application needs to be reloaded.
+  #
+  # Examples
+  # * Time.now.to_i - The JS will be reloaded every time the Rails server is restarted
+  # * File.stat("./dist").mtime.to_i - The JS will be reloaded every time the Rails
+  #   server is restarted AND the modified time of the public/dist directory is updated
+  config.token = Time.now.to_i # eg. File.stat("./public/dist").mtime.to_i
+
+  # Name of the header that holds the current value of the token sent from the client to the server
+  config.token_header_name = "X-Js-Application-Reloader-Current-Token"
+
+  # The http status code that the server sends back to the client with when a reload is required
+  config.reload_required_http_status = 200;
+
+  # Name of the header that the server sends back to the client with the response which indicates if a reload is required
+  config.status_header_name = "X-Js-Application-Reloader-Status"
+
+  # Let's you customize the expiration message with your application name
+  config.application_name = 'this application'
+
+  # Let's you customize the expiration message with a link to go to in order to reload the front end of the application
+  config.redirect_url = '/users/sign_in'
+
+end

data/lib/js_application_reloader/controller_extensions.rb

@@ -0,0 +1,23 @@
+module JsApplicationReloader
+  module ControllerExtensions
+
+    def self.included(base)
+      base.before_filter :handle_js_application_reloader_token_expiration
+    end
+
+    def handle_js_application_reloader_token_expiration
+      # Note: we do a string comparision to avoid 232323 not matching "232323" mistakes
+      if request.headers[JsApplicationReloader.token_header_name] && (request.headers[JsApplicationReloader.token_header_name].to_s != JsApplicationReloader.token.to_s)
+        response.headers[JsApplicationReloader.status_header_name] = 'token_expired'
+        render_js_application_reloader_expiration
+      end
+    end
+
+    # override me in your ApplicationController to customize what gets
+    # sent back to the client on token expiration
+    def render_js_application_reloader_expiration
+        render :text => "A new version of #{JsApplicationReloader.application_name} is available. Please click <a href='#{JsApplicationReloader.redirect_url}'>here</a> to load it.", :status => JsApplicationReloader.reload_required_http_status
+    end
+
+  end
+end

data/lib/js_application_reloader/version.rb

@@ -0,0 +1,3 @@
+module JsApplicationReloader
+  VERSION = "0.0.1"
+end

data/lib/js_application_reloader.rb

@@ -0,0 +1,79 @@
+require "js_application_reloader/version"
+require "js_application_reloader/controller_extensions"
+
+module JsApplicationReloader
+
+  # Can override these via their setters in config/initializers/js_application_reloader.rb
+  @async_js_project = false
+  @token = nil
+  @token_header_name = "X-Js-Application-Reloader-Current-Token"
+  @status_header_name = "X-Js-Application-Reloader-Status"
+  @reload_required_http_status = 200
+  @application_name = 'this application'
+  @redirect_url = '/users/sign_in'
+
+  class << self
+    attr_accessor :async_js_project
+    attr_accessor :token
+    attr_accessor :token_header_name
+    attr_accessor :status_header_name
+    attr_accessor :reload_required_http_status
+    attr_accessor :application_name
+    attr_accessor :redirect_url
+  end
+
+  # Nice configuration is a small twist on http://robots.thoughtbot.com/mygem-configure-block. Thanks!
+
+  def self.configure
+    yield(self)
+  end
+
+  # Must be injected into ERB template using raw
+  # TODO: Option to limit fields sent to the client for lightness
+  def self.inject_script
+    <<-EOF
+      <script type="text/javascript">
+        JsApplicationReloader = {
+          token: '#{JsApplicationReloader.token}',
+          tokenHeaderName: '#{JsApplicationReloader.token_header_name}',
+          statusHeaderName: '#{JsApplicationReloader.status_header_name}',
+          reloadRequiredHttpStatus: '#{JsApplicationReloader.reload_required_http_status}',
+          applicationName: '#{JsApplicationReloader.application_name}',
+          redirectUrl: '#{JsApplicationReloader.redirect_url}'
+        };
+
+        // -- Define Expiration check
+        JsApplicationReloader.isTokenExpired = function(xhr) {
+          return (xhr.status == JsApplicationReloader.reloadRequiredHttpStatus && (xhr.getResponseHeader(JsApplicationReloader.statusHeaderName) === 'token_expired'));
+        };
+
+        #{handle_reloader_token_expiration_on_client}
+
+        #{JsApplicationReloader.non_async_js_request_script unless JsApplicationReloader.async_js_project}
+      </script>
+    EOF
+  end
+
+  # Expiration handler (you can customize this)
+  def self.handle_reloader_token_expiration_on_client
+    <<-EOF
+        JsApplicationReloader.handleTokenExpiration = function(xhr) {
+          $('body').html(xhr.responseText); // Display the HTML returned by xhr.responseText as you see fit
+          return false;
+        };
+    EOF
+  end
+
+  # For non-async Javascript projects
+  def self.non_async_js_request_script
+    <<-EOF
+      $(document).ready(function() {
+          $(document).ajaxSend(function(event, request) {
+              if (JsApplicationReloader && JsApplicationReloader.token) {
+                  request.setRequestHeader('#{JsApplicationReloader.token_header_name}', JsApplicationReloader.token);
+             }
+          });
+      });
+    EOF
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: js_application_reloader
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Declan McGrath
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !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'
+description: Force a full reload of your Single Page Application when a new version
+  of it is available
+email:
+- declan.mcgrath@clavisinsight.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- js_application_reloader.gemspec
+- lib/generators/js_application_reloader/install_generator.rb
+- lib/generators/templates/js_application_reloader.rb
+- lib/js_application_reloader.rb
+- lib/js_application_reloader/controller_extensions.rb
+- lib/js_application_reloader/version.rb
+homepage: ''
+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.4.5
+signing_key: 
+specification_version: 4
+summary: Force a full reload of your Single Page Application when a new version of
+  it is available
+test_files: []