popup.js.coffee in upjs-rails-0.15.0

- old
+ new

@@ -1,18 +1,17 @@
 ###*
 Pop-up overlays
 ===============
 
 Instead of [linking to a page fragment](/up.link), you can choose
-to show a fragment in a popup overlay.
+to show a fragment in a popup overlay that rolls down from an anchoring element.
 
 To open a popup, add an [`up-popup` attribute](/a-up-popup) to a link,
 or call the Javascript function [`up.popup.attach`](/up.popup.attach).
 
 For modal dialogs see [up.modal](/up.modal) instead.
 
-
 \#\#\#\# Customizing the popup design
 
 Loading the Up.js stylesheet will give you a minimal popup design:
 
 - Popup contents are displayed in a white box
@@ -25,11 +24,10 @@
 
     <div class="up-popup">
       ...
     </div>
 
-
 \#\#\#\# Closing behavior
 
 The popup closes when the user clicks anywhere outside the popup area.
 
 By default the popup also closes
@@ -40,11 +38,10 @@
 
 To disable this behavior, give the opening link an `up-sticky` attribute:
 
     <a href="/settings" up-popup=".options" up-sticky>Settings</a>
 
-  
 @class up.popup
 ###
 up.popup = (($) ->
 
   u = up.util
@@ -162,14 +159,18 @@
     $popup
     
   updated = ($link, $popup, position, animation, animateOptions) ->
     $popup.show()
     setPosition($link, $popup, position)
-    up.animate($popup, animation, animateOptions)
+    deferred = up.animate($popup, animation, animateOptions)
+    deferred.then -> up.emit('up:popup:opened')
+    deferred
     
   ###*
   Attaches a popup overlay to the given element or selector.
+
+  Emits events [`up:popup:open`](/up:popup:open) and [`up:popup:opened`](/up:popup:opened).
   
   @function up.popup.attach
   @param {Element|jQuery|String} elementOrSelector
   @param {String} [options.url]
   @param {String} [options.position='bottom-right']
@@ -200,38 +201,92 @@
     sticky = u.option(options.sticky, u.castedAttr($link, 'up-sticky'))
     history = if up.browser.canPushState() then u.option(options.history, u.castedAttr($link, 'up-history'), false) else false
     animateOptions = up.motion.animateOptions(options, $link)
 
     close()
-    $popup = createHiddenPopup($link, selector, sticky)
-    
-    up.replace(selector, url,
-      history: history
-      insert: -> updated($link, $popup, position, animation, animateOptions)
-    )
-    
+
+    if up.bus.nobodyPrevents('up:popup:open', url: url)
+      $popup = createHiddenPopup($link, selector, sticky)
+
+      up.replace(selector, url,
+        history: history
+        insert: -> updated($link, $popup, position, animation, animateOptions)
+      )
+    else
+      # Although someone prevented the destruction, keep a uniform API for
+      # callers by returning a Deferred that will never be resolved.
+      u.unresolvableDeferred()
+
   ###*
+  This event is [emitted](/up.emit) when a popup is starting to open.
+
+  @event up:popup:open
+  @param event.preventDefault()
+    Event listeners may call this method to prevent the popup from opening.
+  @stable
+  ###
+
+  ###*
+  This event is [emitted](/up.emit) when a popup has finished opening.
+
+  @event up:popup:opened
+  @stable
+  ###
+      
+  ###*
   Closes a currently opened popup overlay.
+
   Does nothing if no popup is currently open.
-  
+
+  Emits events [`up:popup:close`](/up:popup:close) and [`up:popup:closed`](/up:popup:closed).
+
   @function up.popup.close
   @param {Object} options
     See options for [`up.animate`](/up.animate).
+  @return {Deferred}
+    A promise that will be resolved once the modal's close
+    animation has finished.
   @stable
   ###
   close = (options) ->
     $popup = $('.up-popup')
     if $popup.length
-      options = u.options(options,
-        animation: config.closeAnimation,
-        url: $popup.attr('up-covered-url'),
-        title: $popup.attr('up-covered-title')
-      )
-      currentUrl = undefined
-      up.destroy($popup, options)
+      if up.bus.nobodyPrevents('up:popup:close', $element: $popup)
+        options = u.options(options,
+          animation: config.closeAnimation,
+          url: $popup.attr('up-covered-url'),
+          title: $popup.attr('up-covered-title')
+        )
+        currentUrl = undefined
+        deferred = up.destroy($popup, options)
+        deferred.then -> up.emit('up:popup:closed')
+        deferred
+      else
+        # Although someone prevented the destruction,
+        # keep a uniform API for callers by returning
+        # a Deferred that will never be resolved.
+        u.unresolvableDeferred()
     else
-      u.resolvedPromise()
-    
+      u.resolvedDeferred()
+
+  ###*
+  This event is [emitted](/up.emit) when a popup dialog
+  is starting to [close](/up.popup.close).
+
+  @event up:popup:close
+  @param event.preventDefault()
+    Event listeners may call this method to prevent the popup from closing.
+  @stable
+  ###
+
+  ###*
+  This event is [emitted](/up.emit) when a popup dialog
+  is done [closing](/up.popup.close).
+
+  @event up:popup:closed
+  @stable
+  ###
+      
   autoclose = ->
     unless $('.up-popup').is('[up-sticky]')
       discardHistory()
       close()
 