upjs-rails 0.14.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fd47220f987d9bf4997383808d2242fc8a8fc316
-  data.tar.gz: b71ce97484ee052743ea7d876cf606f5dbed3928
+  metadata.gz: 8d8056ae5ab5354aaa8ca90558101abf08462bc3
+  data.tar.gz: 40f40019a92d36bbf9b633806f37370d4267c159
 SHA512:
-  metadata.gz: a6dac91f27712ab12d1b9720e024ac37e58cdaed57378a97d9c7a1bee9382d90c699f8156aea44e976cd9c5b0ad309d5df15a0a0fcc00c3199605f75cf82c541
-  data.tar.gz: b9ea728672ad5dcfb5691d5f46d0b00c801724a3dd1dd0ed5e5912c00f62f3f493da867b8a05e6c413f14430a26952a2b40db69391079fd90ed1df5c3eac5838
+  metadata.gz: 56ccd0b74346251a971b60379c7c66b7d00beee8ed4a4e2f095f8f2ba21a2a0aeea83b402ed11d384a7d1db0ba52fc8a9f46f041e89898a381e16db264eac15a
+  data.tar.gz: c3a053fde7dcc0d5ef169ba786de35dcdb36fbda86918ccce04b165453a2ff0a11f32950c6d2e96ffdaadc959dc41116bbaded285ee12864b61b5924e4f65782

data/.gitignore

@@ -1,17 +1,9 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-.idea
-InstalledFiles
-_yardoc
-coverage
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
+/pkg
+/.bundle
+/.yardoc
+/.idea
+/coverage
+/rdoc
 tmp
-dist/manifest.json
+/dist/manifest.json
+/doc

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown --main=README_RAILS.md

data/README.md

@@ -1,47 +1,66 @@
-# Up.js: Snappy UI for server-side web applications
+Up.js + Rails bindings
+======================
 
-Up.js gives your traditional web application fast-responding views with minimal changes to your code and development style. If you require modern UX but don't want to pay the Javascript MVC complexity tax, Up.js can be a solution for you.
+Up.js gives your traditional web application fast-responding views with minimal changes to your code and development style. If you require modern UX but don't want to pay the Javascript complexity tax, Up.js can be a solution for you.
 
-See [upjs.io](http://upjs.io) for more information and API documentation.
+This repository is home both to the Up.js javascript code and its (optional) bindings for Ruby on Rails (`upjs-rails` gem).
 
-See [`CHANGELOG.md`](https://github.com/makandra/upjs/blob/master/CHANGELOG.md) for notable changes.
 
+Getting started
+---------------
 
-## Running tests
+- See [upjs.io](http://upjs.io) for more information and Javascript API documentation.
+- See [`CHANGELOG.md`](https://github.com/makandra/upjs/blob/master/CHANGELOG.md) for notable changes.
+- See [`README_RAILS.md`](https://github.com/makandra/upjs/blob/master/README_RAILS.md) documentation of the Rails bindings.
+
+
+Running tests
+-------------
 
 Overview:
 
 - This currently requires Ruby
 - There's a Rails app in `spec_app`
-- Jasmine tests live in `spec_app/spec/javascripts`
-- There are also some Cucumber integration tests left in `spec_app/features`, but this is legacy code.
-  Testing with Jasmine works so well that we want the entire test suite to become pure-JS Jasmine specs.
- 
-To run Jasmine tests:
- 
+- Jasmine tests for Up.js live in `spec_app/spec/javascripts`
+- RSpec tests for the `upjs-rails` gem live in `spec_app/spec/controllers`
+
+Install dependencies for tests:
+
 - Install Ruby 2.1.2
+- Install Bundler by running `gem install bundler`
 - `cd` into `spec_app`
 - Install dependencies by running `bundle install`
-- Migrate
-- Start the Rails server
-- Access `http://localhost:3000/specs`
 
+To run Jasmine tests for Up.js:
+
+- `cd` into `spec_app`
+- Start the Rails server by running `rails server`
+- Access `http://localhost:3000/specs` to see the Jasmine test runner
 
-## Making a new release
+To run RSpec tests for the `upjs-rails` gem:
+
+- `cd` into `spec_app`
+- Run `rspec`
+
+
+Making a new release
+--------------------
 
 We are currently feeding three release channels:
 
 - Manual download from Github
-- Bower
+- Bower (this also fetches from Github)
 - Rubygems (as the `upjs-rails` gem)
 
+We always release to all channel simultaneously.
+
 To make a new release:
 
 - Edit `lib/upjs/rails/version.rb` and bump the version number. Use [semantic versioning](http://semver.org/).
 - Add an entry to `CHANGELOG.md`
 - Commit and push the version bump and `CHANGELOG.md`
 - From the project root, type `rake assets:compile`. This will output minified JS and CSS files to the `dist` folder.
-- Commit and push the generated files
+- Commit and push the generated files in `dist`
 - From the project root, type `rake release`. This will publish a new gem version to Rubygems.org.
   It will also push a tag for this version, which Bower requires for its own versioning scheme.
 

data/README_RAILS.md

@@ -0,0 +1,116 @@
+upjs-rails: Ruby on Rails bindings for Up.js
+============================================
+
+[Up.js](http://upjs.io) is a backend-agnostic progressive enhancement framework. `upjs-rails` gives your [Ruby on Rails](http://rubyonrails.org/) application some convenience candy when you are using Up.js in your frontend.
+
+
+Features
+--------
+
+The methods documented below are available in all controllers, views and helpers.
+
+### Detecting a fragment update
+
+To test whether the current request is a [fragment update](http://upjs.io/up.replace):
+
+    up?
+
+To retrieve the CSS selector that is being [updated](http://upjs.io/up.replace):
+
+    up.selector
+
+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.
+
+### Pushing a document title to the client
+
+To force Up.js to set a document title when processing the response:
+
+    up.title = 'Title from server'
+
+This is useful when you skip rendering the `<head>` in an Up.js request.
+
+### Detecting an Up.js form validation
+
+To test whether the current request is a [form validation](http://upjs.io/up-validate):
+
+    up.validate?
+
+When detecting a validation request, the server is expected to validate (but not save) the form submission and render a new copy of the form with validation errors. A typical saving action should behave like this:
+
+    class UsersController < ApplicationController
+
+      def create
+        user_params = params[:user].permit(:email, :password)
+        @user = User.new(user_params)
+        if up.validate?
+          @user.valid?  # run validations, but don't save to the database
+          render 'form' # render form with error messages
+        elsif @user.save?
+          sign_in @user
+        else
+          render 'form', status: :bad_request
+        end
+      end
+
+    end
+
+### Automatic redirect detection
+
+`upjs-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](http://upjs.io/form-up-target#redirects), which are otherwise undetectable for an AJAX client.
+
+### Automatic method detection for initial page load
+
+`upjs-rails` sets an `_up_request_method` cookie that Up.js needs to detect the request method for the initial page load.
+
+If the initial page was loaded with a non-`GET` HTTP method, Up.js will fall back to full page loads for all actions that require `pushState`.
+
+The reason for this is that some browsers remember the method of the initial page load and don't let the application change it, even with `pushState`. Thus, when the user reloads the page much later, an affected browser might request a `POST`, `PUT`, etc. instead of the correct method.
+
+
+What you still need to do manually
+----------------------------------
+
+### Failed form submissions must return a non-200 status code
+
+Up.js lets you submit forms via AJAX by using the [`form[up-target]`](http://upjs.io/form-up-target) selector or [`up.submit`](http://upjs.io/up.submit) function.
+
+For Up.js to be able to detect a failed form submission, the form must be re-rendered with a non-200 HTTP status code. We recommend to use either 400 (bad request) or 422 (unprocessable entity).
+
+To do so in Rails, pass a [`:status` option to `render`](http://guides.rubyonrails.org/layouts_and_rendering.html#the-status-option):
+
+    class UsersController < ApplicationController
+
+      def create
+        user_params = params[:user].permit(:email, :password)
+        @user = User.new(user_params)
+        if @user.save?
+          sign_in @user
+        else
+          render 'form', status: :bad_request
+        end
+      end
+
+    end
+
+
+Development
+-----------
+
+### Before you make a PR
+
+Before you make a PR, please have some discussion about the proposed change by [opening an issue on Github](https://github.com/makandra/upjs/issues/new).
+
+### Running tests
+
+- Install Ruby 2.1.2
+- Install Bundler by running `gem install bundler`
+- `cd` into `spec_app`
+- Install dependencies by running `bundle install`
+- Run `rspec`
+
+### Making a new release
+
+New versions of `upjs-rails` are released as part of the [Up.js release process](https://github.com/makandra/upjs/blob/master/README.md#making-a-new-release).

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

@@ -145,7 +145,12 @@ up.bus = (($) ->
 
 
   ###*
-  Emits an event with the given name and properties.
+  Emits a event with the given name and properties.
+
+  The event will be triggered as a jQuery event on `document`.
+
+  Other code can subscribe to events with that name using
+  [`up.on`](/up.on) or by [binding a jQuery event listener](http://api.jquery.com/on/) to `document`.
 
   \#\#\#\# Example
 
@@ -249,9 +254,11 @@ up.bus = (($) ->
 
   ###*
   Boots the Up.js framework.
+
   This is done automatically by including the Up.js Javascript.
 
-  Does nothing if the current browser is [not supported](/up.browser.isSupported).
+  Up.js will not boot if the current browser is [not supported](/up.browser.isSupported).
+  This leaves you with a classic server-side application on legacy browsers.
 
   Emits the [`up:framework:boot`](/up:framework:boot) event.
 

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

@@ -106,6 +106,9 @@ up.flow = (($) ->
   that is being updated. The request's `X-Up-Selector` header will contain
   the CSS selector for the updating fragment.
 
+  If you are using the `upjs-rails` gem you can also access the selector via
+  `up.selector` in all controllers, views and helpers.
+
   \#\#\#\# Events
 
   Up.js will emit [`up:fragment:destroyed`](/up:fragment:destroyed) on the element
@@ -360,13 +363,11 @@ up.flow = (($) ->
     $element.closest(unreal).length == 0
 
   ###*
-  Returns the first element matching the given selector.
-
-  Excludes elements that also match `.up-ghost` or `.up-destroying`
-  or that are children of elements with these selectors.
+  Returns the first element matching the given selector, but
+  ignores elements that are being [destroyed](/up.destroy) or [transitioned](/up.morph).
 
   If the given argument is already a jQuery collection (or an array
-  of DOM elements), the first element  matching these conditions
+  of DOM elements), the first element matching these conditions
   is returned.
 
   Returns `undefined` if no element matches these conditions.

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

@@ -24,6 +24,7 @@ up.form = (($) ->
     By default this looks for a `<fieldset>`, `<label>` or `<form>`
     around the validating input field, or any element with an
     `up-fieldset` attribute.
+  @stable
   ###
   config = u.config
     validateTargets: ['[up-fieldset]:has(&)', 'fieldset:has(&)', 'label:has(&)', 'form:has(&)']
@@ -363,13 +364,13 @@ up.form = (($) ->
 
   The programmatic variant of this is the [`up.submit`](/up.submit) function.
 
-  \#\#\#\# Validation errors
+  \#\#\#\# Failed submission
 
   When the server was unable to save the form due to invalid data,
   it will usually re-render an updated copy of the form with
   validation messages.
 
-  For Up.js to be able to pick up a validation failure,
+  For Up.js to be able to detect a failed form submission,,
   the form must be re-rendered with a non-200 HTTP status code.
   We recommend to use either 400 (bad request) or
   422 (unprocessable entity).

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

@@ -24,6 +24,7 @@ up.history = (($) ->
   @param {Boolean} [config.restoreScroll=true]
     Whether to restore the known scroll positions
     when the user goes back or forward in history.
+  @stable
   ###
   config = u.config
     popTargets: ['body']

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

@@ -38,6 +38,7 @@ up.layout = (($) ->
     to the top when the revealed element is closer to the top than `config.snap`.
   @param {Number} [config.substance]
     A number indicating how many top pixel rows of an element to [reveal](/up.reveal).
+  @stable
   ###
   config = u.config
     duration: 0
@@ -191,7 +192,9 @@ up.layout = (($) ->
   Many applications have a navigation bar fixed to the top or bottom,
   obstructing the view on an element.
 
-  To make `up.aware` of these fixed elements you can either:
+  You can make `up.reveal` aware of these fixed elements
+  so it can scroll the viewport far enough so the revealed element is fully visible.
+  To make `up.reveal` aware fixed elements you can either:
 
   - give the element an attribute [`up-fixed="top"`](/up-fixed-top) or [`up-fixed="bottom"`](up-fixed-bottom)
   - [configure default options](/up.layout.config) for `fixedTop` or `fixedBottom`
@@ -480,7 +483,7 @@ up.layout = (($) ->
   [`up.reveal`](/up.reveal) is aware of fixed elements and will scroll
   the viewport far enough so the revealed element is fully visible.
 
-  Example:
+  \#\#\#\# Example
 
       <div class="top-nav" up-fixed="top">...</div>
 
@@ -495,7 +498,7 @@ up.layout = (($) ->
   [`up.reveal`](/up.reveal) is aware of fixed elements and will scroll
   the viewport far enough so the revealed element is fully visible.
 
-  Example:
+  \#\#\#\# Example
 
       <div class="bottom-nav" up-fixed="bottom">...</div>
 

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

@@ -100,7 +100,7 @@ up.link = (($) ->
     The URL to visit.
   @param {String} [options.target='body']
     The selector to replace.
-  @param {Object} options
+  @param {Object} [options]
     See options for [`up.replace`](/up.replace)
   @stable
   ###
@@ -122,6 +122,8 @@ up.link = (($) ->
       var $link = $('a:first'); // select link with jQuery
       up.follow($link);
 
+  The UJS variant of this are the [`a[up-target]`](/a-up-target) and [`a[up-follow]`](/a-up-follow) selectors.
+
   @function up.follow
   @param {Element|jQuery|String} linkOrSelector
     An element or selector which resolves to an `<a>` tag
@@ -316,11 +318,12 @@ up.link = (($) ->
   If applied on a link, Follows this link via AJAX and replaces the
   current `<body>` element with the response's `<body>` element.
 
-  Example:
+  To only update a fragment instead of the entire page, see
+  [`a[up-target]`](/a-up-target).
 
-      <a href="/users" up-follow>User list</a>
+  \#\#\#\# Example
 
-  To only update a fragment instead of the entire page, see [`up-target`](/up-target).
+      <a href="/users" up-follow>User list</a>
 
   \#\#\#\# Turn any element into a link
 
@@ -353,7 +356,12 @@ up.link = (($) ->
 
   ###*
   Add an `up-expand` class to any element that contains a link
-  in order to enlarge the link's click area:
+  in order to enlarge the link's click area.
+
+  `up-expand` honors all the UJS behavior in expanded links
+  ([`up-target`](/up-target), [`up-instant`](/up-instant), [`up-preload`](/up-preload), etc.).
+
+  \#\#\#\# Example
 
       <div class="notification" up-expand>
         Record was saved!
@@ -363,9 +371,6 @@ up.link = (($) ->
   In the example above, clicking anywhere within `.notification` element
   would [follow](/up.follow) the *Close* link.
 
-  `up-expand` honors all the UJS behavior in expanded links
-  (`up-target`, `up-instant`, `up-preload`, etc.).
-
   @selector [up-expand]
   @stable
   ###

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

@@ -93,6 +93,7 @@ up.modal = (($) ->
   @param {String} [config.closeAnimation='fade-out']
     The animation used to close the modal. The animation will be applied
     to both the dialog box and the overlay dimming the page.
+  @stable
   ###
   config = u.config
     maxWidth: null
@@ -331,6 +332,7 @@ up.modal = (($) ->
 
   ###*
   Closes a currently opened modal overlay.
+
   Does nothing if no modal is currently open.
 
   Emits events [`up:modal:close`](/up:modal:close) and [`up:modal:closed`](/up:modal:closed).

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

@@ -45,6 +45,7 @@ up.motion = (($) ->
   @param {Number} [config.duration=300]
   @param {Number} [config.delay=0]
   @param {String} [config.easing='ease']
+  @stable
   ###
   config = u.config
     duration: 300
@@ -57,7 +58,9 @@ up.motion = (($) ->
     config.reset()
 
   ###*
-  Applies the given animation to the given element:
+  Applies the given animation to the given element.
+
+  \#\#\#\# Example
 
       up.animate('.warning', 'fade-in');
 
@@ -109,6 +112,7 @@ up.motion = (($) ->
     The element to animate.
   @param {String|Function|Object} animation
     Can either be:
+
     - The animation's name
     - A function performing the animation
     - An object of CSS attributes describing the last frame of the animation
@@ -220,9 +224,10 @@ up.motion = (($) ->
     promise
       
   ###*
-  Completes all animations and transitions for the given element
-  by jumping to the last animation frame instantly. All callbacks chained to
-  the original animation's promise will be called.
+  Completes all [animations](/up.animate) and [transitions](/up.morph)
+  for the given element by jumping to the last animation frame instantly.
+
+  All callbacks chained to the original animation's promise will be called.
 
   Does nothing if the given element is not currently animating.
   

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

@@ -21,6 +21,7 @@ up.navigation = (($) ->
   @property up.navigation.config
   @param {Number} [config.currentClasses]
     An array of classes to set on [links that point the current location](/up-current).
+  @stable
   ###
   config = u.config
     currentClasses: ['up-current']
@@ -120,8 +121,8 @@ up.navigation = (($) ->
 
       <a href="/foo" up-follow up-active>Foo</a>
 
-  Once the fragment is loaded the browser's location bar is updated
-  to `http://yourhost/foo` via [`history.pushState`](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history#Adding_and_modifying_history_entries):
+  Once the link destination has loaded and rendered, the `up-active` class
+  is removed and the [`up-current`](/up-current) class is added:
 
       <a href="/foo" up-follow up-current>Foo</a>
 

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

@@ -83,6 +83,7 @@ up.popup = (($) ->
     Defines where the popup is attached to the opening element.
 
     Valid values are `bottom-right`, `bottom-left`, `top-right` and `top-left`.
+  @stable
   ###
   config = u.config
     openAnimation: 'fade-in'
@@ -292,8 +293,15 @@ up.popup = (($) ->
 
   ###*
   When an element with this attribute is clicked,
-  a currently open popup is closed. 
-  
+  a currently open popup is closed.
+
+  Does nothing if no popup is currently open.
+
+  To make a link that closes the current popup, but follows to
+  a fallback destination if no popup is open:
+
+      <a href="/fallback" up-close>Okay</a>
+
   @selector [up-close]
   @stable
   ###

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

@@ -77,6 +77,7 @@ up.proxy = (($) ->
   @param {Number} [config.busyDelay=300]
     How long the proxy waits until emitting the [`up:proxy:busy` event](/up:proxy:busy).
     Use this to prevent flickering of spinners.
+  @stable
   ###
   config = u.config
     busyDelay: 300
@@ -392,7 +393,7 @@ up.proxy = (($) ->
     The element whose destination should be preloaded.
   @return
     A promise that will be resolved when the request was loaded and cached
-  @stable
+  @experimental
   ###
   preload = (linkOrSelector, options) ->
     $link = $(linkOrSelector)

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

@@ -44,6 +44,7 @@ up.tooltip = (($) ->
     The animation used to open a tooltip.
   @param {String} [config.closeAnimation='fade-out']
     The animation used to close a tooltip.
+  @stable
   ###
   config = u.config
     position: 'top'

data/lib/upjs/rails/engine.rb

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

data/lib/upjs/rails/inspector.rb

@@ -40,7 +40,7 @@ module Upjs
         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.
@@ -48,6 +48,15 @@ module Upjs
         request.headers['X-Up-Validate']
       end
 
+      ##
+      # Forces Up.js to use the given string as the document title when processing
+      # this response.
+      #
+      # This is useful when you skip rendering the `<head>` in an Up.js request.
+      def title=(new_title)
+        response.headers['X-Up-Title'] = new_title
+      end
+
       private
 
       def request
@@ -58,6 +67,10 @@ module Upjs
         @controller.params
       end
 
+      def response
+        @controller.response
+      end
+
     end
   end
 end

data/lib/upjs/rails/inspector_accessor.rb

@@ -6,7 +6,7 @@ module Upjs
     # for Up.js-related concerns such as "is this a page fragment update?".
     module InspectorAccessor
 
-      def self.included(base) # :nodoc:
+      def self.included(base)
         base.helper_method :up, :up?
       end
 

data/lib/upjs/rails/request_echo_headers.rb

@@ -1,7 +1,7 @@
 module Upjs
   module Rails
     ##
-    # Installs a before_filter into all controllers which echoes the
+    # 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`.
     #

data/lib/upjs/rails/request_method_cookie.rb

@@ -15,7 +15,7 @@ module Upjs
 
       COOKIE_NAME = '_up_request_method'
 
-      def self.included(base) # :nodoc:
+      def self.included(base)
         base.before_filter :set_up_request_method_cookie
       end
 

data/lib/upjs/rails/version.rb

@@ -4,6 +4,6 @@ module Upjs
     # The current version of the upjs-rails gem.
     # This version number is also used for releases of the Up.js
     # frontend code.
-    VERSION = '0.14.0'
+    VERSION = '0.14.1'
   end
 end

data/spec_app/Gemfile

@@ -26,8 +26,4 @@ end
 
 group :test do
   gem 'rspec-rails'
-  gem 'cucumber-rails', require: false
-  gem 'database_cleaner'
-  gem 'selenium-webdriver'
-  gem 'spreewald'
 end