Создание пользовательских переключателей валют с помощью файлов шаблонов

Многим сайтам и темам оформления нужен переключатель валют, который соответствует их индивидуальному дизайну. Узнайте, как создать собственный переключатель валют с помощью PHP.

Принцип работы PHP-шаблонов для переключателей валют

Вот базовый пример PHP-шаблона для переключателя валют:

<?php
/**
 * @var string $css_classes
 * @var string $format
 * @var string $selected_currency
 * @var string[] $currencies
 */
?>
<div class="<?php echo esc_attr( $css_classes ) ?>">
	<ul>
		<li class="wcml-cs-active-currency">
			<a class="wcml-cs-item-toggle"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $selected_currency, $format ) ); ?></a>
			<ul class="wcml-cs-submenu">
				<?php foreach ( $currencies as $currency ) : ?>
					<?php if ( $currency != $selected_currency ) : ?>
						<li>
							<a rel="<?php echo esc_attr( $currency ); ?>"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ) ); ?></a>
						</li>
					<?php endif; ?>
				<?php endforeach; ?>
			</ul>
		</li>
	</ul>
</div>

Этот шаблон:

Открывает HTML-теги контейнера <div> и <ul>, которые структурируют переключатель
Отображает выбранную валюту
Перебирает доступные валюты
Выводит HTML-элемент списка <li> для каждой валюты (за исключением выбранной в данный момент)
Выводит кликабельные ссылки для переключения валюты

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

Добавление шаблона переключателя валют в Вашу тему оформления

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

Если Вы разрабатываете тему оформления, которую планируете распространять или продавать, включите шаблоны непосредственно в тему. Таким образом, все пользователи Вашей темы оформления смогут использовать созданные Вами переключатели валют.
Если Вы настраиваете существующую тему оформления, создайте шаблоны в дочерней теме. Это предотвратит перезапись Ваших изменений при обновлении родительской темы.

Используйте следующую структуру папок для шаблонов пользовательских переключателей:

my-theme/wpml/templates/currency-switchers/my-template

Структура папок для шаблонов пользовательских переключателей валют

Чтобы создать эту структуру:

Внутри Вашей темы оформления (или дочерней темы) создайте папку с именем wpml. WPML Multilingual & Multicurrency for WooCommerce использует это соглашение об именовании, поскольку работает вместе с WPML.
Внутри wpml создайте папку templates.
Внутри templates создайте папку currency-switchers.
Внутри currency-switchers создайте по одной вложенной папке для каждого создаваемого пользовательского переключателя — например, my-template.

Внутри каждой папки пользовательского переключателя (например, my-template) Вам понадобятся:

template.php — Обязательно. Это Ваш основной файл PHP-шаблона.
config.json — Обязательно. Этот файл предоставляет WCML метаданные о Вашем переключателе валют.
Любые необязательные файлы CSS или JS — включите их, если Ваш переключатель использует пользовательские стили или интерактивность.

В более ранних версиях WPML Multilingual & Multicurrency for WooCommerce (до 5.5) Вы могли использовать файл template.twig, если файл template.php отсутствовал. Если были включены оба файла, WPML Multilingual & Multicurrency for WooCommerce всегда использовал template.php.

Начиная с WPML Multilingual & Multicurrency for WooCommerce 5.6, файлы .twig больше не будут поддерживаться. В дальнейшем всегда используйте template.php для определения структуры Вашего переключателя валют.

Создание файла template.php

Файл template.php определяет макет и поведение Вашего пользовательского переключателя валют. Он использует стандартный PHP и выводит HTML, который будет отображаться на фронтенде.

Внутри Вашего шаблона Вы можете использовать следующие переменные, предоставляемые WPML Multilingual & Multicurrency for WooCommerce:

$css_classes (строка): CSS-классы, применяемые к основному контейнеру.
$currencies (массив): Список доступных валют.
$selected_currency (строка): Текущая выбранная валюта.
$format (строка): Строка, определяющая, как должна отображаться валюта.
WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ): Статический метод, используемый для форматирования и отображения каждой метки валюты.

При написании шаблона следуйте лучшим практикам пользовательского интерфейса WordPress, чтобы Ваш переключатель был доступным и согласованным с другими элементами темы оформления. Также не забудьте экранировать динамический вывод, используя такие функции, как esc_attr() и wp_kses_post(), чтобы обеспечить безопасность Вашего кода.

Настройка параметров в файле config.json

Каждый пользовательский переключатель валют должен включать файл config.json. Этот файл предоставляет WPML Multilingual & Multicurrency for WooCommerce основную информацию о Вашем переключателе валют, такую как его название и любые необходимые ему ресурсы CSS или JS.

Обязательные поля

Файл должен определять название переключателя валют:

{
  "name": "My custom switcher"
}

Вам не нужно добавлять префикс к названию. WPML Multilingual & Multicurrency for WooCommerce автоматически обработает это на основе темы оформления или плагина, к которому относится переключатель.

Необязательные поля

В дополнение к обязательному названию Вы можете включить два необязательных поля:

css: Список файлов CSS для загрузки из папки Вашего шаблона. По умолчанию WPML Multilingual & Multicurrency for WooCommerce автоматически ставит в очередь все файлы .css в папке шаблона, но Вы можете переопределить это поведение с помощью данного поля.

"css": ["style.css", "responsive.css"]

js: Список файлов JavaScript для загрузки из папки Вашего шаблона. Используйте только чистый JavaScript, если Ваша тема оформления или плагин еще не включает JS-библиотеку, такую как jQuery.

"js": ["script.js", "click-handler.js"]

Вот полный файл config.json, который включает все поля:

{
"name":           "My custom Vertical List",
"css":            ["style.css"],
"js":             ["script.js"],
}

Добавление шаблонов переключателя валют в папку uploads

Вы также можете хранить шаблоны пользовательских переключателей валют в папке загрузок WordPress. Это полезно, если Вы хотите уберечь шаблоны от обновлений темы оформления или плагина.

Поместите Ваши шаблоны по следующему пути:

../wp-content/uploads/wpml/templates/currency-switchers/

WPML Multilingual & Multicurrency for WooCommerce автоматически сканирует этот путь на наличие шаблонов переключателей валют.

Добавление шаблонов переключателя валют в плагин

Если Вы создаете плагин и хотите включить в него пользовательские переключатели валют, Вам нужно указать WPML Multilingual & Multicurrency for WooCommerce, где их найти.

Используйте фильтр wcml_cs_directories_to_scan для регистрации каталога шаблонов. Добавьте этот код в основной файл Вашего плагина:

function myplugin_wcml_cs_dirs_to_scan( $dirs ) {
    $folder_name = basename( dirname( __FILE__ ) );
    $dirs[] 	= trailingslashit( WP_PLUGIN_DIR ) . $folder_name . '/templates/';
    return $dirs;
}
add_filter( 'wcml_cs_directories_to_scan', 'myplugin_wcml_cs_dirs_to_scan' );

Затем WPML Multilingual & Multicurrency for WooCommerce просканирует папку шаблонов внутри Вашего плагина. Вам нужно поместить каждый пользовательский переключатель валют в собственную вложенную папку, например так:

my-plugin/templates/my-template/

Полный пример: пользовательский переключатель валют

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

В Вашей теме оформления или дочерней теме создайте следующую папку:

wpml/templates/currency-switchers/custom-currency-switcher/

Создайте файл config.json внутри папки:

{
"name": "Custom currency switcher"
}

Создайте файл template.php для отображения выбранной валюты и списка остальных:

<?php
/**
* @var string $css_classes
* @var string $format
* @var string $selected_currency
* @var string[] $currencies
*/
?>
<div class="<?php echo esc_attr( $css_classes ) ?>">
	<ul>
		<li class="wcml-cs-active-currency">
			<a class="wcml-cs-item-toggle"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $selected_currency, $format ) ); ?></a>
			<ul class="wcml-cs-submenu">
				<?php foreach ( $currencies as $currency ) : ?>
					<?php if ( $currency != $selected_currency ) : ?>
						<li>
							<a rel="<?php echo esc_attr( $currency ); ?>"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ) ); ?></a>
						</li>
					<?php endif; ?>
				<?php endforeach; ?>
			</ul>
		</li>
	</ul>
</div>

Если Вы хотите настроить внешний вид, добавьте файл style.css:

.your-custom-class li {
  list-style: none;
  float: left;
  margin: 0 3px;
}

Использование пользовательских переключателей валют в PHP-шаблонах

После создания пользовательского переключателя валют Вы можете использовать его в своих PHP-шаблонах, вызвав действие wcml_currency_switcher.

do_action('wcml_currency_switcher', array(
  'format' => '%name% (%symbol%)',
  'switcher_style' => 'twenty-seventeen-my-custom-switcher'
));

Значение switcher_style зависит от двух вещей: расположения переключателя и названия, определенного в его config.json. WCML генерирует слаг автоматически, используя этот формат:

Расположение пользовательского переключателя валют	Как генерируется слаг
Папка темы оформления	Слаг темы оформления + очищенное название переключателя
Папка плагина	Слаг плагина + очищенное название переключателя
Папка «uploads»	«uploads-» + очищенное название переключателя

Допустим:

Ваша тема оформления — Twenty Seventeen
В config.json Вашего переключателя содержится:

{ "name": "My custom switcher" }

Тогда сгенерированный слаг будет таким:

twenty-seventeen-my-custom-switcher

Используйте это в качестве значения для switcher_style во фрагменте кода выше.