resources/src/jquery/jquery.confirmable.js

   1 /**
   2  * jQuery confirmable plugin
   3  *
   4  * Released under the MIT License.
   5  *
   6  * @author Bartosz Dziewoński
   7  *
   8  * @class jQuery.plugin.confirmable
   9  */
  10 ( function ( $ ) {
  11         var identity = function ( data ) {
  12                 return data;
  13         };
  14
  15         /**
  16          * Enable inline confirmation for given clickable element (like `<a />` or `<button />`).
  17          *
  18          * An additional inline confirmation step being shown before the default action is carried out on
  19          * click.
  20          *
  21          * Calling `.confirmable( { handler: function () { … } } )` will fire the handler only after the
  22          * confirmation step.
  23          *
  24          * The element will have the `jquery-confirmable-element` class added to it when it's clicked for
  25          * the first time, which has `white-space: nowrap;` and `display: inline-block;` defined in CSS.
  26          * If the computed values for the element are different when you make it confirmable, you might
  27          * encounter unexpected behavior.
  28          *
  29          * @param {Object} [options]
  30          * @param {string} [options.events='click'] Events to hook to.
  31          * @param {Function} [options.wrapperCallback] Callback to fire when preparing confirmable
  32          *     interface. Receives the interface jQuery object as the only parameter.
  33          * @param {Function} [options.buttonCallback] Callback to fire when preparing confirmable buttons.
  34          *     It is fired separately for the 'Yes' and 'No' button. Receives the button jQuery object as
  35          *     the first parameter and 'yes' or 'no' as the second.
  36          * @param {Function} [options.handler] Callback to fire when the action is confirmed (user clicks
  37          *     the 'Yes' button).
  38          * @param {string} [options.i18n] Text to use for interface elements.
  39          * @param {string} [options.i18n.space] Word separator to place between the three text messages.
  40          * @param {string} [options.i18n.confirm] Text to use for the confirmation question.
  41          * @param {string} [options.i18n.yes] Text to use for the 'Yes' button.
  42          * @param {string} [options.i18n.no] Text to use for the 'No' button.
  43          * @param {string} [options.i18n.yesTitle] Title text to use for the 'Yes' button.
  44          * @param {string} [options.i18n.noTitle] Title text to use for the 'No' button.
  45          *
  46          * @chainable
  47          */
  48         $.fn.confirmable = function ( options ) {
  49                 options = $.extend( true, {}, $.fn.confirmable.defaultOptions, options || {} );
  50
  51                 return this.on( options.events, function ( e ) {
  52                         var $element, $text, $buttonYes, $buttonNo, $wrapper, $interface, $elementClone,
  53                                 interfaceWidth, elementWidth, rtl, positionOffscreen, positionRestore, sideMargin;
  54
  55                         $element = $( this );
  56
  57                         if ( $element.data( 'jquery-confirmable-button' ) ) {
  58                                 // We're running on a clone of this element that represents the 'Yes' or 'No' button.
  59                                 // (This should never happen for the 'No' case unless calling code does bad things.)
  60                                 return;
  61                         }
  62
  63                         // Only prevent native event handling. Stopping other JavaScript event handlers
  64                         // is impossible because they might have already run (we have no control over the order).
  65                         e.preventDefault();
  66
  67                         rtl = $element.css( 'direction' ) === 'rtl';
  68                         if ( rtl ) {
  69                                 positionOffscreen = { position: 'absolute', right: '-9999px' };
  70                                 positionRestore = { position: '', right: '' };
  71                                 sideMargin = 'marginRight';
  72                         } else {
  73                                 positionOffscreen = { position: 'absolute', left: '-9999px' };
  74                                 positionRestore = { position: '', left: '' };
  75                                 sideMargin = 'marginLeft';
  76                         }
  77
  78                         if ( $element.hasClass( 'jquery-confirmable-element' ) ) {
  79                                 $wrapper = $element.closest( '.jquery-confirmable-wrapper' );
  80                                 $interface = $wrapper.find( '.jquery-confirmable-interface' );
  81                                 $text = $interface.find( '.jquery-confirmable-text' );
  82                                 $buttonYes = $interface.find( '.jquery-confirmable-button-yes' );
  83                                 $buttonNo = $interface.find( '.jquery-confirmable-button-no' );
  84
  85                                 interfaceWidth = $interface.data( 'jquery-confirmable-width' );
  86                                 elementWidth = $element.data( 'jquery-confirmable-width' );
  87                         } else {
  88                                 $elementClone = $element.clone( true );
  89                                 $element.addClass( 'jquery-confirmable-element' );
  90
  91                                 elementWidth = $element.width();
  92                                 $element.data( 'jquery-confirmable-width', elementWidth );
  93
  94                                 $wrapper = $( '<span>' )
  95                                         .addClass( 'jquery-confirmable-wrapper' );
  96                                 $element.wrap( $wrapper );
  97
  98                                 // Build the mini-dialog
  99                                 $text = $( '<span>' )
 100                                         .addClass( 'jquery-confirmable-text' )
 101                                         .text( options.i18n.confirm );
 102
 103                                 // Clone original element along with event handlers to easily replicate its behavior.
 104                                 // We could fiddle with .trigger() etc., but that is troublesome especially since
 105                                 // Safari doesn't implement .click() on <a> links and jQuery follows suit.
 106                                 $buttonYes = $elementClone.clone( true )
 107                                         .addClass( 'jquery-confirmable-button jquery-confirmable-button-yes' )
 108                                         .data( 'jquery-confirmable-button', true )
 109                                         .text( options.i18n.yes );
 110                                 if ( options.handler ) {
 111                                         $buttonYes.on( options.events, options.handler );
 112                                 }
 113                                 if ( options.i18n.yesTitle ) {
 114                                         $buttonYes.attr( 'title', options.i18n.yesTitle );
 115                                 }
 116                                 $buttonYes = options.buttonCallback( $buttonYes, 'yes' );
 117
 118                                 // Clone it without any events and prevent default action to represent the 'No' button.
 119                                 $buttonNo = $elementClone.clone( false )
 120                                         .addClass( 'jquery-confirmable-button jquery-confirmable-button-no' )
 121                                         .data( 'jquery-confirmable-button', true )
 122                                         .text( options.i18n.no )
 123                                         .on( options.events, function ( e ) {
 124                                                 $element.css( sideMargin, 0 );
 125                                                 $interface.css( 'width', 0 );
 126                                                 e.preventDefault();
 127                                         } );
 128                                 if ( options.i18n.noTitle ) {
 129                                         $buttonNo.attr( 'title', options.i18n.noTitle );
 130                                 } else {
 131                                         $buttonNo.removeAttr( 'title' );
 132                                 }
 133                                 $buttonNo = options.buttonCallback( $buttonNo, 'no' );
 134
 135                                 // Prevent memory leaks
 136                                 $elementClone.remove();
 137
 138                                 $interface = $( '<span>' )
 139                                         .addClass( 'jquery-confirmable-interface' )
 140                                         .append( $text, options.i18n.space, $buttonYes, options.i18n.space, $buttonNo );
 141                                 $interface = options.wrapperCallback( $interface );
 142
 143                                 // Render offscreen to measure real width
 144                                 $interface.css( positionOffscreen );
 145                                 // Insert it in the correct place while we're at it
 146                                 $element.after( $interface );
 147                                 interfaceWidth = $interface.width();
 148                                 $interface.data( 'jquery-confirmable-width', interfaceWidth );
 149                                 $interface.css( positionRestore );
 150
 151                                 // Hide to animate the transition later
 152                                 $interface.css( 'width', 0 );
 153                         }
 154
 155                         // Hide element, show interface. This triggers both transitions.
 156                         // In a timeout to trigger the 'width' transition.
 157                         setTimeout( function () {
 158                                 $element.css( sideMargin, -elementWidth );
 159                                 $interface.css( 'width', interfaceWidth );
 160                         }, 1 );
 161                 } );
 162         };
 163
 164         /**
 165          * Default options. Overridable primarily for internationalisation handling.
 166          * @property {Object} defaultOptions
 167          */
 168         $.fn.confirmable.defaultOptions = {
 169                 events: 'click',
 170                 wrapperCallback: identity,
 171                 buttonCallback: identity,
 172                 handler: null,
 173                 i18n: {
 174                         space: ' ',
 175                         confirm: 'Are you sure?',
 176                         yes: 'Yes',
 177                         no: 'No',
 178                         yesTitle: undefined,
 179                         noTitle: undefined
 180                 }
 181         };
 182 }( jQuery ) );