unpoly-rails 0.37.0 → 0.50.0

data/lib/assets/javascripts/unpoly/popup.coffee

@@ -5,7 +5,7 @@ Pop-up overlays
 Instead of [linking to a page fragment](/up.link), you can choose
 to show a fragment in a popup overlay that rolls down from an anchoring element.
 
-To open a popup, add an [`up-popup` attribute](/up-popup) to a link:
+To open a popup, add an [`up-popup` attribute](/a-up-popup) to a link:
 
     <a href="/options" up-popup=".menu">Show options</a>
 
@@ -22,7 +22,7 @@ The popup also closes *when a link within the popup changes a fragment behind th
 This is useful to have the popup interact with the page that
 opened it, e.g. by updating parts of a larger form.
 
-To disable this behavior, give the opening link an [`up-sticky`](/up-popup#up-sticky) attribute.
+To disable this behavior, give the opening link an [`up-sticky`](/a-up-popup#up-sticky) attribute.
 
 
 \#\#\# Customizing the popup design
@@ -53,25 +53,25 @@ up.popup = (($) ->
   Sets default options for future popups.
 
   @property up.popup.config
-  @param {String} [config.position='bottom-right']
+  @param {string} [config.position='bottom-right']
     Defines where the popup is attached to the opening element.
 
     Valid values are `bottom-right`, `bottom-left`, `top-right` and `top-left`.
-  @param {String} [config.history=false]
+  @param {string} [config.history=false]
     Whether opening a popup will add a browser history entry.
-  @param {String} [config.openAnimation='fade-in']
+  @param {string} [config.openAnimation='fade-in']
     The animation used to open a popup.
-  @param {String} [config.closeAnimation='fade-out']
+  @param {string} [config.closeAnimation='fade-out']
     The animation used to close a popup.
-  @param {String} [config.openDuration]
+  @param {string} [config.openDuration]
     The duration of the open animation (in milliseconds).
-  @param {String} [config.closeDuration]
+  @param {string} [config.closeDuration]
     The duration of the close animation (in milliseconds).
-  @param {String} [config.openEasing]
+  @param {string} [config.openEasing]
     The timing function controlling the acceleration of the opening animation.
-  @param {String} [config.closeEasing]
+  @param {string} [config.closeEasing]
     The timing function controlling the acceleration of the closing animation.
-  @param {Boolean} [options.sticky=false]
+  @param {boolean} [options.sticky=false]
     If set to `true`, the popup remains
     open even it changes the page in the background.
   @stable
@@ -92,7 +92,7 @@ up.popup = (($) ->
   Returns `undefined` if no  popup is open.
 
   @function up.popup.url
-  @return {String}
+  @return {string}
     the source URL
   @stable
   ###
@@ -101,7 +101,7 @@ up.popup = (($) ->
   Returns the URL of the page or modal behind the popup.
 
   @function up.popup.coveredUrl
-  @return {String}
+  @return {string}
   @experimental
   ###
 
@@ -173,7 +173,7 @@ up.popup = (($) ->
   Returns whether popup modal is currently open.
 
   @function up.popup.isOpen
-  @return {Boolean}
+  @return {boolean}
   @stable
   ###
   isOpen = ->
@@ -185,51 +185,46 @@ up.popup = (($) ->
   Emits events [`up:popup:open`](/up:popup:open) and [`up:popup:opened`](/up:popup:opened).
 
   @function up.popup.attach
-  @param {Element|jQuery|String} anchor
+  @param {Element|jQuery|string} anchor
     The element to which the popup will be attached.
-  @param {String} [options.url]
+  @param {string} [options.url]
     The URL from which to fetch the popup contents.
 
     If omitted, the `href` or `up-href` attribute of the anchor element will be used.
 
     Will be ignored if `options.html` is given.
-  @param {String} [options.target]
+  @param {string} [options.target]
     A CSS selector that will be extracted from the response and placed into the popup.
-  @param {String} [options.position='bottom-right']
+  @param {string} [options.position='bottom-right']
     Defines where the popup is attached to the opening element.
 
     Valid values are `bottom-right`, `bottom-left`, `top-right` and `top-left`.
-  @param {String} [options.html]
+  @param {string} [options.html]
     A string of HTML from which to extract the popup contents. No network request will be made.
-  @param {String} [options.confirm]
+  @param {string} [options.confirm]
     A message that will be displayed in a cancelable confirmation dialog
     before the modal is being opened.
-  @param {String} [options.animation]
+  @param {string} [options.animation]
     The animation to use when opening the popup.
-  @param {Number} [options.duration]
+  @param {number} [options.duration]
     The duration of the animation. See [`up.animate()`](/up.animate).
-  @param {Number} [options.delay]
+  @param {number} [options.delay]
     The delay before the animation starts. See [`up.animate()`](/up.animate).
-  @param {String} [options.easing]
+  @param {string} [options.easing]
     The timing function that controls the animation's acceleration. [`up.animate()`](/up.animate).
-  @param {String} [options.method="GET"]
+  @param {string} [options.method="GET"]
     Override the request method.
-  @param {Boolean} [options.sticky=false]
+  @param {boolean} [options.sticky=false]
     If set to `true`, the popup remains
     open even if the page changes in the background.
-  @param {Object} [options.history=false]
+  @param {boolean} [options.history=false]
   @return {Promise}
-    A promise that will be resolved when the popup has been loaded and
+    A promise that will be fulfilled when the popup has been loaded and
     the opening animation has completed.
   @stable
   ###
   attachAsap = (elementOrSelector, options) ->
-    curriedAttachNow = -> attachNow(elementOrSelector, options)
-    if isOpen()
-      chain.asap(closeNow, curriedAttachNow)
-    else
-      chain.asap(curriedAttachNow)
-    chain.promise()
+    chain.asap closeNow, (-> attachNow(elementOrSelector, options))
 
   attachNow = (elementOrSelector, options) ->
     $anchor = $(elementOrSelector)
@@ -238,6 +233,7 @@ up.popup = (($) ->
     options = u.options(options)
     url = u.option(u.pluckKey(options, 'url'), $anchor.attr('up-href'), $anchor.attr('href'))
     html = u.option(u.pluckKey(options, 'html'))
+    url or html or up.fail('up.popup.attach() requires either an { url } or { html } option')
     target = u.option(u.pluckKey(options, 'target'), $anchor.attr('up-popup'), 'body')
     position = u.option(options.position, $anchor.attr('up-position'), config.position)
     options.animation = u.option(options.animation, $anchor.attr('up-animation'), config.openAnimation)
@@ -246,8 +242,18 @@ up.popup = (($) ->
     options.confirm = u.option(options.confirm, $anchor.attr('up-confirm'))
     options.method = up.link.followMethod($anchor, options)
     options.layer = 'popup'
+    options.failTarget = u.option(options.failTarget, $anchor.attr('up-fail-target'))
     options.failLayer = u.option(options.failLayer, $anchor.attr('up-fail-layer'), 'auto')
+
+    # This will prevent up.replace() from looking for fallbacks, since
+    # it knows the target will always exist.
+    options.provideTarget = -> createHiddenFrame(target)
+
     animateOptions = up.motion.animateOptions(options, $anchor, duration: config.openDuration, easing: config.openEasing)
+    extractOptions = u.merge(options, animation: false)
+
+    if options.preload && url
+      return up.replace(target, url, options)
 
     up.browser.whenConfirmed(options).then ->
       up.bus.whenEmitted('up:popup:open', url: url, message: 'Opening popup').then ->
@@ -258,8 +264,6 @@ up.popup = (($) ->
           state.coveredUrl = up.browser.url()
           state.coveredTitle = document.title
         state.sticky = options.sticky
-        options.provideTarget = -> createHiddenFrame(target)
-        extractOptions = u.merge(options, animation: false)
         if html
           promise = up.extract(target, html, extractOptions)
         else
@@ -300,18 +304,16 @@ up.popup = (($) ->
   @param {Object} options
     See options for [`up.animate()`](/up.animate).
   @return {Promise}
-    A promise that will be resolved once the modal's close
+    A promise that will be fulfilled once the modal's close
     animation has finished.
   @stable
   ###
   closeAsap = (options) ->
-    if isOpen()
-      chain.asap -> closeNow(options)
-    chain.promise()
+    chain.asap -> closeNow(options)
 
   closeNow = (options) ->
     unless isOpen() # this can happen when a request fails and the chain proceeds to the next task
-      return u.resolvedPromise()
+      return Promise.resolve()
     
     options = u.options(options,
       animation: config.closeAnimation
@@ -334,6 +336,19 @@ up.popup = (($) ->
         state.sticky = null
         up.emit('up:popup:closed', message: 'Popup closed')
 
+  preloadNow = ($link, options) ->
+    options = u.options(options)
+    options.preload = true
+    # Use attachNow() and not attachAsap() so (1) we don't close a currently open popup
+    # and (2) our pending AJAX request does not prevent other popups from opening
+    attachNow($link, options)
+
+  toggleAsap = ($link, options) ->
+    if $link.is('.up-current')
+      closeAsap()
+    else
+      attachAsap($link, options)
+
   ###*
   This event is [emitted](/up.emit) when a popup dialog
   is starting to [close](/up.popup.close).
@@ -362,9 +377,9 @@ up.popup = (($) ->
   within the current popup.
 
   @methods up.popup.contains
-  @param {String} elementOrSelector
+  @param {string} elementOrSelector
     The element to test
-  @return {Boolean}
+  @return {boolean}
   @stable
   ###
   contains = (elementOrSelector) ->
@@ -382,23 +397,23 @@ up.popup = (($) ->
       <a href="/decks" up-popup=".deck_list">Switch deck</a>
       <a href="/settings" up-popup=".options" up-sticky>Settings</a>
 
-  @selector [up-popup]
-  @param {String} up-popup
+  @selector a[up-popup]
+  @param {string} up-popup
     The CSS selector that will be extracted from the response and
     displayed in a popup overlay.
   @param [up-position]
     Defines where the popup is attached to the opening element.
 
     Valid values are `bottom-right`, `bottom-left`, `top-right` and `top-left`.
-  @param {String} [up-confirm]
+  @param {string} [up-confirm]
     A message that will be displayed in a cancelable confirmation dialog
     before the popup is opened.
-  @param {String} [up-method='GET']
+  @param {string} [up-method='GET']
     Override the request method.
   @param [up-sticky]
     If set to `true`, the popup remains
     open even if the page changes in the background.
-  @param {String} [up-history='false']
+  @param {string} [up-history='false']
     Whether to push an entry to the browser history for the popup's source URL.
 
     Set this to `'false'` to prevent the URL bar from being updated.
@@ -406,11 +421,10 @@ up.popup = (($) ->
 
   @stable
   ###
-  up.link.onAction '[up-popup]', ($link) ->
-    if $link.is('.up-current')
-      closeAsap()
-    else
-      attachAsap($link)
+  up.link.addFollowVariant '[up-popup]',
+    # Don't just pass the `toggleAsap` function reference so we can stub it in tests
+    follow: ($link, options) -> toggleAsap($link, options)
+    preload: ($link, options) -> preloadNow($link, options)
 
   # We close the popup when someone clicks on the document.
   # We also need to listen to up:action:consumed in case an [up-instant] link

data/lib/assets/javascripts/unpoly/protocol.coffee

@@ -31,7 +31,6 @@ After the form's action performs a redirect, the next response should include th
 URL in the HTTP headers:
 
 ```http
-X-Up-Method: GET
 X-Up-Location: /current-url
 ```
 
@@ -40,8 +39,8 @@ The **simplest implementation** is to set these headers for every request.
 
 \#\#\# Optimizing responses
 
-When [updating a fragment](/up.link), Unpoly will send
-an additional HTTP header containing the CSS selector that is being replaced:
+When [updating a fragment](/up.link), Unpoly will send an
+additional HTTP header containing the CSS selector that is being replaced:
 
 ```http
 X-Up-Target: .user-list
@@ -51,6 +50,13 @@ Server-side code is free to **optimize its response** by only returning HTML
 that matches the selector. For example, you might prefer to not render an
 expensive sidebar if the sidebar is not targeted.
 
+Unpoly will often update a different selector in case the request fails.
+This selector is also included as a HTTP header:
+
+```
+X-Up-Fail-Target: body
+```
+
 
 \#\#\# Pushing a document title to the client
 
@@ -97,7 +103,7 @@ To do so in [Ruby on Rails](http://rubyonrails.org/), pass a [`:status` option t
 
 \#\#\# Detecting live form validations
 
-When [validating a form](/up-validate), Unpoly will
+When [validating a form](/input-up-validate), Unpoly will
 send an additional HTTP header containing a CSS selector for the form that is
 being updated:
 
@@ -144,7 +150,8 @@ This fixes two edge cases you might or might not care about:
 2. Some browsers have a bug where the initial request method is used for all
    subsequently pushed states. That means if the user reloads the page on a later
    GET state, the browser will wrongly attempt a POST request.
-   Modern Firefoxes, Chromes and IE10+ don't seem to be affected by this.
+   This issue affects Safari 9 and 10 (last tested in 2017-08).
+   Modern Firefoxes, Chromes and IE10+ don't have this behavior.
 
 In order to allow Unpoly to detect the HTTP method of the initial page load,
 the server must set a cookie:
@@ -205,38 +212,82 @@ up.protocol = (($) ->
   Configures strings used in the optional [server protocol](/up.protocol).
 
   @property up.protocol.config
-  @param [config.targetHeader='X-Up-Target']
-  @param [config.locationHeader='X-Up-Location']
-  @param [config.titleHeader='X-Up-Title']
-  @param [config.validateHeader='X-Up-Validate']
-  @param [config.methodHeader='X-Up-Method']
-  @param [config.methodCookie='_up_method']
-  @param [config.methodParam='_method']
+  @param {String} [config.targetHeader='X-Up-Target']
+  @param {String} [config.failTargetHeader='X-Up-Fail-Target']
+  @param {String} [config.locationHeader='X-Up-Location']
+  @param {String} [config.titleHeader='X-Up-Title']
+  @param {String} [config.validateHeader='X-Up-Validate']
+  @param {String} [config.methodHeader='X-Up-Method']
+  @param {String} [config.methodCookie='_up_method']
+    The name of the optional cookie the server can send to
+    [signal the initial request method](/up.protocol#signaling-the-initial-request-method).
+  @param {String} [config.methodParam='_method']
     The name of the POST parameter when [wrapping HTTP methods](/up.form.config#config.wrapMethods)
     in a `POST` request.
+  @param {String} [config.csrfHeader='X-CSRF-Token']
+    The name of the HTTP header that will include the
+    [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
+    for AJAX requests.
+  @param {String|Function} [config.csrfParam]
+    The `name` of the hidden `<input>` used for sending a
+    [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern) when
+    submitting a default, non-AJAX form. For AJAX request the token is sent as an HTTP header instead.
+
+    The parameter name can be configured as a string or as function that returns the parameter name.
+    If no name is set, no token will be sent.
+
+    Defaults to the `content` attribute of a `<meta>` tag named `csrf-token`:
+
+        <meta name="csrf-param" content="authenticity_token" />
+
+  @param {String|Function} [config.csrfToken]
+    The [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
+    to send for unsafe requests. The token will be sent as either a HTTP header (for AJAX requests)
+    or hidden form `<input>` (for default, non-AJAX form submissions).
+
+    The token can either be configured as a string or as function that returns the token.
+    If no token is set, no token will be sent.
+
+    Defaults to the `content` attribute of a `<meta>` tag named `csrf-token`:
+
+        <meta name='csrf-token' content='secret12345'>
+
   @experimental
   ###
   config = u.config
     targetHeader: 'X-Up-Target'
+    failTargetHeader: 'X-Up-Fail-Target'
     locationHeader: 'X-Up-Location'
     validateHeader: 'X-Up-Validate'
     titleHeader: 'X-Up-Title'
     methodHeader: 'X-Up-Method'
     methodCookie: '_up_method'
     methodParam: '_method'
+    csrfParam: -> $('meta[name="csrf-param"]').attr('content')
+    csrfToken: -> $('meta[name="csrf-token"]').attr('content')
+    csrfHeader: 'X-CSRF-Token'
 
-  ## Unfortunately we cannot offer reset without introducing cycles
+  csrfParam = ->
+    u.evalOption(config.csrfParam)
+
+  csrfToken = ->
+    u.evalOption(config.csrfToken)
+
+  ## Unfortunately we cannot offer reset via event without introducing cycles
   ## in the asset load order
   #
-  # reset = ->
-  #   config.reset()
-  #
   # up.on 'up:framework:reset', reset
 
+  reset = ->
+    config.reset()
+
   config: config
+  reset: reset
   locationFromXhr: locationFromXhr
   titleFromXhr: titleFromXhr
   methodFromXhr: methodFromXhr
+  csrfParam :csrfParam
+  csrfToken: csrfToken
   initialRequestMethod: initialRequestMethod
 
 )(jQuery)