使用模板文件设计自定义货币切换器

许多网站和主题需要与其自定义设计相匹配的货币切换器。了解如何使用 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>

此模板：

• 打开构成切换器结构的容器 <div> 和 <ul> HTML 标签
• 显示所选货币
• 循环遍历可用货币
• 为每种货币（不包括当前选择的货币）输出一个 <li> HTML 列表项
• 输出用于切换货币的可点击链接

现在，让我们逐步了解如何为自己的货币切换器创建此类模板。

向主题添加货币切换器模板

您可以在主题中添加一个目录，用于存放自定义货币切换器模板。

• 如果您正在开发计划分发或出售的主题，请将模板直接包含在主题中。这样，您主题的所有用户都将能够使用您创建的货币切换器。
• 如果您正在自定义现有主题，请在子主题内创建模板。这可防止您的更改在父主题更新时被覆盖。

对自定义切换器模板使用以下文件夹结构：

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

要构建此结构：

1. 在您的主题（或子主题）内，创建一个名为 wpml 的文件夹。WPML Multilingual & Multicurrency for WooCommerce 使用此命名约定，因为它与 WPML 协同工作。
2. 在 wpml 内，创建一个 templates 文件夹。
3. 在 templates 内，创建一个 currency-switchers 文件夹。
4. 在 currency-switchers 内，为您构建的每个自定义切换器创建一个子文件夹，例如 my-template。

在每个自定义切换器文件夹（例如 my-template）内，您将需要：

• template.php — 必填。这是您的主 PHP 模板文件。
  
• config.json — 必填。此文件为 WCML 提供有关货币切换器的元数据。
  
• 任何可选的 CSS 或 JS 文件 — 如果您的切换器使用自定义样式或交互，请包含这些文件。

设计 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 UI 最佳实践，以确保您的切换器易于访问且与其他主题元素保持一致。此外，请确保使用 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 文件列表。除非您的主题或插件已包含 jQuery 等 JS 库，否则请仅使用纯 JavaScript。

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

以下是包含所有字段的完整 config.json：

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

向 Uploads 文件夹添加货币切换器模板

您也可以将自定义货币切换器模板存储在 WordPress 的 uploads 文件夹中。如果您希望模板免受主题或插件更新的影响，这将非常有用。

将模板放置在以下路径中：

../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 将扫描插件内的 templates 文件夹。您需要将每个自定义货币切换器放置在其自己的子文件夹中，如下所示：

my-plugin/templates/my-template/

完整示例：自定义货币切换器

此示例展示了如何创建具有自己的文件夹、模板、配置和可选样式的完整货币切换器。

1. 在您的主题或子主题中，创建以下文件夹：

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

1. 在文件夹内创建一个 config.json 文件：

{
"name": "Custom currency switcher"
}

1. 创建一个 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>

1. 如果您想自定义外观，请添加一个 style.css 文件：

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

在 PHP 模板中使用自定义货币切换器

创建自定义货币切换器后，您可以通过调用 wcml_currency_switcher 操作在 PHP 模板中使用它。

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 的值。