X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/6c8f14c09105d0afa4c1574215c59b5021040e76..refs/tags/wordpress-4.2:/wp-includes/js/customize-loader.js

diff --git a/wp-includes/js/customize-loader.js b/wp-includes/js/customize-loader.js
index 2ecbbe0f..ce69a359 100644
--- a/wp-includes/js/customize-loader.js
+++ b/wp-includes/js/customize-loader.js
@@ -1,3 +1,4 @@
+/* global _wpCustomizeLoaderSettings, confirm */
 window.wp = window.wp || {};
 
 (function( exports, $ ){
@@ -9,7 +10,20 @@ window.wp = window.wp || {};
 		hashchange: ('onhashchange' in window) && (document.documentMode === undefined || document.documentMode > 7)
 	});
 
+	/**
+	 * Allows the Customizer to be overlayed on any page.
+	 *
+	 * By default, any element in the body with the load-customize class will open
+	 * an iframe overlay with the URL specified.
+	 *
+	 *     e.g. <a class="load-customize" href="<?php echo wp_customize_url(); ?>">Open Customizer</a>
+	 *
+	 * @augments wp.customize.Events
+	 */
 	Loader = $.extend( {}, api.Events, {
+		/**
+		 * Setup the Loader; triggered on document#ready.
+		 */
 		initialize: function() {
 			this.body = $( document.body );
 
@@ -22,21 +36,25 @@ window.wp = window.wp || {};
 			this.window  = $( window );
 			this.element = $( '<div id="customize-container" />' ).appendTo( this.body );
 
+			// Bind events for opening and closing the overlay.
 			this.bind( 'open', this.overlay.show );
 			this.bind( 'close', this.overlay.hide );
 
+			// Any element in the body with the `load-customize` class opens
+			// the Customizer.
 			$('#wpbody').on( 'click', '.load-customize', function( event ) {
 				event.preventDefault();
 
-				// Store a reference to the link that opened the customizer.
+				// Store a reference to the link that opened the Customizer.
 				Loader.link = $(this);
 				// Load the theme.
 				Loader.open( Loader.link.attr('href') );
 			});
 
 			// Add navigation listeners.
-			if ( $.support.history )
+			if ( $.support.history ) {
 				this.window.on( 'popstate', Loader.popstate );
+			}
 
 			if ( $.support.hashchange ) {
 				this.window.on( 'hashchange', Loader.hashchange );
@@ -46,36 +64,57 @@ window.wp = window.wp || {};
 
 		popstate: function( e ) {
 			var state = e.originalEvent.state;
-			if ( state && state.customize )
+			if ( state && state.customize ) {
 				Loader.open( state.customize );
-			else if ( Loader.active )
+			} else if ( Loader.active ) {
 				Loader.close();
+			}
 		},
 
-		hashchange: function( e ) {
+		hashchange: function() {
 			var hash = window.location.toString().split('#')[1];
 
-			if ( hash && 0 === hash.indexOf( 'wp_customize=on' ) )
+			if ( hash && 0 === hash.indexOf( 'wp_customize=on' ) ) {
 				Loader.open( Loader.settings.url + '?' + hash );
+			}
 
-			if ( ! hash && ! $.support.history )
+			if ( ! hash && ! $.support.history ) {
 				Loader.close();
+			}
+		},
+
+		beforeunload: function () {
+			if ( ! Loader.saved() ) {
+				return Loader.settings.l10n.saveAlert;
+			}
 		},
 
+		/**
+		 * Open the Customizer overlay for a specific URL.
+		 *
+		 * @param  string src URL to load in the Customizer.
+		 */
 		open: function( src ) {
-			var hash;
 
-			if ( this.active )
+			if ( this.active ) {
 				return;
+			}
 
 			// Load the full page on mobile devices.
-			if ( Loader.settings.browser.mobile )
+			if ( Loader.settings.browser.mobile ) {
 				return window.location = src;
+			}
+
+			// Store the document title prior to opening the Live Preview
+			this.originalDocumentTitle = document.title;
 
 			this.active = true;
 			this.body.addClass('customize-loading');
 
-			this.iframe = $( '<iframe />', { src: src }).appendTo( this.element );
+			// Dirty state of Customizer in iframe
+			this.saved = new api.Value( true );
+
+			this.iframe = $( '<iframe />', { 'src': src, 'title': Loader.settings.l10n.mainIframeTitle } ).appendTo( this.element );
 			this.iframe.one( 'load', this.loaded );
 
 			// Create a postMessage connection with the iframe.
@@ -91,58 +130,113 @@ window.wp = window.wp || {};
 			});
 
 			this.messenger.bind( 'close', function() {
-				if ( $.support.history )
+				if ( $.support.history ) {
 					history.back();
-				else if ( $.support.hashchange )
+				} else if ( $.support.hashchange ) {
 					window.location.hash = '';
-				else
+				} else {
 					Loader.close();
+				}
 			});
 
+			// Prompt AYS dialog when navigating away
+			$( window ).on( 'beforeunload', this.beforeunload );
+
 			this.messenger.bind( 'activated', function( location ) {
-				if ( location )
+				if ( location ) {
 					window.location = location;
+				}
+			});
+
+			this.messenger.bind( 'saved', function () {
+				Loader.saved( true );
+			} );
+			this.messenger.bind( 'change', function () {
+				Loader.saved( false );
+			} );
+
+			this.messenger.bind( 'title', function( newTitle ){
+				window.document.title = newTitle;
 			});
 
-			hash = src.split('?')[1];
+			this.pushState( src );
+
+			this.trigger( 'open' );
+		},
+
+		pushState: function ( src ) {
+			var hash = src.split( '?' )[1];
 
 			// Ensure we don't call pushState if the user hit the forward button.
-			if ( $.support.history && window.location.href !== src )
+			if ( $.support.history && window.location.href !== src ) {
 				history.pushState( { customize: src }, '', src );
-			else if ( ! $.support.history && $.support.hashchange && hash )
+			} else if ( ! $.support.history && $.support.hashchange && hash ) {
 				window.location.hash = 'wp_customize=on&' + hash;
+			}
 
 			this.trigger( 'open' );
 		},
 
+		/**
+		 * Callback after the Customizer has been opened.
+		 */
 		opened: function() {
 			Loader.body.addClass( 'customize-active full-overlay-active' );
 		},
 
+		/**
+		 * Close the Customizer overlay and return focus to the link that opened it.
+		 */
 		close: function() {
-			if ( ! this.active )
+			if ( ! this.active ) {
+				return;
+			}
+
+			// Display AYS dialog if Customizer is dirty
+			if ( ! this.saved() && ! confirm( Loader.settings.l10n.saveAlert ) ) {
+				// Go forward since Customizer is exited by history.back()
+				history.forward();
 				return;
+			}
+
 			this.active = false;
 
 			this.trigger( 'close' );
 
+			// Restore document title prior to opening the Live Preview
+			if ( this.originalDocumentTitle ) {
+				document.title = this.originalDocumentTitle;
+			}
+
 			// Return focus to link that was originally clicked.
-			if ( this.link )
+			if ( this.link ) {
 				this.link.focus();
+			}
 		},
 
+		/**
+		 * Callback after the Customizer has been closed.
+		 */
 		closed: function() {
 			Loader.iframe.remove();
 			Loader.messenger.destroy();
 			Loader.iframe    = null;
 			Loader.messenger = null;
+			Loader.saved     = null;
 			Loader.body.removeClass( 'customize-active full-overlay-active' ).removeClass( 'customize-loading' );
+			$( window ).off( 'beforeunload', Loader.beforeunload );
 		},
 
+		/**
+		 * Callback for the `load` event on the Customizer iframe.
+		 */
 		loaded: function() {
 			Loader.body.removeClass('customize-loading');
 		},
 
+		/**
+		 * Overlay hide/show utility methods.
+		 */
 		overlay: {
 			show: function() {
 				this.element.fadeIn( 200, Loader.opened );
@@ -154,11 +248,12 @@ window.wp = window.wp || {};
 		}
 	});
 
+	// Bootstrap the Loader on document#ready.
 	$( function() {
 		Loader.settings = _wpCustomizeLoaderSettings;
 		Loader.initialize();
 	});
 
-	// Expose the API to the world.
+	// Expose the API publicly on window.wp.customize.Loader
 	api.Loader = Loader;
 })( wp, jQuery );