WordPress как на ладони

wp_localize_script()WP 2.2.0

Добавляет дополнительные данные перед указанным скриптом, который находится в очереди на вывод.

Функция создана для добавления данных локализации к JS скрипту. Эта функция регистрирует данные для указанного скрипта, затем перед выводом (подключением) самого скрипта указанные в этой функции данные выводятся в теге <script> в виде JS объекта.

Эту функцию нужно вызывать:

  • после того как скрипт был зарегистрирован. См. wp_register_script().
  • или после того как скрипт был добавлен в очередь на вывод. См. wp_enqueue_script().
  • или, если скрипт уже существует в WordPress.

Если скрипт уже выведен на экран и только потом используется эта функция, то ничего не произойдет.

Другими словами, скрипт, к которому подключается эта функцию обязательно должен быть:

  • уже зарегистрирован с помощью функции wp_register_script()
  • и/или должен быть добавлен в очередь на вывод с помощью wp_enqueue_script().

При этом на момент использования этой функции скрипт к которому эта функция подключается еще не должен быть выведен. В коде это должно выглядеть так:

// регистрируем скрипт
wp_register_script( $id, ... )

// добавляем данные к зарегистрированному скрипту
wp_localize_script( $id, ... )

// планируем скрипт на вывод
wp_enqueue_script( $id )

Или если так, когда скрипт сразу планируется на вывод (без предварительной регистрации):

// регистрируем и планируем скрипт на вывод
wp_enqueue_script( $id, ... )

// добавляем данные к зарегистрированному скрипту
wp_localize_script( $id, ... )

Эту функцию нужно вызывать через хуки, потому что на момент срабатывания этих хуков обычно все скрипты зарегистрированы, но еще не выведены в HTML:

  • wp_enqueue_scripts, если нужно вызвать функцию в лицевой части сайта (фронт-энде).

  • admin_enqueue_scripts, чтобы вызвать в административной части.

  • login_enqueue_scripts - для страницы авторизации.

Эта функция нужна для локализации!
Её часто используют для добавления данных к скрипту, а не для подключения строк локализации. Например при подключении слайдера, перед ним подключаются его настройки.

Так делать не рекомендуется! Используйте эту функцию только для локализации, а для добавления дополнительных данных используйте wp_add_inline_script(). См. пример.

Данные в итоговом Javascript будут переданы как текст.
Если нужно обработать числа, вы должны использовать функцию parseInt() в принимаемом скрипте:

<script>
FinalZoom = map.getBoundsZoomLevel( bounds ) - parseInt( data.a_value );
</script>

ИСКЛЮЧЕНИЕ. Если в $handle указать jquery то локализация будет подключаться к скрипту jquery-core.

Но если вы переопределили подключение jquery (указали что подключать его нужно с внешнего ресурса, т.е. удалили базовый вариант подключения в WordPress и указали свой), то скрипт jquery-core будет отключен, а это значит, что локализация не сработает, потому что она подключается к jquery-core, которого уже нет.

Чтобы однозначно избежать обоих этих нестыковок, надо сделать так::

add_action( 'wp_enqueue_scripts', 'front_scripts' );

function front_scripts(){

	$jquery_url = 'https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js';

	wp_deregister_script( 'jquery-core' );
	wp_deregister_script( 'jquery' );

	wp_register_script( 'jquery-core', $jquery_url, false, null, true );
	wp_register_script( 'jquery', false, [ 'jquery-core' ], null, true );
}
Работает на основе: WP_Scripts::localize()

Хуков нет.

Возвращает

true|false.

Использование

wp_localize_script( $handle, $object_name, $l10n );
$handle(строка) (обязательный)
Название скрипта, перед которым будут добавлены данные. Скрипт должен быть зарегистрирован заранее.
$object_name(строка) (обязательный)
Название Javascript объекта, который будет содержать данные. Название должно быть уникальным, чтобы не вызвать конфликтов с другими скриптами! В названии нельзя использовать тире -, только латиницу a-zA-Z, подчеркивание _, а также можно примерять метод "верблюжьегоРегстра" (CamelCase).
$l10n(массив) (обязательный)
Данные перевода. Данные могут быть как в одномерном, так и в многомерном массиве.

Примеры

1

#1 Не используйте для данных

wp_localize_script() рекомендуется использовать только для передачи строк локализации, а не для передачи данных - объекта, который будет использовать ваш скрипт. Для передачи данных лучше использовать wp_add_inline_script().

Рассмотрим на примере:

Раньше вы могли (и все еще можете) сделать следующее:

wp_enqueue_script( 'my-script', 'https://url-to/my-script.js' );

wp_localize_script( 'my-script', 'MYSCRIPT', array(
	'ajaxUrl' => admin_url( 'admin-ajax.php' ),
	'otherParam' => 'some value',
) );

Но лучше делать это так, потому что в этом случае мы сохраняем типы передаваемых данных и, например числа останутся числами, а не превратятся в строки:

wp_enqueue_script( 'my-script', 'https://url-to/my-script.js' );

$data = [
	'ajaxUrl' => admin_url( 'admin-ajax.php' ),
	'param_one' => 'some value',
	'param_two' => 25,
];

wp_add_inline_script( 'my-script', 'const myScriptData = ' . wp_json_encode( $data ), 'before' );

Обратите внимание, что нужно добавить 'before' в качестве третьего параметра.

Теперь в JS-скрипте эти данные можно получить так:

console.log( myScriptData.ajaxUrl );   // "https://site.com/wp-admin/admin-ajax.php"
console.log( myScriptData.param_one ); // "some value"
console.log( myScriptData.param_two ); // 25
0

#2 Вставка глобальных данных

Пример вставки глобальных javascript данных перед рабочим скриптом (в примере рабочий скрипт это jquery). Вставляем этот код в functions.php:

add_action( 'wp_enqueue_scripts', 'action_function_name_7714', 99 );

function action_function_name_7714(){

	wp_localize_script( 'jquery', 'object_name', array(
		'some_string' => __( 'Some string to translate' ),
		'some_num' => '10'
	) );
}

Получим в head части сайта:

<script type='text/javascript'>
/* <![CDATA[ */
var object_name = {"some_string":"Some string to translate","some_num":"10"};
/* ]]> */
</script>
<script type='text/javascript' src='http://example.com/wp-includes/js/jquery/jquery.js?ver=1.8.3'></script>
0

#3 Определим файл обработчик AJAX запросов

Добавим скрипт, а затем глобальных данных к нему. Тут мы добавляем javascript файл с AJAX запросом. В файле используется переменная MyAjax.ajaxurl, как URL для направления AJAX запроса. Этот URL мы определим через wp_localize_script():

add_action( 'wp_enqueue_scripts', 'action_function_name_7714' );

function action_function_name_7714(){

	wp_enqueue_script( 'my-ajax', get_template_directory_uri() . '/js/custom_script.js' );

	wp_localize_script( 'my-ajax', 'MyAjax', [ 'ajaxurl' => admin_url( 'admin-ajax.php' ) ] );

}

получим:

<script type='text/javascript'>
/* <![CDATA[ */
var MyAjax = {"ajaxurl":"http://example.com/wp-admin/admin-ajax.php"};
/* ]]> */
</script>
<script type='text/javascript' src='http://example.com/wp-content/themes/twentyeleven/js/custom_script.js?ver=3.5'></script>

Доступ к переменным в Javascript осуществляется так (для примера 2):

<script>
// в файле custom_script.js мы можем использовать переменную: MyAjax.ajaxurl
alert( MyAjax.ajaxurl ); // выведет http://example.com/wp-admin/admin-ajax.php
</script>

Заметки

  • Смотрите: WP_Scripts::localize()
  • Global. WP_Scripts. $wp_scripts The WP_Scripts object for printing scripts.

Список изменений

С версии 2.2.0 Введена.

Код wp_localize_script() WP 6.5.2

function wp_localize_script( $handle, $object_name, $l10n ) {
	global $wp_scripts;

	if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
		_wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
		return false;
	}

	return $wp_scripts->localize( $handle, $object_name, $l10n );
}
16 комментариев
Полезные 4 Все
    Войти