Ressurect WP_Scripts::localize() and fix public function names, fixes #11520

git-svn-id: http://svn.automattic.com/wordpress/trunk@19217 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/js/wp-fullscreen.dev.js

@@ -138,8 +138,8 @@ PubSub.prototype.publish = function( topic, args ) {
 			return;
 
 		// Settings can be added or changed by defining "wp_fullscreen_settings" JS object.
-		// This can be done by defining it as PHP array and passing it to JS with:
+		// This can be done by defining it as PHP associative array, json encoding it and passing it to JS with:
-		// add_script_data( 'wp-fullscreen', 'wp_fullscreen_settings', $settings_array )
+		// wp_add_script_before( 'wp-fullscreen', 'wp_fullscreen_settings = ' . $json_encoded_array . ';' );
 		if ( typeof(wp_fullscreen_settings) == 'object' )
 			$.extend( s, wp_fullscreen_settings );
 

wp-includes/class.wp-scripts.php

@@ -47,42 +47,22 @@ class WP_Scripts extends WP_Dependencies {
 		return $this->do_items( $handles, $group );
 	}
 
-	// Deprecated since 3.3, see print_script_data()
+	// Deprecated since 3.3, see print_extra_script()
 	function print_scripts_l10n( $handle, $echo = true ) {
-		_deprecated_function( __FUNCTION__, '3.3', 'print_script_data()' );
+		_deprecated_function( __FUNCTION__, '3.3', 'print_extra_script()' );
-		return $this->print_script_data( $handle, $echo, true );
+		return $this->print_extra_script( $handle, $echo );
 	}
 
-	function print_script_data( $handle, $echo = true, $_l10n = false ) {
+	function print_extra_script( $handle, $echo = true ) {
-		if ( $_l10n ) {
+		if ( !$output = $this->get_data( $handle, 'data' ) )
-			list( $name, $data ) = $this->get_data( $handle, 'l10n' );
+			return;
-			$after = '';
-
-			if ( is_array($data) && isset($data['l10n_print_after']) ) {
-				$after = $data['l10n_print_after'];
-				unset($data['l10n_print_after']);
-			}
-
-			$data = $this->decode_html_entities($data);
-			$output = "var $name = " . json_encode( $data ) . "; $after\n";
-		} else {
-			$data = $this->get_data( $handle, 'data' );
-
-			if ( empty( $data ) )
-				return false;
-
-			foreach ( (array) $data as $name => $value ) {
-				$value = $this->decode_html_entities($value);
-				$output = "var $name = " . json_encode( $value ) . ";\n";
-			}
-		}
 
 		if ( !$echo )
 			return $output;
 
-		echo "<script type='text/javascript'>\n";
+		echo "<script type='text/javascript'>\n"; // CDATA and type='text/javascript' is not needed for HTML 5
-		echo "/* <![CDATA[ */\n"; // CDATA is not needed for HTML 5
+		echo "/* <![CDATA[ */\n";
-		echo $output;
+		echo "$output\n";
 		echo "/* ]]> */\n";
 		echo "</script>\n";
 
@@ -114,7 +94,7 @@ class WP_Scripts extends WP_Dependencies {
 		if ( $this->do_concat ) {
 			$srce = apply_filters( 'script_loader_src', $src, $handle );
 			if ( $this->in_default_dir($srce) ) {
-				$this->print_code .= $this->print_script_data( $handle, false );
+				$this->print_code .= $this->print_extra_script( $handle, false );
 				$this->concat .= "$handle,";
 				$this->concat_version .= "$handle$ver";
 				return true;
@@ -124,14 +104,15 @@ class WP_Scripts extends WP_Dependencies {
 			}
 		}
 
-		$this->print_script_data( $handle );
+		$this->print_extra_script( $handle );
 		if ( !preg_match('|^https?://|', $src) && ! ( $this->content_url && 0 === strpos($src, $this->content_url) ) ) {
 			$src = $this->base_url . $src;
 		}
 
 		if ( !empty($ver) )
 			$src = add_query_arg('ver', $ver, $src);
-		$src = esc_url(apply_filters( 'script_loader_src', $src, $handle ));
+
+		$src = esc_url( apply_filters( 'script_loader_src', $src, $handle ) );
 
 		if ( $this->do_concat )
 			$this->print_html .= "<script type='text/javascript' src='$src'></script>\n";
@@ -142,15 +123,29 @@ class WP_Scripts extends WP_Dependencies {
 	}
 
 	/**
-	 * Localizes a script (Deprecated)
+	 * Localizes a script
 	 *
-	 * Localizes only if script has already been added
+	 * Localizes only if the script has already been added
-	 *
-	 * @deprecated WP 3.3
 	 */
 	function localize( $handle, $object_name, $l10n ) {
-		_deprecated_function( __FUNCTION__, '3.3', 'add_script_data()' );
+		if ( is_array($l10n) && isset($l10n['l10n_print_after']) ) { // back compat, preserve the code in 'l10n_print_after' if present
-		return $this->add_script_data( $handle, $object_name, $l10n );
+			$after = $l10n['l10n_print_after'];
+			unset($l10n['l10n_print_after']);
+		}
+
+		foreach ( (array) $l10n as $key => $value ) {
+			if ( !is_scalar($value) )
+				continue;
+
+			$l10n[$key] = html_entity_decode( (string) $value, ENT_QUOTES, 'UTF-8');
+		}
+
+		$script = "var $object_name = " . json_encode($l10n) . ';';
+
+		if ( !empty($after) )
+			$script .= "\n$after";
+
+		return $this->add_script_data( $handle, $script );
 	}
 
 	/**
@@ -159,20 +154,19 @@ class WP_Scripts extends WP_Dependencies {
 	 * Only if script has already been added.
 	 *
 	 * @param string $handle Script name
-	 * @param string $name Name of JS object to hold the data
+	 * @param string $script Extra JS to add before the script
-	 * @param array $args Associative array of JS object attributes
 	 * @return bool Successful or not
 	 */
-	function add_script_data( $handle, $name, $args ) {
+	function add_script_data( $handle, $script ) {
-		if ( !$name || !is_array( $args ) )
+		if ( !is_string( $script ) )
 			return false;
 
 		$data = $this->get_data( $handle, 'data' );
 
-		if ( !empty( $data[$name] ) )
+		if ( !empty( $data ) )
-			$args = array_merge( $data[$name], $args );
+			$script = "$data;\n$script";
 
-		return $this->add_data( $handle, 'data', array( $name => $args ) );
+		return $this->add_data( $handle, 'data', $script );
 	}
 
 	function set_group( $handle, $recursion, $group = false ) {
@@ -219,16 +213,6 @@ class WP_Scripts extends WP_Dependencies {
 		return false;
 	}
 
-	function decode_html_entities($data) {
-		foreach ( (array) $data as $key => $value ) {
-			if ( is_array($value) )
-				$data[$key] = $this->decode_html_entities($value);
-			elseif ( is_string($value) )
-				$data[$key] = html_entity_decode($value, ENT_QUOTES, 'UTF-8');
-		}
-		return $data;
-	}
-
 	function reset() {
 		$this->do_concat = false;
 		$this->print_code = '';

wp-includes/functions.wp-scripts.php

@@ -64,24 +64,48 @@ function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_f
 }
 
 /**
- * Adds extra Javascript data.
+ * Wrapper for $wp_scripts->localize().
  *
+ * Used to localizes a script.
  * Works only if the script has already been added.
- * Accepts an associative array $data and creates JS object:
+ * Accepts an associative array $l10n and creates JS object:
- * "$name" = {
+ * "$object_name" = {
  *   key: value,
  *   key: value,
  *   ...
  * }
- * The $name is passed directly so it should be qualified JS variable /[a-zA-Z0-9_]+/
+ * See http://core.trac.wordpress.org/ticket/11520 for more information.
- * The $data array is JSON encoded. If called more than once for the same $handle with the same $name,
- * the object would contain all values. In that case if two or more keys are the same,
- * the last value overwrites the previous. The function is named "localize_script" because of historical reasons.
  *
  * @since r16
+ *
+ * @param string $handle The script handle that was registered or used in script-loader
+ * @param string $object_name Name for the created JS object. This is passed directly so it should be qualified JS variable /[a-zA-Z0-9_]+/
+ * @param array $l10n Associative PHP array containing the translated strings. HTML entities will be converted and the array will be JSON encoded. 
+ * @return bool Whether the localization was added successfully.
+ */
+function wp_localize_script( $handle, $object_name, $l10n ) { 
+	global $wp_scripts;
+	if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
+		if ( ! did_action( 'init' ) )
+			_doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
+				'<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>init</code>' ), '3.3' );
+
+		return false;
+	}
+
+	return $wp_scripts->localize( $handle, $object_name, $l10n ); 
+} 
+
+/**
+ * Adds extra Javascript.
+ *
+ * Works only if the script referenced by $handle has already been added.
+ * Accepts string $extra that will be printed as script before the main script tag.
+ *
+ * @since 3.3
  * @see WP_Scripts::add_script_data()
  */
-function wp_localize_script( $handle, $name, $data ) {
+function wp_add_script_before( $handle, $script ) {
 	global $wp_scripts;
 	if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
 		if ( ! did_action( 'init' ) )
@@ -90,7 +114,7 @@ function wp_localize_script( $handle, $name, $data ) {
 		return false;
 	}
 
-	return $wp_scripts->add_script_data( $handle, $name, $data );
+	return $wp_scripts->add_script_data( $handle, $script );
 }
 
 /**

wp-includes/script-loader.php

@@ -62,14 +62,14 @@ function wp_default_scripts( &$scripts ) {
 	$scripts->add( 'utils', "/wp-admin/js/utils$suffix.js", false, '20101110' );
 
 	$scripts->add( 'common', "/wp-admin/js/common$suffix.js", array('jquery', 'hoverIntent', 'utils'), '20111106a', 1 );
-	$scripts->add_script_data( 'common', 'commonL10n', array(
+	$scripts->localize( 'common', 'commonL10n', array(
 		'warnDelete' => __("You are about to permanently delete the selected items.\n  'Cancel' to stop, 'OK' to delete.")
 	) );
 
 	$scripts->add( 'sack', "/wp-includes/js/tw-sack$suffix.js", false, '1.6.1', 1 );
 
 	$scripts->add( 'quicktags', "/wp-includes/js/quicktags$suffix.js", false, '20111108', 1 );
-	$scripts->add_script_data( 'quicktags', 'quicktagsL10n', array(
+	$scripts->localize( 'quicktags', 'quicktagsL10n', array(
 		'wordLookup' => __('Enter a word to look up:'),
 		'dictionaryLookup' => esc_attr(__('Dictionary lookup')),
 		'lookup' => esc_attr(__('lookup')),
@@ -91,13 +91,13 @@ function wp_default_scripts( &$scripts ) {
 	$scripts->add( 'prototype', '/wp-includes/js/prototype.js', false, '1.6.1');
 
 	$scripts->add( 'wp-ajax-response', "/wp-includes/js/wp-ajax-response$suffix.js", array('jquery'), '20091119', 1 );
-	$scripts->add_script_data( 'wp-ajax-response', 'wpAjax', array(
+	$scripts->localize( 'wp-ajax-response', 'wpAjax', array(
 		'noPerm' => __('You do not have permission to do that.'),
 		'broken' => __('An unidentified error has occurred.')
 	) );
 
 	$scripts->add( 'wp-pointer', "/wp-includes/js/wp-pointer$suffix.js", array( 'jquery-ui-widget', 'jquery-ui-position' ), '20111017', 1 );
-	$scripts->add_script_data( 'wp-pointer', 'wpPointerL10n', array(
+	$scripts->localize( 'wp-pointer', 'wpPointerL10n', array(
 		'close' => __('Close'),
 	) );
 
@@ -166,7 +166,7 @@ function wp_default_scripts( &$scripts ) {
 	$scripts->add( 'jquery-table-hotkeys', "/wp-includes/js/jquery/jquery.table-hotkeys$suffix.js", array('jquery', 'jquery-hotkeys'), '20090102', 1 );
 
 	$scripts->add( 'thickbox', "/wp-includes/js/thickbox/thickbox.js", array('jquery'), '3.1-20110930', 1 );
-	$scripts->add_script_data( 'thickbox', 'thickboxL10n', array(
+	$scripts->localize( 'thickbox', 'thickboxL10n', array(
 			'next' => __('Next >'),
 			'prev' => __('< Prev'),
 			'image' => __('Image'),
@@ -221,7 +221,7 @@ function wp_default_scripts( &$scripts ) {
 	$scripts->add( 'plupload-all', false, array('plupload', 'plupload-html5', 'plupload-flash', 'plupload-silverlight', 'plupload-html4'), '1511');
 
 	$scripts->add( 'plupload-handlers', "/wp-includes/js/plupload/handlers$suffix.js", array('plupload-all', 'jquery'), '20111102');
-	$scripts->add_script_data( 'plupload-handlers', 'pluploadL10n', $uploader_l10n );
+	$scripts->localize( 'plupload-handlers', 'pluploadL10n', $uploader_l10n );
 
 	// keep 'swfupload' for back-compat.
 	$scripts->add( 'swfupload', '/wp-includes/js/swfupload/swfupload.js', false, '2201-20110113');
@@ -237,7 +237,7 @@ function wp_default_scripts( &$scripts ) {
 	}
 
 	$scripts->add( 'swfupload-handlers', "/wp-includes/js/swfupload/handlers$suffix.js", array('swfupload-all', 'jquery'), '2201-20110524');
-	$scripts->add_script_data( 'swfupload-handlers', 'swfuploadL10n', $uploader_l10n );
+	$scripts->localize( 'swfupload-handlers', 'swfuploadL10n', $uploader_l10n );
 
 	$scripts->add( 'comment-reply', "/wp-includes/js/comment-reply$suffix.js", false, '20090102');
 
@@ -246,7 +246,7 @@ function wp_default_scripts( &$scripts ) {
 	$scripts->add( 'imgareaselect', "/wp-includes/js/imgareaselect/jquery.imgareaselect$suffix.js", array('jquery'), '0.9.6-20110515', 1 );
 
 	$scripts->add( 'password-strength-meter', "/wp-admin/js/password-strength-meter$suffix.js", array('jquery'), '20101027', 1 );
-	$scripts->add_script_data( 'password-strength-meter', 'pwsL10n', array(
+	$scripts->localize( 'password-strength-meter', 'pwsL10n', array(
 		'empty' => __('Strength indicator'),
 		'short' => __('Very weak'),
 		'bad' => __('Weak'),
@@ -261,7 +261,7 @@ function wp_default_scripts( &$scripts ) {
 	$scripts->add( 'admin-bar', "/wp-includes/js/admin-bar$suffix.js", false, '20111107', 1 );
 
 	$scripts->add( 'wplink', "/wp-includes/js/wplink$suffix.js", array( 'jquery', 'wpdialogs' ), '20110929', 1 );
-	$scripts->add_script_data( 'wplink', 'wpLinkL10n', array(
+	$scripts->localize( 'wplink', 'wpLinkL10n', array(
 		'title' => __('Insert/edit link'),
 		'update' => __('Update'),
 		'save' => __('Add Link'),
@@ -280,7 +280,7 @@ function wp_default_scripts( &$scripts ) {
 	if ( is_admin() ) {
 		$scripts->add( 'ajaxcat', "/wp-admin/js/cat$suffix.js", array( 'wp-lists' ), '20090102' );
 		$scripts->add_data( 'ajaxcat', 'group', 1 );
-		$scripts->add_script_data( 'ajaxcat', 'catL10n', array(
+		$scripts->localize( 'ajaxcat', 'catL10n', array(
 			'add' => esc_attr(__('Add')),
 			'how' => __('Separate multiple categories with commas.')
 		) );
@@ -288,7 +288,7 @@ function wp_default_scripts( &$scripts ) {
 		$scripts->add( 'admin-categories', "/wp-admin/js/categories$suffix.js", array('wp-lists'), '20091201', 1 );
 
 		$scripts->add( 'admin-tags', "/wp-admin/js/tags$suffix.js", array('jquery', 'wp-ajax-response'), '20110429', 1 );
-		$scripts->add_script_data( 'admin-tags', 'tagsl10n', array(
+		$scripts->localize( 'admin-tags', 'tagsl10n', array(
 			'noPerm' => __('You do not have permission to do that.'),
 			'broken' => __('An unidentified error has occurred.')
 		));
@@ -296,7 +296,7 @@ function wp_default_scripts( &$scripts ) {
 		$scripts->add( 'admin-custom-fields', "/wp-admin/js/custom-fields$suffix.js", array('wp-lists'), '20110429', 1 );
 
 		$scripts->add( 'admin-comments', "/wp-admin/js/edit-comments$suffix.js", array('wp-lists', 'quicktags', 'jquery-query'), '20111026', 1 );
-		$scripts->add_script_data( 'admin-comments', 'adminCommentsL10n', array(
+		$scripts->localize( 'admin-comments', 'adminCommentsL10n', array(
 			'hotkeys_highlight_first' => isset($_GET['hotkeys_highlight_first']),
 			'hotkeys_highlight_last' => isset($_GET['hotkeys_highlight_last']),
 			'replyApprove' => __( 'Approve and Reply' ),
@@ -308,7 +308,7 @@ function wp_default_scripts( &$scripts ) {
 		$scripts->add( 'postbox', "/wp-admin/js/postbox$suffix.js", array('jquery-ui-sortable'), '20111009a', 1 );
 
 		$scripts->add( 'post', "/wp-admin/js/post$suffix.js", array('suggest', 'wp-lists', 'postbox'), '20110524', 1 );
-		$scripts->add_script_data( 'post', 'postL10n', array(
+		$scripts->localize( 'post', 'postL10n', array(
 			'ok' => __('OK'),
 			'cancel' => __('Cancel'),
 			'publishOn' => __('Publish on:'),
@@ -333,7 +333,7 @@ function wp_default_scripts( &$scripts ) {
 
 		$scripts->add( 'comment', "/wp-admin/js/comment$suffix.js", array('jquery'), '20110429' );
 		$scripts->add_data( 'comment', 'group', 1 );
-		$scripts->add_script_data( 'comment', 'commentL10n', array(
+		$scripts->localize( 'comment', 'commentL10n', array(
 			'submittedOn' => __('Submitted on:')
 		) );
 
@@ -346,19 +346,19 @@ function wp_default_scripts( &$scripts ) {
 		$scripts->add( 'theme-preview', "/wp-admin/js/theme-preview$suffix.js", array( 'thickbox', 'jquery' ), '20100407', 1 );
 
 		$scripts->add( 'inline-edit-post', "/wp-admin/js/inline-edit-post$suffix.js", array( 'jquery', 'suggest' ), '20111107', 1 );
-		$scripts->add_script_data( 'inline-edit-post', 'inlineEditL10n', array(
+		$scripts->localize( 'inline-edit-post', 'inlineEditL10n', array(
 			'error' => __('Error while saving the changes.'),
 			'ntdeltitle' => __('Remove From Bulk Edit'),
 			'notitle' => __('(no title)')
 		) );
 
 		$scripts->add( 'inline-edit-tax', "/wp-admin/js/inline-edit-tax$suffix.js", array( 'jquery' ), '20110609', 1 );
-		$scripts->add_script_data( 'inline-edit-tax', 'inlineEditL10n', array(
+		$scripts->localize( 'inline-edit-tax', 'inlineEditL10n', array(
 			'error' => __('Error while saving the changes.')
 		) );
 
 		$scripts->add( 'plugin-install', "/wp-admin/js/plugin-install$suffix.js", array( 'jquery', 'thickbox' ), '20110113', 1 );
-		$scripts->add_script_data( 'plugin-install', 'plugininstallL10n', array(
+		$scripts->localize( 'plugin-install', 'plugininstallL10n', array(
 			'plugin_information' => __('Plugin Information:'),
 			'ays' => __('Are you sure you want to install this plugin?')
 		) );
@@ -374,12 +374,12 @@ function wp_default_scripts( &$scripts ) {
 		$scripts->add( 'media', "/wp-admin/js/media$suffix.js", array( 'jquery-ui-draggable' ), '20101022', 1 );
 
 		$scripts->add( 'image-edit', "/wp-admin/js/image-edit$suffix.js", array('jquery', 'json2', 'imgareaselect'), '20110927', 1 );
-		$scripts->add_script_data( 'image-edit', 'imageEditL10n', array(
+		$scripts->localize( 'image-edit', 'imageEditL10n', array(
 			'error' => __( 'Could not load the preview image. Please reload the page and try again.' )
 		));
 
 		$scripts->add( 'set-post-thumbnail', "/wp-admin/js/set-post-thumbnail$suffix.js", array( 'jquery' ), '20100518', 1 );
-		$scripts->add_script_data( 'set-post-thumbnail', 'setPostThumbnailL10n', array(
+		$scripts->localize( 'set-post-thumbnail', 'setPostThumbnailL10n', array(
 			'setThumbnail' => __( 'Use as featured image' ),
 			'saving' => __( 'Saving...' ),
 			'error' => __( 'Could not set that as the thumbnail image. Try a different attachment.' ),
@@ -388,7 +388,7 @@ function wp_default_scripts( &$scripts ) {
 
 		// Navigation Menus
 		$scripts->add( 'nav-menu', "/wp-admin/js/nav-menu$suffix.js", array('jquery-ui-sortable'), '20110524' );
-		$scripts->add_script_data( 'nav-menu', 'navMenuL10n', array(
+		$scripts->localize( 'nav-menu', 'navMenuL10n', array(
 			'noResultsFound' => _x('No results found.', 'search results'),
 			'warnDeleteMenu' => __( "You are about to permanently delete this menu. \n 'Cancel' to stop, 'OK' to delete." ),
 			'saveAlert' => __('The changes you made will be lost if you navigate away from this page.')