unpoly-rails 0.28.1 → 0.29.0

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

@@ -150,7 +150,7 @@ up.proxy = (($) ->
   Only requests with a method of `GET`, `OPTIONS` and `HEAD`
   are considered to be read-only.
 
-  \#\#\#\# Example
+  \#\#\# Example
 
       up.ajax('/search', data: { query: 'sunshine' }).then(function(data, status, xhr) {
         console.log('The response body is %o', data);
@@ -158,7 +158,7 @@ up.proxy = (($) ->
         console.error('The request failed');
       });
 
-  \#\#\#\# Events
+  \#\#\# Events
 
   If a network connection is attempted, the proxy will emit
   a [`up:proxy:load`](/up:proxy:load) event with the `request` as its argument.
@@ -296,7 +296,7 @@ up.proxy = (($) ->
   waiting, **no** additional `up:proxy:slow` events will be triggered.
 
 
-  \#\#\#\# Spinners
+  \#\#\# Spinners
 
   You can [listen](/up.on) to the `up:proxy:slow`
   and [`up:proxy:recover`](/up:proxy:recover) events to implement a spinner

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

@@ -1,34 +1,21 @@
 ###*
-Enhancing elements
-==================
+Custom Javascript
+=================
 
-Unpoly keeps a persistent Javascript environment during page transitions.
-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.
+Every app needs a way to pair Javascript snippets with certain HTML elements,
+in order to integrate libraries or implement custom behavior.
 
-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:
+Unpoly lets you organize your Javascript snippets using [compilers](/up.compiler).
 
-    <a href="river.png" class="lightbox">River</a>
-    <a href="ocean.png" class="lightbox">Ocean</a>
+For instance, to activate the [Masonry](http://masonry.desandro.com/) jQuery plugin for every element
+with a `grid` class, use this compiler:
 
-You should **avoid** doing this on page load:
-
-    $(document).on('ready', function() {
-      $('a.lightbox').lightboxify();
-    });
-
-Instead you should register a [`compiler`](/up.compiler) for the `a.lightbox` selector:
-
-    up.compiler('a.lightbox', function($element) {
-      $element.lightboxify();
+    up.compiler('.grid', function($element) {
+      $element.masonry();
     });
 
-The compiler function will be called on matching elements when
-the page loads, or whenever a matching fragment is [updated through Unpoly](/up.replace)
-later.
+The compiler function will be called on matching elements when the page loads
+or when a matching fragment is [inserted via AJAX](/up.link) later.
 
 @class up.syntax
 ###
@@ -58,7 +45,7 @@ up.syntax = (($) ->
   [Angular directives](https://docs.angularjs.org/guide/directive).
 
 
-  \#\#\#\# Integrating jQuery plugins
+  \#\#\# Integrating jQuery plugins
 
   `up.compiler` is a great way to integrate jQuery plugins.
   Let's say your Javascript plugin wants you to call `lightboxify()`
@@ -75,7 +62,7 @@ up.syntax = (($) ->
       });
 
 
-  \#\#\#\# Custom elements
+  \#\#\# Custom elements
 
   You can use `up.compiler` to implement custom elements like this:
 
@@ -89,7 +76,7 @@ up.syntax = (($) ->
       });
 
 
-  \#\#\#\# Cleaning up after yourself
+  \#\#\# Cleaning up after yourself
 
   If your compiler returns a function, Unpoly will use this as a *destructor* to
   clean up if the element leaves the DOM. Note that in Unpoly the same DOM ad Javascript environment
@@ -98,7 +85,7 @@ up.syntax = (($) ->
 
   You should clean up after yourself whenever your compilers have global
   side effects, like a [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setInterval)
-  or event handlers bound to the document root.
+  or [event handlers bound to the document root](/up.on).
 
   Here is a version of `<clock>` that updates
   the time every second, and cleans up once it's done. Note how it returns
@@ -124,7 +111,7 @@ up.syntax = (($) ->
   of `<clock>` elements.
 
 
-  \#\#\#\# Attaching structured data
+  \#\#\# Attaching structured data
 
   In case you want to attach structured data to the event you're observing,
   you can serialize the data to JSON and put it into an `[up-data]` attribute.
@@ -154,7 +141,7 @@ up.syntax = (($) ->
       });
 
 
-  \#\#\#\# Migrating jQuery event handlers to `up.compiler`
+  \#\#\# Migrating jQuery event handlers to `up.compiler`
 
   Within the compiler, Unpoly will bind `this` to the
   native DOM element to help you migrate your existing jQuery code to
@@ -201,9 +188,12 @@ up.syntax = (($) ->
 
     The function may return a destructor function that destroys the compiled
     object before it is removed from the DOM. The destructor is supposed to
-    clear global state such as time-outs and event handlers bound to the document.
+    [clear global state](/up.compiler#cleaning-up-after-yourself)
+    such as timeouts and event handlers bound to the document.
     The destructor is *not* expected to remove the element from the DOM, which
     is already handled by [`up.destroy`](/up.destroy).
+
+    The function may also return an array of destructor functions.
   @stable
   ###
   compiler = (args...) ->
@@ -214,7 +204,7 @@ up.syntax = (($) ->
 
   You can use `up.macro` to register a compiler that sets other UJS attributes.
 
-  \#\#\#\# Example
+  \#\#\# Example
 
   You will sometimes find yourself setting the same combination of UJS attributes again and again:
 
@@ -281,14 +271,16 @@ up.syntax = (($) ->
       value = if u.isString(compiler.keep) then compiler.keep else ''
       $jqueryElement.attr('up-keep', value)
     returnValue = compiler.callback.apply(nativeElement, [$jqueryElement, data($jqueryElement)])
-    if destructor = discoverDestructor(returnValue)
+    for destructor in discoverDestructors(returnValue)
       addDestructor($jqueryElement, destructor)
 
-  discoverDestructor = (returnValue) ->
+  discoverDestructors = (returnValue) ->
     if u.isFunction(returnValue)
-      returnValue
+      [returnValue]
     else if u.isArray(returnValue) && u.all(returnValue, u.isFunction)
-      u.sequence(returnValue...)
+      returnValue
+    else
+      []
 
   addDestructor = ($jqueryElement, destructor) ->
     $jqueryElement.addClass(DESTRUCTABLE_CLASS)
@@ -348,7 +340,7 @@ up.syntax = (($) ->
 
   Returns an empty object if the element has no `up-data` attribute.
 
-  \#\#\#\# Example
+  \#\#\# Example
 
   You have an element with JSON data serialized into an `up-data` attribute:
 

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

@@ -10,7 +10,7 @@ You can an [`up-tooltip`](/up-tooltip) attribute to any HTML tag to show a toolt
       <a href="/decks" up-tooltip="Show all decks">Decks</a>
 
 
-\#\#\#\# Styling
+\#\#\# Styling
 
 The [default styles](https://github.com/unpoly/unpoly/blob/master/lib/assets/stylesheets/up/tooltip.css.sass)
 show a simple tooltip with white text on a gray background.
@@ -125,8 +125,16 @@ up.tooltip = (($) ->
 
   @function up.tooltip.attach
   @param {Element|jQuery|String} elementOrSelector
+  @param {String} [options.text]
+    The text to display in the tooltip.
+
+    Any HTML control characters will be escaped.
+    If you need to use HTML formatting in the tooltip, use `options.html` instead.
   @param {String} [options.html]
-    The HTML to display in the tooltip.
+    The HTML to display in the tooltip unescaped.
+
+    Make sure to escape any user-provided text before passing it as this option,
+    or use `options.text` (which automatically escapes).
   @param {String} [options.position='top']
     The position of the tooltip.
     Can be `'top'`, `'right'`, `'bottom'` or `'left'`.
@@ -228,20 +236,21 @@ up.tooltip = (($) ->
   @selector [up-tooltip-html]
   @stable
   ###
-  up.compiler('[up-tooltip], [up-tooltip-html]', ($opener) ->
+  up.compiler '[up-tooltip], [up-tooltip-html]', ($opener) ->
     # Don't register these events on document since *every*
     # mouse move interaction  bubbles up to the document. 
     $opener.on('mouseenter', -> attachAsap($opener))
     $opener.on('mouseleave', -> closeAsap())
-  )
 
-  # Close the tooltip when someone clicks anywhere.
-  up.on('click', 'body', (event, $body) ->
+  # We close the tooltip when someone clicks on the document.
+  # We also need to listen to up:action:consumed in case an [up-instant] link
+  # was followed on mousedown.
+  up.on 'click up:action:consumed', (event) ->
     closeAsap()
-  )
+    # Do not halt the event chain here. The user is allowed to directly activate
+    # a link in the background, even with a (now closing) tooltip open.
 
-  # The framework is reset between tests, so also close
-  # a currently open tooltip.
+  # The framework is reset between tests, so also close a currently open tooltip.
   up.on 'up:framework:reset', reset
 
   # Close the tooltip when the user presses ESC.

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

@@ -829,8 +829,8 @@ up.util = (($) ->
       position:  'absolute'
       top:       '0'
       left:      '0'
-      width:     '50px'
-      height:    '50px'
+      width:     '100px'
+      height:    '100px' # Firefox needs at least 100px to show a scrollbar
       overflowY: 'scroll'
     $outer.appendTo(document.body)
     outer = $outer.get(0)
@@ -1668,19 +1668,26 @@ up.util = (($) ->
     data
 
   ###*
-  Throws an [exception](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
+  Throws a [Javascript error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
   with the given message.
 
-  The message will also be printed to the [error log](/up.log.error).
+  The message will also be printed to the [error log](/up.log.error). Also a notification will be shown at the bottom of the screen.
 
-  Also a notification will be shown at the bottom of the screen.
+  The message may contain [substitution marks](https://developer.mozilla.org/en-US/docs/Web/API/console#Using_string_substitutions).
 
-  \#\#\#\# Examples
+  \#\#\# Examples
 
       up.fail('Division by zero')
       up.fail('Unexpected result %o', result)
 
   @function up.fail
+  @param {String} message
+    A message with details about the error.
+
+    The message can contain [substitution marks](https://developer.mozilla.org/en-US/docs/Web/API/console#Using_string_substitutions)
+    like `%s` or `%o`.
+  @param {Array<String>} vars...
+    A list of variables to replace any substitution marks in the error message.
   @experimental
   ###
   fail = (args...) ->
@@ -1833,7 +1840,7 @@ up.util = (($) ->
   @function up.util.sequence
   @internal
   ###
-  sequence: (functions...) ->
+  sequence = (functions...) ->
     ->
       map functions, (f) -> f()
 
@@ -1944,6 +1951,7 @@ up.util = (($) ->
   escapeHtml: escapeHtml
   DivertibleChain: DivertibleChain
   submittedValue: submittedValue
+  sequence: sequence
 
 )($)
 

data/lib/unpoly/rails/version.rb

@@ -4,6 +4,6 @@ module Unpoly
     # The current version of the unpoly-rails gem.
     # This version number is also used for releases of the Unpoly
     # frontend code.
-    VERSION = '0.28.1'
+    VERSION = '0.29.0'
   end
 end

data/spec_app/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    unpoly-rails (0.27.3)
+    unpoly-rails (0.28.1)
       rails (>= 3)
 
 GEM

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

@@ -18,6 +18,11 @@
     event = createMouseEvent('click', options)
     dispatch($element, event)
 
+  clickSequence = ($element, options) ->
+    mousedown($element, options)
+    mouseup($element, options)
+    click($element, options)
+
   # Can't use the new MouseEvent constructor in IE11 because computer.
   # http://www.codeproject.com/Tips/893254/JavaScript-Triggering-Event-Manually-in-Internet-E
   createMouseEvent = (type, options) ->
@@ -64,5 +69,6 @@
   mousedown: mousedown
   mouseup: mouseup
   click: click
+  clickSequence: clickSequence
   
 )()

data/spec_app/spec/javascripts/up/bus_spec.js.coffee

@@ -11,8 +11,8 @@ describe 'up.bus', ->
         up.on 'click', '.child', (event, $element) ->
           observeClass($element.attr('class'))
 
-        $('.container').click()
-        $('.child').click()
+        Trigger.click($('.container'))
+        Trigger.click($('.child'))
 
         expect(observeClass).not.toHaveBeenCalledWith('container')
         expect(observeClass).toHaveBeenCalledWith('child')
@@ -21,9 +21,10 @@ describe 'up.bus', ->
         $child = affix('.child')
         clickSpy = jasmine.createSpy()
         unsubscribe = up.on 'click', '.child', clickSpy
-        $('.child').click()
+        Trigger.click($('.child'))
+        expect(clickSpy.calls.count()).toEqual(1)
         unsubscribe()
-        $('.child').click()
+        Trigger.click($('.child'))
         expect(clickSpy.calls.count()).toEqual(1)
 
       it 'parses an up-data attribute as JSON and passes the parsed object as a third argument to the initializer', ->
@@ -35,7 +36,7 @@ describe 'up.bus', ->
         data = { key1: 'value1', key2: 'value2' }
         $tag = affix(".child").attr('up-data', JSON.stringify(data))
 
-        $('.child').click()
+        Trigger.click($('.child'))
         expect(observeArgs).toHaveBeenCalledWith('child', data)
 
       it 'passes an empty object as a second argument to the listener if there is no up-data attribute', ->
@@ -44,7 +45,7 @@ describe 'up.bus', ->
         up.on 'click', '.child', (event, $element, data) ->
           observeArgs($element.attr('class'), data)
 
-        $('.child').click()
+        Trigger.click($('.child'))
         expect(observeArgs).toHaveBeenCalledWith('child', {})
 
     describe 'up.off', ->
@@ -53,9 +54,9 @@ describe 'up.bus', ->
         $child = affix('.child')
         clickSpy = jasmine.createSpy()
         up.on 'click', '.child', clickSpy
-        $('.child').click()
+        Trigger.click($('.child'))
         up.off 'click', '.child', clickSpy
-        $('.child').click()
+        Trigger.click($('.child'))
         expect(clickSpy.calls.count()).toEqual(1)
 
       it 'throws an error if the given event listener was not registered through up.on', ->

data/spec_app/spec/javascripts/up/form_spec.js.coffee

@@ -69,11 +69,11 @@ describe 'up.form', ->
             callback = jasmine.createSpy('change callback')
             up.observe($checkbox, callback)
             expect($checkbox.is(':checked')).toBe(false)
-            $checkbox.get(0).click()
+            Trigger.clickSequence($checkbox)
             u.nextFrame ->
               expect($checkbox.is(':checked')).toBe(true)
               expect(callback.calls.count()).toEqual(1)
-              $checkbox.get(0).click()
+              Trigger.clickSequence($checkbox)
               u.nextFrame ->
                 expect($checkbox.is(':checked')).toBe(false)
                 expect(callback.calls.count()).toEqual(2)
@@ -86,11 +86,11 @@ describe 'up.form', ->
             callback = jasmine.createSpy('change callback')
             up.observe($checkbox, callback)
             expect($checkbox.is(':checked')).toBe(false)
-            $label.get(0).click()
+            Trigger.clickSequence($label)
             u.nextFrame ->
               expect($checkbox.is(':checked')).toBe(true)
               expect(callback.calls.count()).toEqual(1)
-              $label.get(0).click()
+              Trigger.clickSequence($label)
               u.nextFrame ->
                 expect($checkbox.is(':checked')).toBe(false)
                 expect(callback.calls.count()).toEqual(2)
@@ -106,11 +106,11 @@ describe 'up.form', ->
             callback = jasmine.createSpy('change callback')
             up.observe($group, callback)
             expect($radio1.is(':checked')).toBe(false)
-            $radio1.get(0).click()
+            Trigger.clickSequence($radio1)
             u.nextFrame ->
               expect($radio1.is(':checked')).toBe(true)
               expect(callback.calls.count()).toEqual(1)
-              $radio2.get(0).click()
+              Trigger.clickSequence($radio2)
               u.nextFrame ->
                 expect($radio1.is(':checked')).toBe(false)
                 expect(callback.calls.count()).toEqual(2)
@@ -126,11 +126,11 @@ describe 'up.form', ->
             callback = jasmine.createSpy('change callback')
             up.observe($group, callback)
             expect($radio1.is(':checked')).toBe(false)
-            $radio1Label.get(0).click()
+            Trigger.clickSequence($radio1Label)
             u.nextFrame ->
               expect($radio1.is(':checked')).toBe(true)
               expect(callback.calls.count()).toEqual(1)
-              $radio2Label.get(0).click()
+              Trigger.clickSequence($radio2Label)
               u.nextFrame ->
                 expect($radio1.is(':checked')).toBe(false)
                 expect(callback.calls.count()).toEqual(2)
@@ -145,14 +145,14 @@ describe 'up.form', ->
             up.observe($group, callback)
             expect($radio1.is(':checked')).toBe(true)
             expect($radio2.is(':checked')).toBe(false)
-            $radio1.get(0).click()
+            Trigger.clickSequence($radio1)
             u.nextFrame ->
               # Since the radio button was already checked, the click doesn't do anything
               expect($radio1.is(':checked')).toBe(true)
               expect($radio2.is(':checked')).toBe(false)
               # Since the radio button was already checked, clicking it again won't trigger the callback
               expect(callback.calls.count()).toEqual(0)
-              $radio2.get(0).click()
+              Trigger.clickSequence($radio2)
               u.nextFrame ->
                 expect($radio1.is(':checked')).toBe(false)
                 expect($radio2.is(':checked')).toBe(true)