unpoly-rails 0.20.0

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

@@ -0,0 +1,36 @@
+###*
+Play nice with Rails UJS
+========================
+###
+
+up.rails = (($) ->
+
+  u = up.util
+
+  willHandle = ($element) ->
+    $element.is('[up-follow], [up-target], [up-modal], [up-popup]')
+
+  isRails = ->
+    u.isGiven($.rails)
+
+  u.each ['method', 'confirm'], (feature) ->
+
+    dataAttribute = "data-#{feature}"
+    upAttribute = "up-#{feature}"
+
+    up.compiler "[#{dataAttribute}]", ($element) ->
+      if isRails() && willHandle($element)
+        replacement = {}
+        replacement[upAttribute] = $element.attr(dataAttribute)
+        u.setMissingAttrs($element, replacement)
+        $element.removeAttr(dataAttribute)
+
+  csrfField = ->
+    if isRails()
+      name: $.rails.csrfParam()
+      value: $.rails.csrfToken()
+
+  csrfField: csrfField
+  isRails: isRails
+
+)(jQuery)

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

@@ -0,0 +1,337 @@
+###*
+Enhancing elements
+==================
+
+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.
+
+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();
+    });
+
+Instead you should register a [`compiler`](/up.compiler) for the `a.lightbox` selector:
+
+    up.compiler('a.lightbox', function($element) {
+      $element.lightboxify();
+    });
+
+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.
+
+@class up.syntax
+###
+up.syntax = (($) ->
+  
+  u = up.util
+
+  DESTROYABLE_CLASS = 'up-destroyable'
+  DESTROYER_KEY = 'up-destroyer'
+
+
+  ###*
+  Registers a function to be called whenever an element with
+  the given selector is inserted into the DOM.
+
+      $('.action').compiler(function($element) {
+        // your code here
+      });
+
+  Compiler functions will be called on matching elements when
+  the page loads, or whenever a matching fragment is [updated through Unpoly](/up.replace)
+  later.
+
+  If you have used Angular.js before, this resembles
+  [Angular directives](https://docs.angularjs.org/guide/directive).
+
+
+  \#\#\#\# Integrating jQuery plugins
+
+  `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 `lightbox` class:
+
+      <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.lightbox', function($element) {
+        $element.lightboxify();
+      });
+
+
+  \#\#\#\# Custom elements
+
+  You can use `up.compiler` to implement custom elements like this:
+
+      <clock></clock>
+
+  Here is the Javascript that inserts the current time into to these elements:
+
+      up.compiler('clock', function($element) {
+        var now = new Date();
+        $element.text(now.toString()));
+      });
+
+
+  \#\#\#\# 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
+  will persist through many page loads, so it's important to not create
+  [memory leaks](https://makandracards.com/makandra/31325-how-to-create-memory-leaks-in-jquery).
+
+  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.
+
+  Here is a version of `<clock>` that updates
+  the time every second, and cleans up once it's done:
+
+      up.compiler('clock', function($element) {
+
+        function update() {
+          var now = new Date();
+          $element.text(now.toString()));
+        }
+
+        setInterval(update, 1000);
+
+        return function() {
+          clearInterval(update);
+        };
+
+      });
+
+  If we didn't clean up after ourselves, we would have many ticking intervals
+  operating on detached DOM elements after we have created and removed a couple
+  of `<clock>` elements.
+
+
+  \#\#\#\# 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.
+  For instance, a container for a [Google Map](https://developers.google.com/maps/documentation/javascript/tutorial)
+  might attach the location and names of its marker pins:
+
+      <div class="google-map" up-data="[
+        { lat: 48.36, lng: 10.99, title: 'Friedberg' },
+        { lat: 48.75, lng: 11.45, title: 'Ingolstadt' }
+      ]"></div>
+
+  The JSON will parsed and handed to your event handler as a second argument:
+
+      up.compiler('.google-map', function($element, pins) {
+
+        var map = new google.maps.Map($element);
+
+        pins.forEach(function(pin) {
+          var position = new google.maps.LatLng(pin.lat, pin.lng);
+          new google.maps.Marker({
+            position: position,
+            map: map,
+            title: pin.title
+          });
+        });
+
+      });
+
+
+  \#\#\#\# 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
+  this new syntax.
+
+  So if you had this before:
+
+      $(function() {
+        $('.action').on('click', function() {
+          $(this).something();
+        });
+      });
+
+  ... you can reuse the event handler like this:
+
+      $('.action').compiler(function($element) {
+        $element.on('click', function() {
+          $(this).something();
+        });
+      });
+
+  
+  @function up.compiler
+  @param {String} selector
+    The selector to match.
+  @param {Boolean} [options.batch=false]
+    If set to `true` and a fragment insertion contains multiple
+    elements matching the selector, `compiler` is only called once
+    with a jQuery collection containing all matching elements. 
+  @param {Boolean} [options.keep=false]
+    If set to `true` compiled fragment will be [persisted](/up-keep) during
+    [page updates](/a-up-target).
+
+    This has the same effect as setting an `up-keep` attribute on the element.
+  @param {Function($element, data)} compiler
+    The function to call when a matching element is inserted.
+    The function takes the new element as the first argument (as a jQuery object).
+    If the element has an `up-data` attribute, its value is parsed as JSON
+    and passed as a second argument.
+
+    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.
+    The destructor is *not* expected to remove the element from the DOM, which
+    is already handled by [`up.destroy`](/up.destroy).
+  @stable
+  ###
+  compilers = []
+
+  compiler = (selector, args...) ->
+    # Silently discard any compilers that are registered on unsupported browsers
+    return unless up.browser.isSupported()
+    compiler = args.pop()
+    options = u.options(args[0])
+    compilers.push
+      selector: selector
+      callback: compiler
+      batch: options.batch
+      keep: options.keep
+
+  applyCompiler = (compiler, $jqueryElement, nativeElement) ->
+    up.puts ("Compiling '%s' on %o" unless compiler.isDefault), compiler.selector, nativeElement
+    if compiler.keep
+      value = if u.isString(compiler.keep) then compiler.keep else ''
+      $jqueryElement.attr('up-keep', value)
+    destroyer = compiler.callback.apply(nativeElement, [$jqueryElement, data($jqueryElement)])
+    if u.isFunction(destroyer)
+      $jqueryElement.addClass(DESTROYABLE_CLASS)
+      $jqueryElement.data(DESTROYER_KEY, destroyer)
+
+  ###*
+  Applies all compilers on the given element and its descendants.
+  Unlike [`up.hello`](/up.hello), this doesn't emit any events.
+
+  @function up.syntax.compile
+  @param {Array<Element>} [options.skip]
+    A list of elements whose subtrees should not be compiled.
+  @internal
+  ###
+  compile = ($fragment, options) ->
+    options = u.options(options)
+    $skipSubtrees = $(options.skip)
+
+    up.log.group "Compiling fragment %o", $fragment.get(0), ->
+      for compiler in compilers
+        $matches = u.findWithSelf($fragment, compiler.selector)
+
+        $matches = $matches.filter ->
+          $match = $(this)
+          u.all $skipSubtrees, (element) ->
+            $match.closest(element).length == 0
+
+        if $matches.length
+          up.log.group ("Compiling '%s' on %d element(s)" unless compiler.isDefault), compiler.selector, $matches.length, ->
+            if compiler.batch
+              applyCompiler(compiler, $matches, $matches.get())
+            else
+              $matches.each -> applyCompiler(compiler, $(this), this)
+
+  ###*
+  Runs any destroyers on the given fragment and its descendants.
+  Unlike [`up.destroy`](/up.destroy), this doesn't emit any events
+  and does not remove the element from the DOM.
+
+  @function up.syntax.clean
+  @internal
+  ###
+  clean = ($fragment) ->
+    u.findWithSelf($fragment, ".#{DESTROYABLE_CLASS}").each ->
+      $element = $(this)
+      destroyer = $element.data(DESTROYER_KEY)
+      destroyer()
+
+  ###*
+  Checks if the given element has an `up-data` attribute.
+  If yes, parses the attribute value as JSON and returns the parsed object.
+
+  Returns an empty object if the element has no `up-data` attribute.
+
+  @function up.syntax.data
+  @param {String|Element|jQuery} elementOrSelector
+  @return
+    The JSON-decoded value of the `up-data` attribute.
+
+    Returns an empty object (`{}`) if the element has no (or an empty) `up-data` attribute.
+  @experimental
+  ###
+
+  ###
+  If an element annotated with [`up-data`] is inserted into the DOM,
+  Up will parse the JSON and pass the resulting object to any matching
+  [`up.compiler`](/up.syntax.compiler) handlers.
+
+  Similarly, when an event is triggered on an element annotated with
+  [`up-data`], the parsed object will be passed to any matching
+  [`up.on`](/up.on) handlers.
+
+  @selector [up-data]
+  @param {JSON} up-data
+    A serialized JSON string
+  @stable
+  ###
+  data = (elementOrSelector) ->
+    $element = $(elementOrSelector)
+    json = $element.attr('up-data')
+    if u.isString(json) && u.trim(json) != ''
+      JSON.parse(json)
+    else
+      {}
+
+  ###*
+  Makes a snapshot of the currently registered event listeners,
+  to later be restored through `reset`.
+  
+  @internal
+  ###
+  snapshot = ->
+    for compiler in compilers
+      compiler.isDefault = true
+
+  ###*
+  Resets the list of registered compiler directives to the
+  moment when the framework was booted.
+  
+  @internal
+  ###
+  reset = ->
+    compilers = u.select compilers, (compiler) -> compiler.isDefault
+
+  up.on 'up:framework:boot', snapshot
+  up.on 'up:framework:reset', reset
+
+  compiler: compiler
+  compile: compile
+  clean: clean
+  data: data
+
+)(jQuery)
+
+up.compiler = up.syntax.compiler
+
+up.ready = -> up.util.error('up.ready no longer exists. Please use up.hello instead.')
+up.awaken = -> up.util.error('up.awaken no longer exists. Please use up.compiler instead.')

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

@@ -0,0 +1,183 @@
+###*
+Tooltips
+========
+
+Unpoly comes with a basic tooltip implementation.
+
+You can an [`up-tooltip`](/up-tooltip) attribute to any HTML tag to show a tooltip whenever
+  the user hovers over the element:
+
+      <a href="/decks" up-tooltip="Show all decks">Decks</a>
+
+
+\#\#\#\# 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.
+A gray triangle points to the element.
+
+To change the styling, simply override CSS rules for the `.up-tooltip` selector and its `:after`
+selector that is used the triangle.
+
+The HTML of a tooltip element is simply this:
+
+    <div class="up-tooltip">
+      Show all decks
+    </div>
+
+The tooltip element is appended to the end of `<body>`.
+
+@class up.tooltip
+###
+up.tooltip = (($) ->
+  
+  u = up.util
+
+  ###*
+  Sets default options for future tooltips.
+
+  @property up.tooltip.config
+  @param {String} [config.position]
+    The default position of tooltips relative to the element.
+    Can be either `"top"` or `"bottom"`.
+  @param {String} [config.openAnimation='fade-in']
+    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'
+    openAnimation: 'fade-in'
+    closeAnimation: 'fade-out'
+
+  reset = ->
+    config.reset()
+
+  setPosition = ($link, $tooltip, position) ->
+    linkBox = u.measure($link)
+    tooltipBox = u.measure($tooltip)
+    css = switch position
+      when "top"
+        left: linkBox.left + 0.5 * (linkBox.width - tooltipBox.width)
+        top: linkBox.top - tooltipBox.height
+      when "bottom"
+        left: linkBox.left + 0.5 * (linkBox.width - tooltipBox.width)
+        top: linkBox.top + linkBox.height
+      else
+        u.error("Unknown position option '%s'", position)
+    $tooltip.attr('up-position', position)
+    $tooltip.css(css)
+
+  createElement = (options) ->
+    $element = u.$createElementFromSelector('.up-tooltip')
+    if u.isGiven(options.text)
+      $element.text(options.text)
+    else
+      $element.html(options.html)
+    $element.appendTo(document.body)
+    $element
+
+  ###*
+  Opens a tooltip over the given element.
+
+      up.tooltip.attach('.help', {
+        html: 'Enter multiple words or phrases'
+      });
+  
+  @function up.tooltip.attach
+  @param {Element|jQuery|String} elementOrSelector
+  @param {String} [options.html]
+    The HTML to display in the tooltip.
+  @param {String} [options.position='top']
+    The position of the tooltip. Known values are `top` and `bottom`.
+  @param {String} [options.animation]
+    The animation to use when opening the tooltip.
+  @return {Promise}
+    A promise that will be resolved when the tooltip's opening animation has finished.
+  @stable
+  ###
+  attach = (linkOrSelector, options = {}) ->
+    $link = $(linkOrSelector)
+    html = u.option(options.html, $link.attr('up-tooltip-html'))
+    text = u.option(options.text, $link.attr('up-tooltip'))
+    position = u.option(options.position, $link.attr('up-position'), config.position)
+    animation = u.option(options.animation, u.castedAttr($link, 'up-animation'), config.openAnimation)
+    animateOptions = up.motion.animateOptions(options, $link)
+    close()
+    $tooltip = createElement(text: text, html: html)
+    setPosition($link, $tooltip, position)
+    up.animate($tooltip, animation, animateOptions)
+
+  ###*
+  Closes a currently shown tooltip.
+  Does nothing if no tooltip is currently shown.
+  
+  @function up.tooltip.close
+  @param {Object} options
+    See options for [`up.animate`](/up.animate).
+  @stable
+  ###
+  close = (options) ->
+    $tooltip = $('.up-tooltip')
+    if $tooltip.length
+      options = u.options(options, animation: config.closeAnimation)
+      options = u.merge(options, up.motion.animateOptions(options))
+      up.destroy($tooltip, options)
+
+  ###*
+  Displays a tooltip with text content when hovering the mouse over this element:
+
+      <a href="/decks" up-tooltip="Show all decks">Decks</a>
+
+  To make the tooltip appear below the element instead of above the element,
+  add an `up-position` attribute:
+
+      <a href="/decks" up-tooltip="Show all decks" up-position="bottom">Decks</a>
+
+  @selector [up-tooltip]
+  @param {String} [up-animation]
+    The animation used to open the tooltip.
+    Defaults to [`up.tooltip.config.openAnimation`](/up.tooltip.config).
+  @param {String} [up-position]
+    The default position of tooltips relative to the element.
+    Can be either `"top"` or `"bottom"`.
+    Defaults to [`up.tooltip.config.position`](/up.tooltip.config).
+  @stable
+  ###
+
+  ###*
+  Displays a tooltip with HTML content when hovering the mouse over this element:
+
+      <a href="/decks" up-tooltip-html="Show &lt;b&gt;all&lt;/b&gt; decks">Decks</a>
+
+  @selector [up-tooltip-html]
+  @stable
+  ###
+  up.compiler('[up-tooltip], [up-tooltip-html]', ($link) ->
+    # Don't register these events on document since *every*
+    # mouse move interaction  bubbles up to the document. 
+    $link.on('mouseover', -> attach($link))
+    $link.on('mouseout', -> close())
+  )
+
+  # Close the tooltip when someone clicks anywhere.
+  up.on('click', 'body', (event, $body) ->
+    close()
+  )
+
+  # The framework is reset between tests, so also close
+  # a currently open tooltip.
+  up.on 'up:framework:reset', close
+
+  # Close the tooltip when the user presses ESC.
+  up.bus.onEscape(-> close())
+
+  # The framework is reset between tests
+  up.on 'up:framework:reset', reset
+
+  attach: attach
+  close: close
+  open: -> u.error('up.tooltip.open no longer exists. Use up.tooltip.attach instead.')
+
+)(jQuery)