upjs-rails 0.12.5 → 0.13.0

data/lib/assets/javascripts/up/syntax.js.coffee

@@ -1,16 +1,34 @@
 ###*
-Custom elements
-===============
-  
+Enhancing elements
+==================
+
 Up.js keeps a persistent Javascript environment during page transitions.
-To prevent memory leaks it is important to cleanly set up and tear down
-event handlers and custom elements.
+If you wire Javascript to run on `ready` or `onload` events, those scripts will
+only run during the initial page load. Subsequently [inserted](/up.replace)
+page fragments will not be compiled.
+
+Let's say your Javascript plugin wants you to call `lightboxify()`
+on links that should open a lightbox. You decide to
+do this for all links with an `lightbox` class:
+
+    <a href="river.png" class="lightbox">River</a>
+    <a href="ocean.png" class="lightbox">Ocean</a>
+
+You should **avoid** doing this on page load:
+
+    $(document).on('ready', function() {
+      $('a.lightbox').lightboxify();
+    });
 
-\#\#\# Incomplete documentation!
+Instead you should register a [`compiler`](/up.compiler) for the `a.lightbox` selector:
 
-We need to work on this page:
+    up.compiler('a.lightbox', function($element) {
+      $element.lightboxify();
+    });
 
-- Better class-level introduction for this module
+The compiler function will be called on matching elements when
+the page loads, or whenever a matching fragment is [updated through Up.js](/up.replace)
+later.
 
 @class up.syntax
 ###
@@ -34,7 +52,8 @@ up.syntax = (($) ->
   the page loads, or whenever a matching fragment is [updated through Up.js](/up.replace)
   later.
 
-  If you have used Angular.js before, this resembles [Angular directives](https://docs.angularjs.org/guide/directive).
+  If you have used Angular.js before, this resembles
+  [Angular directives](https://docs.angularjs.org/guide/directive).
 
 
   \#\#\#\# Integrating jQuery plugins
@@ -42,14 +61,14 @@ up.syntax = (($) ->
   `up.compiler` is a great way to integrate jQuery plugins.
   Let's say your Javascript plugin wants you to call `lightboxify()`
   on links that should open a lightbox. You decide to
-  do this for all links with an `[rel=lightbox]` attribute:
+  do this for all links with an `lightbox` class:
 
-      <a href="river.png" rel="lightbox">River</a>
-      <a href="ocean.png" rel="lightbox">Ocean</a>
+      <a href="river.png" class="lightbox">River</a>
+      <a href="ocean.png" class="lightbox">Ocean</a>
 
   This Javascript will do exactly that:
 
-      up.compiler('a[rel=lightbox]', function($element) {
+      up.compiler('a.lightbox', function($element) {
         $element.lightboxify();
       });
 
@@ -268,17 +287,17 @@ up.syntax = (($) ->
     compilers = u.copy(defaultCompilers)
 
   ###*
-  Sends a notification that the given element has been inserted
-  into the DOM. This causes Up.js to compile the fragment (apply
-  event listeners, etc.).
+  Compiles a page fragment that has been inserted into the DOM
+  without Up.js.
 
   **As long as you manipulate the DOM using Up.js, you will never
   need to call this method.** You only need to use `up.hello` if the
-  DOM is manipulated without Up.js' involvement, e.g. by plugin code that
-  is not aware of Up.js:
+  DOM is manipulated without Up.js' involvement, e.g. by setting
+  the `innerHTML` property or calling jQuery methods like
+  `html`, `insertAfter` or `appendTo`:
 
-      // Add an element with naked jQuery, without going through Upjs:
-      $element = $('<div>...</div>').appendTo(document.body);
+      $element = $('.element');
+      $element.html('<div>...</div>');
       up.hello($element);
 
   This function emits the [`up:fragment:inserted`](/up:fragment:inserted)

data/lib/assets/javascripts/up/util.js.coffee

@@ -25,9 +25,8 @@ up.util = (($) ->
   ajax = (request) ->
     request = copy(request)
     if request.selector
-      request.headers = {
-        "X-Up-Selector": request.selector
-      }
+      request.headers ||= {}
+      request.headers['X-Up-Selector'] = request.selector
     # Delegate to jQuery
     $.ajax(request)
 
@@ -194,14 +193,25 @@ up.util = (($) ->
           arg += " }"
       arg
 
-  createSelectorFromElement = ($element) ->
-    debug("Creating selector from element %o", $element)
-    classes = if classString = $element.attr("class") then classString.split(" ") else []
-    id = $element.attr("id")
-    selector = $element.prop("tagName").toLowerCase()
-    selector += "#" + id  if id
-    for klass in classes
-      selector += "." + klass
+  createSelectorFromElement = (element) ->
+    $element = $(element)
+    selector = undefined
+
+    debug("Creating selector from element %o", $element.get(0))
+
+    if upId = presence($element.attr("up-id"))
+      selector = "[up-id='#{upId}']"
+    else if id = presence($element.attr("id"))
+      selector = "##{id}"
+    else if name = presence($element.attr("name"))
+      selector = "[name='#{name}']"
+    else if classString = presence($element.attr("class"))
+      classes = classString.split(' ')
+      selector = ''
+      for klass in classes
+        selector += ".#{klass}"
+    else
+      selector = $element.prop('tagName').toLowerCase()
     selector
 
   # jQuery's implementation of $(...) cannot create elements that have
@@ -638,7 +648,10 @@ up.util = (($) ->
     
   locationFromXhr = (xhr) ->
     xhr.getResponseHeader('X-Up-Location')
-    
+
+  titleFromXhr = (xhr) ->
+    xhr.getResponseHeader('X-Up-Title')
+
   methodFromXhr = (xhr) ->
     xhr.getResponseHeader('X-Up-Method')
     
@@ -758,6 +771,9 @@ up.util = (($) ->
     will be discarded.
   @param {String} [config.log]
     A prefix for log entries printed by this cache object.
+  @param {Function<Object>} [config.key]
+    A function that takes an argument and returns a `String` key
+    for storage. If omitted, `toString()` is called on the argument.
   ###
   cache = (config = {}) ->
 
@@ -978,6 +994,7 @@ up.util = (($) ->
 #  castsToFalse: castsToFalse
   castedAttr: castedAttr
   locationFromXhr: locationFromXhr
+  titleFromXhr: titleFromXhr
   methodFromXhr: methodFromXhr
   clientSize: clientSize
   only: only

data/lib/assets/javascripts/up-bootstrap/form-ext.js.coffee

@@ -0,0 +1 @@
+up.form.config.validateTargets.unshift('.form-group:has(&)')

data/lib/upjs/rails/engine.rb

@@ -1,6 +1,6 @@
 module Upjs
   module Rails
-    class Engine < ::Rails::Engine
+    class Engine < ::Rails::Engine # :nodoc:
     end
   end
 end

data/lib/upjs/rails/inspector.rb

@@ -0,0 +1,63 @@
+module Upjs
+  module Rails
+    ##
+    # This object allows the server to inspect the current request
+    # for Up.js-related concerns such as "is this a page fragment update?".
+    #
+    # Available through the `#up` method in all controllers, helpers and views.
+    class Inspector
+
+      def initialize(controller)
+        @controller = controller
+      end
+
+      ##
+      # Returns whether the current request is an
+      # [page fragment update](http://upjs.io/up.replace) triggered by an
+      # Up.js frontend.
+      def up?
+        selector.present?
+      end
+
+      ##
+      # If the current request is a [fragment update](http://upjs.io/up.replace),
+      # this returns the CSS selector of the page fragment that should be updated.
+      #
+      # The Up.js frontend will expect an HTML response containing an element
+      # that matches this selector. If no such element is found, an error is shown
+      # to the user.
+      #
+      # Server-side code is free to optimize its response by only returning HTML
+      # that matches this selector.
+      def selector
+        request.headers['X-Up-Selector']
+      end
+
+      ##
+      # Returns whether the current form submission should be
+      # [validated](http://upjs.io/up-validate) (and not be saved to the database).
+      def validate?
+        validate_name.present?
+      end
+
+      ###
+      # If the current form submission is a [validation](http://upjs.io/up-validate),
+      # this returns the name attribute of the form field that has triggered
+      # the validation.
+      def validate_name
+        request.headers['X-Up-Validate']
+      end
+
+      private
+
+      def request
+        @controller.request
+      end
+
+      def params
+        @controller.params
+      end
+
+    end
+  end
+end

data/lib/upjs/rails/inspector_accessor.rb

@@ -0,0 +1,28 @@
+module Upjs
+  module Rails
+    ##
+    # This adds two methods `#up` and `#up?` to all controllers,
+    # helpers and views, allowing the server to inspect the current request
+    # for Up.js-related concerns such as "is this a page fragment update?".
+    module InspectorAccessor
+
+      def self.included(base) # :nodoc:
+        base.helper_method :up, :up?
+      end
+
+      def up
+        @up_inspector ||= Inspector.new(self)
+      end
+
+      ##
+      # :method: up?
+      # Returns whether the current request is an
+      # [page fragment update](http://upjs.io/up.replace) triggered by an
+      # Up.js frontend.
+      delegate :up?, :to => :up
+
+      ActionController::Base.send(:include, self)
+
+    end
+  end
+end

data/lib/upjs/rails/request_echo_headers.rb

@@ -1,5 +1,12 @@
 module Upjs
   module Rails
+    ##
+    # Installs a before_filter into all controllers which echoes the
+    # request's URL as a response header `X-Up-Location` and the request's
+    # HTTP method as `X-Up-Method`.
+    #
+    # The Up.js frontend requires these headers to detect redirects,
+    # which are otherwise undetectable for an AJAX client.
     module RequestEchoHeaders
 
       def self.included(base)

data/lib/upjs/rails/request_method_cookie.rb

@@ -1,13 +1,21 @@
-# See
-# https://github.com/rails/turbolinks/search?q=request_method&ref=cmdform
-# https://github.com/rails/turbolinks/blob/83d4b3d2c52a681f07900c28adb28bc8da604733/README.md#initialization
+##
+# Installs a before_filter into all controllers which echoes the
+# request's method as a cookie named `_up_request_method`.
+#
+# The Up.js requires this cookie to detect whether the initial page
+# load was requested using a non-GET method. In this case the Up.js
+# framework will prevent itself from booting until it was loaded
+# from a GET request. For the terrible reasons behind this see:
+
+# - <https://github.com/rails/turbolinks/search?q=request_method&ref=cmdform>
+# - <https://github.com/rails/turbolinks/blob/83d4b3d2c52a681f07900c28adb28bc8da604733/README.md#initialization>
 module Upjs
   module Rails
     module RequestMethod
 
       COOKIE_NAME = '_up_request_method'
 
-      def self.included(base)
+      def self.included(base) # :nodoc:
         base.before_filter :set_up_request_method_cookie
       end
 

data/lib/upjs/rails/version.rb

@@ -1,5 +1,9 @@
 module Upjs
   module Rails
-    VERSION = '0.12.5'
+    ##
+    # The current version of the upjs-rails gem.
+    # This version number is also used for releases of the Up.js
+    # frontend code.
+    VERSION = '0.13.0'
   end
 end

data/lib/upjs-rails.rb

@@ -1,5 +1,7 @@
-require "upjs/rails/version"
-require "upjs/rails/engine"
-require "upjs/rails/request_echo_headers"
-require "upjs/rails/request_method_cookie"
-require "upjs/rails/request_ext"
+require 'upjs/rails/version'
+require 'upjs/rails/engine'
+require 'upjs/rails/request_echo_headers'
+require 'upjs/rails/request_method_cookie'
+require 'upjs/rails/inspector'
+require 'upjs/rails/inspector_accessor'
+

data/spec_app/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--color

data/spec_app/Gemfile

@@ -16,9 +16,6 @@ group :development, :test do
   gem 'byebug'
   gem 'web-console', '~> 2.0'
   gem 'jasmine-rails'
-  # gem 'rails-assets-jasmine-jquery'
-  # gem 'rails-assets-jasmine-fixture'
-  # gem 'rails-assets-jasmine-ajax'
 end
 
 group :test do

data/spec_app/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    upjs-rails (0.12.1)
+    upjs-rails (0.13.0)
       rails (>= 3)
 
 GEM
@@ -42,7 +42,7 @@ GEM
       minitest (~> 5.1)
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    arel (6.0.0)
+    arel (6.0.3)
     binding_of_caller (0.7.2)
       debug_inspector (>= 0.0.1)
     bower-rails (0.9.2)
@@ -67,6 +67,7 @@ GEM
       execjs
     coffee-script-source (1.8.0)
     columnize (0.9.0)
+    concurrent-ruby (1.0.0)
     cucumber (1.3.16)
       builder (>= 2.1.2)
       diff-lcs (>= 1.1.3)
@@ -87,7 +88,7 @@ GEM
     ffi (1.9.5)
     gherkin (2.12.2)
       multi_json (~> 1.3)
-    globalid (0.3.0)
+    globalid (0.3.6)
       activesupport (>= 4.1.0)
     haml (4.1.0.beta.1)
       tilt
@@ -97,7 +98,6 @@ GEM
       haml (>= 3.1, < 5.0)
       html2haml (>= 1.0.1)
       railties (>= 4.0.1)
-    hike (1.2.3)
     hpricot (0.8.6)
     html2haml (1.0.1)
       erubis (~> 2.7.0)
@@ -115,21 +115,21 @@ GEM
       rails-dom-testing (~> 1.0)
       railties (>= 4.2.0)
       thor (>= 0.14, < 2.0)
-    json (1.8.2)
+    json (1.8.3)
     libv8 (3.16.14.3)
-    loofah (2.0.1)
+    loofah (2.0.3)
       nokogiri (>= 1.5.9)
     mail (2.6.3)
       mime-types (>= 1.16, < 3)
-    mime-types (2.4.3)
-    mini_portile (0.6.2)
-    minitest (5.5.1)
-    multi_json (1.10.1)
+    mime-types (2.99)
+    mini_portile2 (2.0.0)
+    minitest (5.8.3)
+    multi_json (1.11.2)
     multi_test (0.1.1)
-    nokogiri (1.6.6.2)
-      mini_portile (~> 0.6.0)
+    nokogiri (1.6.7.1)
+      mini_portile2 (~> 2.0.0.rc2)
     phantomjs (1.9.8.0)
-    rack (1.6.0)
+    rack (1.6.4)
     rack-test (0.6.3)
       rack (>= 1.0)
     rails (4.2.0)
@@ -145,11 +145,11 @@ GEM
       sprockets-rails
     rails-deprecated_sanitizer (1.0.3)
       activesupport (>= 4.2.0.alpha)
-    rails-dom-testing (1.0.5)
+    rails-dom-testing (1.0.7)
       activesupport (>= 4.2.0.beta, < 5.0)
       nokogiri (~> 1.6.0)
       rails-deprecated_sanitizer (>= 1.0.1)
-    rails-html-sanitizer (1.0.1)
+    rails-html-sanitizer (1.0.2)
       loofah (~> 2.0)
     railties (4.2.0)
       actionpack (= 4.2.0)
@@ -158,32 +158,33 @@ GEM
       thor (>= 0.18.1, < 2.0)
     rake (10.4.2)
     ref (1.0.5)
-    rspec-core (3.0.4)
-      rspec-support (~> 3.0.0)
-    rspec-expectations (3.0.4)
+    rspec-core (3.4.1)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.0.0)
-    rspec-mocks (3.0.4)
-      rspec-support (~> 3.0.0)
-    rspec-rails (3.0.2)
-      actionpack (>= 3.0)
-      activesupport (>= 3.0)
-      railties (>= 3.0)
-      rspec-core (~> 3.0.0)
-      rspec-expectations (~> 3.0.0)
-      rspec-mocks (~> 3.0.0)
-      rspec-support (~> 3.0.0)
-    rspec-support (3.0.4)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-rails (3.4.0)
+      actionpack (>= 3.0, < 4.3)
+      activesupport (>= 3.0, < 4.3)
+      railties (>= 3.0, < 4.3)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
     ruby_parser (3.1.3)
       sexp_processor (~> 4.1)
     rubyzip (1.1.6)
-    sass (3.4.9)
-    sass-rails (5.0.0)
+    sass (3.4.20)
+    sass-rails (5.0.4)
       railties (>= 4.0.0, < 5.0)
       sass (~> 3.1)
       sprockets (>= 2.8, < 4.0)
       sprockets-rails (>= 2.0, < 4.0)
-      tilt (~> 1.1)
+      tilt (>= 1.1, < 3)
     selenium-webdriver (2.42.0)
       childprocess (>= 0.5.0)
       multi_json (~> 1.0)
@@ -195,22 +196,20 @@ GEM
       capybara
       cucumber
       cucumber-rails
-    sprockets (2.12.3)
-      hike (~> 1.2)
-      multi_json (~> 1.0)
-      rack (~> 1.0)
-      tilt (~> 1.1, != 1.3.0)
-    sprockets-rails (2.2.4)
-      actionpack (>= 3.0)
-      activesupport (>= 3.0)
-      sprockets (>= 2.8, < 4.0)
+    sprockets (3.5.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.0.0)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
     sqlite3 (1.3.10)
     therubyracer (0.12.1)
       libv8 (~> 3.16.14.0)
       ref
     thor (0.19.1)
-    thread_safe (0.3.4)
-    tilt (1.4.1)
+    thread_safe (0.3.5)
+    tilt (2.0.1)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
     uglifier (2.6.0)

data/spec_app/app/assets/stylesheets/application.css

@@ -11,7 +11,7 @@
  * file per style scope.
  *
  *= require up
- *= require_tree .
+ *= require_tree ./blocks
  *= require_self
  */
 

data/spec_app/app/controllers/test_controller.rb

@@ -0,0 +1,23 @@
+class TestController < ActionController::Base
+
+  def is_up
+    render :text => up?.to_s
+  end
+
+  def up_selector
+    render :text => up.selector
+  end
+
+  def is_up_validate
+    render :text => up.validate?.to_s
+  end
+
+  def up_validate_name
+    render :text => up.validate_name
+  end
+
+  def text
+    render :text => 'text from controller'
+  end
+
+end

data/spec_app/config/routes.rb

@@ -3,4 +3,6 @@ Rails.application.routes.draw do
   mount JasmineRails::Engine => '/specs' if defined?(JasmineRails)
   root to: redirect('/specs')
 
+  get 'test/:action', controller: 'test'
+
 end

data/spec_app/spec/controllers/test_controller_spec.rb

@@ -0,0 +1,67 @@
+describe TestController do
+
+  describe '#up?' do
+
+    it 'returns true if the request has an X-Up-Selector header' do
+      request.headers['X-Up-Selector'] = 'body'
+      get :is_up
+      expect(response.body).to eq('true')
+    end
+
+    it 'returns false if the request has no X-Up-Selector header' do
+      get :is_up
+      expect(response.body).to eq('false')
+    end
+
+  end
+
+  describe '#up' do
+
+    describe '#selector' do
+
+      it 'returns the CSS selector that is requested via Up.js' do
+        request.headers['X-Up-Selector'] = '.foo'
+        get :up_selector
+        expect(response.body).to eq('.foo')
+      end
+
+    end
+
+    describe '#validate?' do
+
+      it 'returns true the request is an Up.js validation call' do
+        request.headers['X-Up-Validate'] = 'user[email]'
+        get :is_up_validate
+        expect(response.body).to eq('true')
+      end
+
+      it 'returns false if the request is not an Up.js validation call' do
+        get :is_up_validate
+        expect(response.body).to eq('false')
+      end
+
+    end
+
+    describe '#validate_name' do
+
+      it 'returns the name of the field that is being validated' do
+        request.headers['X-Up-Validate'] = 'user[email]'
+        get :up_validate_name
+        expect(response.body).to eq('user[email]')
+      end
+
+    end
+
+  end
+
+
+  # describe '#test' do
+  #
+  #   it 'does stuff' do
+  #     get :test
+  #     expect(response.body).to eq('foo')
+  #   end
+  #
+  # end
+
+end

data/spec_app/spec/javascripts/helpers/append_fixture.js.coffee

@@ -0,0 +1,8 @@
+beforeEach ->
+  @appendFixture = (html) ->
+    @$fixtureContainer ||= $('<div class="fixture-container"></div>').appendTo(document.body)
+    $(html).appendTo(@$fixtureContainer)
+
+afterEach ->
+  $('.fixture-container').remove()
+  @$fixtureContainer = undefined

data/spec_app/spec/javascripts/helpers/last_request.js.coffee

@@ -1,4 +1,22 @@
+u = up.util
+
 beforeEach ->
   @lastRequest = ->
     jasmine.Ajax.requests.mostRecent() or up.util.error('There is no last request')
 
+  @respondWith = (args...) ->
+    firstArg = args.shift()
+    responseText = undefined
+    options = undefined
+    if u.isString(firstArg)
+      responseText = firstArg
+      options = args[0] || {}
+    else
+      options = firstArg
+      responseText = options.responseText
+    request = options.request || @lastRequest()
+    request.respondWith
+      status: options.status || 200
+      contentType: options.contentType || 'text/html'
+      responseHeaders: options.responseHeaders
+      responseText: responseText