upjs-rails 0.12.5 → 0.13.0

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

@@ -1,21 +1,10 @@
 ###*
-Forms and controls
-==================
+Forms
+=====
   
-Up.js comes with functionality to submit forms without
-leaving the current page. This means you can replace page fragments,
+Up.js comes with functionality to [submit](/form-up-target) and [validate](/up-validate)
+forms without leaving the current page. This means you can replace page fragments,
 open dialogs with sub-forms, etc. all without losing form state.
-  
-\#\#\# Incomplete documentation!
-  
-We need to work on this page:
-  
-- Explain how to display form errors
-- Explain that the server needs to send 2xx or 5xx status codes so
-  Up.js can decide whether the form submission was successful
-- Explain that the server needs to send `X-Up-Location` and `X-Up-Method` headers
-  if an successful form submission resulted in a redirect
-- Examples
 
 @class up.form
 ###
@@ -24,14 +13,37 @@ up.form = (($) ->
   u = up.util
 
   ###*
-  Submits a form using the Up.js flow:
-  
-      up.submit('form.new_user')
+  Sets default options for form submission and validation.
+
+  @property up.form.config
+  @param {Array} [config.validateTargets=['[up-fieldset]:has(&)', 'fieldset:has(&)', 'label:has(&)', 'form:has(&)']]
+    An array of CSS selectors that are searched around a form field
+    that wants to [validate](/up.validate). The first matching selector
+    will be updated with the validation messages from the server.
+
+    By default this looks for a `<fieldset>`, `<label>` or `<form>`
+    around the validating input field, or any element with an
+    `up-fieldset` attribute.
+  ###
+  config = u.config
+    validateTargets: ['[up-fieldset]:has(&)', 'fieldset:has(&)', 'label:has(&)', 'form:has(&)']
+
+  reset = ->
+    config.reset()
+
+  ###*
+  Submits a form via AJAX and updates a page fragment with the response.
+
+      up.submit('form.new-user', { target: '.main' })
   
   Instead of loading a new page, the form is submitted via AJAX.
   The response is parsed for a CSS selector and the matching elements will
   replace corresponding elements on the current page.
-  
+
+  The UJS variant of this is the [`form[up-target]`](/form-up-target) selector.
+  See the documentation for [`form[up-target]`](/form-up-target) for more
+  information on how AJAX form submissions work in Up.js.
+
   @function up.submit
   @param {Element|jQuery|String} formOrSelector
     A reference or selector for the form to submit.
@@ -81,6 +93,9 @@ up.form = (($) ->
 
     By default only responses to `GET` requests are cached
     for a few minutes.
+  @param {Object} [options.headers={}]
+    An object of additional header key/value pairs to send along
+    with the request.
   @return {Promise}
     A promise for the successful form submission.
   ###
@@ -89,27 +104,38 @@ up.form = (($) ->
     $form = $(formOrSelector).closest('form')
 
     options = u.options(options)
-    successSelector = u.option(options.target, $form.attr('up-target'), 'body')
-    failureSelector = u.option(options.failTarget, $form.attr('up-fail-target'), -> u.createSelectorFromElement($form))
+    successSelector = up.flow.resolveSelector(u.option(options.target, $form.attr('up-target'), 'body'), options)
+    failureSelector = up.flow.resolveSelector(u.option(options.failTarget, $form.attr('up-fail-target'), -> u.createSelectorFromElement($form)), options)
     historyOption = u.option(options.history, u.castedAttr($form, 'up-history'), true)
     successTransition = u.option(options.transition, u.castedAttr($form, 'up-transition'))
     failureTransition = u.option(options.failTransition, u.castedAttr($form, 'up-fail-transition'), successTransition)
     httpMethod = u.option(options.method, $form.attr('up-method'), $form.attr('data-method'), $form.attr('method'), 'post').toUpperCase()
+    headers = u.option(options.headers, {})
 
     implantOptions = {}
     implantOptions.reveal = u.option(options.reveal, u.castedAttr($form, 'up-reveal'), true)
     implantOptions.cache = u.option(options.cache, u.castedAttr($form, 'up-cache'))
     implantOptions.restoreScroll = u.option(options.restoreScroll, u.castedAttr($form, 'up-restore-scroll'))
+    implantOptions.origin = u.option(options.origin, $form)
     implantOptions = u.extend(implantOptions, up.motion.animateOptions(options, $form))
 
     useCache = u.option(options.cache, u.castedAttr($form, 'up-cache'))
     url = u.option(options.url, $form.attr('action'), up.browser.url())
-    
+
+    hasFileInputs = $form.find('input[type=file]').length
+
+    if options.validate
+      headers['X-Up-Validate'] = options.validate
+      # Since we cannot (yet) submit file inputs via AJAX, we cannot
+      # offer inline validation for such forms.
+      if hasFileInputs
+        return u.unresolvablePromise()
+
     $form.addClass('up-active')
-    
-    if !up.browser.canPushState() && historyOption != false
+
+    if hasFileInputs || (!up.browser.canPushState() && historyOption != false)
       $form.get(0).submit()
-      return
+      return u.unresolvablePromise()
 
     request = {
       url: url
@@ -117,6 +143,7 @@ up.form = (($) ->
       data: $form.serialize()
       selector: successSelector
       cache: useCache
+      headers: headers
     }
 
     successUrl = (xhr) ->
@@ -148,7 +175,11 @@ up.form = (($) ->
   Observes a form field and runs a callback when its value changes.
   This is useful for observing text fields while the user is typing.
 
-  For instance, the following would submit the form whenever the
+  The UJS variant of this is the [`up-observe`](/up-observe) attribute.
+
+  \#\#\#\# Example
+
+  The following would submit the form whenever the
   text field value changes:
 
       up.observe('input[name=query]', { change: function(value, $input) {
@@ -176,7 +207,6 @@ up.form = (($) ->
         change: function(value, $input) { up.submit($input) }
       });
 
-
   @function up.observe
   @param {Element|jQuery|String} fieldOrSelector
   @param {Function(value, $field)|String} options.change
@@ -265,14 +295,125 @@ up.form = (($) ->
     # return destructor
     return clearTimer
 
+  resolveValidateTarget = ($field, options) ->
+    target = u.option(options.target, $field.attr('up-validate'))
+    if u.isBlank(target)
+      target ||= u.detect(config.validateTargets, (defaultTarget) ->
+        resolvedDefault = up.flow.resolveSelector(defaultTarget, options)
+        $field.closest(resolvedDefault).length
+      )
+    if u.isBlank(target)
+      error('Could not find default validation target for %o (tried ancestors %o)', $field, config.validateTargets)
+    unless u.isString(target)
+      target = u.createSelectorFromElement(target)
+    target
+
+  ###*
+  Performs a server-side validation of a form and update the form
+  with validation messages.
+
+  `up.validate` submits the given field's form with an additional `X-Up-Validate`
+  HTTP header. Upon seeing this header, the server is expected to validate (but not save)
+  the form submission and render a new copy of the form with validation errors.
+
+  The UJS variant of this is the [`[up-validate]`](/up-validate) selector.
+  See the documentation for [`[up-validate]`](/up-validate) for more information
+  on how server-side validation works in Up.js.
+
+  \#\#\#\# Example
+
+      up.validate('input[name=email]', { target: '.email-errors' })
+
+  @function up.validate
+  @param {String|Element|jQuery} fieldOrSelector
+  @param {String|Element|jQuery} [options.target]
+  @return {Promise}
+    A promise that is resolved when the server-side
+    validation is received and the form was updated.
+  ###
+  validate = (fieldOrSelector, options) ->
+    $field = $(fieldOrSelector)
+    options = u.options(options)
+    options.origin = $field
+    options.target = resolveValidateTarget($field, options)
+    options.failTarget = options.target
+    options.history = false
+    options.headers = u.option(options.headers, {})
+    # Make sure the X-Up-Validate header is present, so the server-side
+    # knows that it should not persist the form submission
+    options.validate = ($field.attr('name') || '__none__')
+    options = u.merge(options, up.motion.animateOptions(options, $field))
+    $form = $field.closest('form')
+    promise = up.submit($form, options)
+    promise
+
   ###*
-  Submits the form through AJAX, searches the response for the selector
-  given in `up-target` and [replaces](/up.replace) the selector content in the current page:
+  Forms with an `up-target` attribute are [submitted via AJAX](/up.submit)
+  instead of triggering a full page reload.
 
       <form method="post" action="/users" up-target=".main">
         ...
       </form>
 
+  The server response is searched for the selector given in `up-target`.
+  The selector content is then [replaced](/up.replace) in the current page.
+
+  The programmatic variant of this is the [`up.submit`](/up.submit) function.
+
+  \#\#\#\# Validation errors
+
+  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,
+  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).
+
+  In Ruby on Rails, you can pass a
+  [`:status` option to `render`](http://guides.rubyonrails.org/layouts_and_rendering.html#the-status-option)
+  for this:
+
+      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
+
+  Note that you can also use the
+  [`up-validate`](/up-validate) attribute to perform server-side
+  validations while the user is completing fields.
+
+  \#\#\#\# Redirects
+
+  Up.js requires two additional response headers to detect redirects,
+  which are otherwise undetectable for an AJAX client.
+
+  When the form's action performs a redirect, the server should echo
+  the new request's URL as a response header `X-Up-Location`
+  and the request's HTTP method as `X-Up-Method`.
+
+  If you are using Up.js via the `upjs-rails` gem, these headers
+  are set automatically for every request.
+
+  \#\#\#\# Giving feedback while the form is processing
+
+  The `<form>` element will be assigned a CSS class `up-active` while
+  the submission is loading.
+
+  You can also [implement a spinner](/up.proxy/#spinners)
+  by [listening](/up.on) to the [`up:proxy:busy`](/up:proxy:busy)
+  and [`up:proxy:idle`](/up:proxy:idle) events.
+
   @selector form[up-target]
   @param {String} up-target
     The selector to [replace](/up.replace) if the form submission is successful (200 status code).
@@ -306,11 +447,160 @@ up.form = (($) ->
     event.preventDefault()
     submit($form)
 
+  ###*
+  When a form field with this attribute is changed,
+  the form is validated on the server and is updated with
+  validation messages.
+
+  The programmatic variant of this is the [`up.validate`](/up.validate) function.
+
+  \#\#\#\# Example
+
+  Let's look at a standard registration form that asks for an e-mail and password:
+
+      <form action="/users">
+
+        <label>
+          E-mail: <input type="text" name="email" />
+        </label>
+
+        <label>
+          Password: <input type="password" name="password" />
+        </label>
+
+        <button type="submit">Register</button>
+
+      </form>
+
+  When the user changes the `email` field, we want to validate that
+  the e-mail address is valid and still available. Also we want to
+  change the `password` field for the minimum required password length.
+  We can do this by giving both fields an `up-validate` attribute:
+
+      <form action="/users">
+
+        <label>
+          E-mail: <input type="text" name="email" up-validate />
+        </label>
+
+        <label>
+          Password: <input type="password" name="password" up-validate />
+        </label>
+
+        <button type="submit">Register</button>
+
+      </form>
+
+  Whenever a field with `up-validate` changes, the form is POSTed to
+  `/users` with an additional `X-Up-Validate` HTTP header.
+  Upon seeing this header, the server is expected to validate (but not save)
+  the form submission and render a new copy of the form with validation errors.
+
+  In Ruby on Rails the processing action should behave like this:
+
+      class UsersController < ApplicationController
+
+        # This action handles POST /users
+        def create
+          user_params = params[:user].permit(:email, :password)
+          @user = User.new(user_params)
+          if request.headers['X-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
+
+  Note that if you're using the `upjs-rails` gem you can simply say `up.validate?`
+  instead of manually checking for `request.headers['X-Up-Validate']`.
+
+  The server now renders an updated copy of the form with eventual validation errors:
+
+      <form action="/users">
+
+        <label class="has-error">
+          E-mail: <input type="text" name="email" value="foo@bar.com" />
+          Has already been taken!
+        </label>
+
+        <button type="submit">Register</button>
+
+      </form>
+
+  The `<label>` around the e-mail field is now updated to have the `has-error`
+  class and display the validation message.
+
+  \#\#\#\# How validation results are displayed
+
+  Although the server will usually respond to a validation with a complete,
+  fresh copy of the form, Up.js will by default not update the entire form.
+  This is done in order to preserve volatile state such as the scroll position
+  of `<textarea>` elements.
+
+  By default Up.js looks for a `<fieldset>`, `<label>` or `<form>`
+  around the validating input field, or any element with an
+  `up-fieldset` attribute.
+  With the Bootstrap bindings, Up.js will also look
+  for a container with the `form-group` class.
+
+  You can change this default behavior by setting `up.config.validateTargets`:
+
+      // Always update the entire form containing the current field ("&")
+      up.config.validateTargets = ['form &']
+
+  You can also individually override what to update by setting the `up-validate`
+  attribute to a CSS selector:
+
+      <input type="text" name="email" up-validate=".email-errors">
+      <span class="email-errors"></span>
+
+
+  \#\#\#\# Updating dependent fields
+
+  The `[up-validate]` behavior is also a great way to partially update a form
+  when one fields depends on the value of another field.
+
+  Let's say you have a form with one `<select>` to pick a department (sales, engineering, ...)
+  and another `<select>` to pick an employeee from the selected department:
+
+      <form action="/contracts">
+        <select name="department">...</select> <!-- options for all departments -->
+        <select name="employeed">...</select> <!-- options for employees of selected department -->
+      </form>
+
+  The list of employees needs to be updated as the appartment changes:
+
+      <form action="/contracts">
+        <select name="department" up-validate="[name=employee]">...</select>
+        <select name="employee">...</select>
+      </form>
+
+  In order to update the `department` field in addition to the `employee` field, you could say
+  `up-validate="&, [name=employee]"`, or simply `up-validate="form"` to update the entire form.
+
+  @selector [up-validate]
+  @param {String} up-validate
+    The CSS selector to update with the server response.
+
+    This defaults to a fieldset or form group around the validating field.
+  ###
+  up.on 'change', '[up-validate]', (event, $field) ->
+    validate($field)
+
   ###*
   Observes this form field and runs the given script
   when its value changes. This is useful for observing text fields
   while the user is typing.
 
+  The programmatic variant of this is the [`up.observe`](/up.observe) function.
+
+  \#\#\#\# Example
+
   For instance, the following would submit the form whenever the
   text field value changes:
 
@@ -318,7 +608,7 @@ up.form = (($) ->
         <input type="query" up-observe="up.form.submit(this)">
       </form>
 
-  The script given with `up-observe` runs with the following context:
+  The script given to `up-observe` runs with the following context:
 
   | Name     | Type      | Description                           |
   | -------- | --------- | ------------------------------------- |
@@ -326,11 +616,9 @@ up.form = (($) ->
   | `this`   | `Element` | The form field                        |
   | `$field` | `jQuery`  | The form field as a jQuery collection |
 
-  See up.observe.
-
-  @selector input[up-observe]
-    The code to run when the field's value changes.
+  @selector [up-observe]
   @param {String} up-observe
+    The code to run when the field's value changes.
   ###
   up.compiler '[up-observe]', ($field) ->
     return observe($field)
@@ -343,10 +631,15 @@ up.form = (($) ->
 #        $field.removeClass('up-active')
 #    )
 
+  up.on 'up:framework:reset', reset
+
   submit: submit
   observe: observe
+  validate: validate
 
 )(jQuery)
 
 up.submit = up.form.submit
 up.observe = up.form.observe
+up.validate = up.form.validate
+

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

@@ -18,7 +18,7 @@ up.history = (($) ->
 
   ###*
   @property up.history.config
-  @param {Array<String>} [config.popTargets=['body']]
+  @param {Array} [config.popTargets=['body']]
     An array of CSS selectors to replace when the user goes
     back in history.
   @param {Boolean} [config.restoreScroll=true]

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

@@ -14,16 +14,16 @@ up.layout = (($) ->
   Configures the application layout.
 
   @property up.layout.config
-  @param {Array<String>} [config.viewports]
+  @param {Array} [config.viewports]
     An array of CSS selectors that find viewports
     (containers that scroll their contents).
-  @param {Array<String>} [config.fixedTop]
+  @param {Array} [config.fixedTop]
     An array of CSS selectors that find elements fixed to the
     top edge of the screen (using `position: fixed`).
-  @param {Array<String>} [config.fixedBottom]
+  @param {Array} [config.fixedBottom]
     An array of CSS selectors that find elements fixed to the
     bottom edge of the screen (using `position: fixed`).
-  @param {Array<String>} [config.anchoredRight]
+  @param {Array} [config.anchoredRight]
     An array of CSS selectors that find elements anchored to the
     right edge of the screen (using `position: fixed` or `position: absolute`).
   @param {Number} [config.duration]

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

@@ -140,12 +140,15 @@ up.link = (($) ->
   @param {Element|jQuery|String} [options.reveal]
     Whether to reveal the target  element within its viewport before updating.
   @param {Boolean} [options.restoreScroll]
-    If set to `true`, this will attempt to [`restore scroll positions`](/up.restoreScroll)
+    If set to `true`, this will attempt to [restore scroll positions](/up.restoreScroll)
     previously seen on the destination URL.
   @param {Boolean} [options.cache]
     Whether to force the use of a cached response (`true`)
     or never use the cache (`false`)
     or make an educated guess (`undefined`).
+  @param {Object} [options.headers={}]
+    An object of additional header key/value pairs to send along
+    with the request.
   ###
   follow = (linkOrSelector, options) ->
     $link = $(linkOrSelector)
@@ -159,6 +162,7 @@ up.link = (($) ->
     options.cache = u.option(options.cache, u.castedAttr($link, 'up-cache'))
     options.restoreScroll = u.option(options.restoreScroll, u.castedAttr($link, 'up-restore-scroll'))
     options.method = followMethod($link, options)
+    options.origin = u.option(options.origin, $link)
     options = u.merge(options, up.motion.animateOptions(options, $link))
 
     up.replace(selector, url, options)
@@ -371,7 +375,6 @@ up.link = (($) ->
     $area.removeAttr('up-expand')
     makeFollowable($area)
 
-  
   ###*
   Marks up the current link to be followed *as fast as possible*.
   This is done by:

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

@@ -452,6 +452,7 @@ up.modal = (($) ->
   # The framework is reset between tests
   up.on 'up:framework:reset', reset
 
+  knife: eval(Knife?.point)
   visit: visit
   follow: follow
   open: -> up.error('up.modal.open no longer exists. Please use either up.modal.follow or up.modal.visit.')

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

@@ -75,7 +75,7 @@ up.proxy = (($) ->
     The number of milliseconds until a cache entry expires.
     Defaults to 5 minutes.
   @param {Number} [config.busyDelay=300]
-    How long the proxy waits until emitting the `proxy:busy` [event](/up.bus).
+    How long the proxy waits until emitting the [`up:proxy:busy` event](/up:proxy:busy).
     Use this to prevent flickering of spinners.
   ###
   config = u.config
@@ -98,11 +98,23 @@ up.proxy = (($) ->
     key: cacheKey
     log: 'up.proxy'
 
+
   ###*
   @protected
   @function up.proxy.get
   ###
-  get = cache.get
+  get = (request) ->
+    request = normalizeRequest(request)
+    candidates = [request]
+    unless request.selector is 'html'
+      requestForHtml = u.merge(request, selector: 'html')
+      candidates.push(requestForHtml)
+      unless request.selector is 'body'
+        requestForBody = u.merge(request, selector: 'body')
+        candidates.push(requestForBody)
+    for candidate in candidates
+      if response = cache.get(candidate)
+        return response
 
   ###*
   @protected
@@ -162,8 +174,8 @@ up.proxy = (($) ->
   are considered to be read-only.
 
   If a network connection is attempted, the proxy will emit
-  a `proxy:load` event with the `request` as its argument.
-  Once the response is received, a `proxy:receive` event will
+  a `up:proxy:load` event with the `request` as its argument.
+  Once the response is received, a `up:proxy:receive` event will
   be emitted.
   
   @function up.proxy.ajax
@@ -173,13 +185,16 @@ up.proxy = (($) ->
   @param {Boolean} [request.cache]
     Whether to use a cached response, if available.
     If set to `false` a network connection will always be attempted.
+  @param {Object} [request.headers={}]
+    An object of additional header key/value pairs to send along
+    with the request.
   ###
   ajax = (options) ->
 
     forceCache = (options.cache == true)
     ignoreCache = (options.cache == false)
 
-    request = u.only(options, 'url', 'method', 'data', 'selector', '_normalized')
+    request = u.only(options, 'url', 'method', 'data', 'selector', 'headers', '_normalized')
 
     pending = true
 
@@ -204,11 +219,11 @@ up.proxy = (($) ->
       # following case:
       #
       # - User starts preloading a request.
-      #   This triggers *no* `proxy:busy`.
+      #   This triggers *no* `up:proxy:busy`.
       # - User starts loading the request (without preloading).
-      #   This triggers `proxy:busy`.
+      #   This triggers `up:proxy:busy`.
       # - The request finishes.
-      #   This triggers `proxy:idle`.
+      #   This triggers `up:proxy:idle`.
       loadStarted()
       promise.always(loadEnded)
 
@@ -220,7 +235,7 @@ up.proxy = (($) ->
   Returns `true` if the proxy is not currently waiting
   for a request to finish. Returns `false` otherwise.
 
-  The proxy will also emit an `proxy:idle` [event](/up.bus) if it
+  The proxy will also emit an [`up:proxy:idle` event](/up:proxy:idle) if it
   used to busy, but is now idle.
 
   @function up.proxy.idle
@@ -233,8 +248,8 @@ up.proxy = (($) ->
   Returns `true` if the proxy is currently waiting
   for a request to finish. Returns `false` otherwise.
 
-  The proxy will also emit an `proxy:busy` [event](/up.bus) if it
-  used to idle, but is now busy.
+  The proxy will also emit an [`up:proxy:busy` event](/up:proxy:busy) if it
+  used to be idle, but is now busy.
 
   @function up.proxy.busy
   @return {Boolean} Whether the proxy is busy
@@ -285,7 +300,7 @@ up.proxy = (($) ->
   This event is [emitted]/(up.emit) when [AJAX requests](/up.proxy.ajax)
   have [taken long to finish](/up:proxy:busy), but have finished now.
 
-  @event up:proxy:busy
+  @event up:proxy:idle
   ###
 
   load = (request) ->