Diseñar selectores de moneda personalizados usando archivos de plantilla

Muchos sitios y temas necesitan un selector de moneda que coincida con su diseño personalizado. Aprenda a crear su propio selector de moneda con PHP.

Entender las plantillas PHP para los selectores de moneda

Este es un ejemplo básico de una plantilla PHP para un selector de moneda:

<?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>

Esta plantilla:

• Abre las etiquetas HTML contenedoras <div> y <ul> que estructuran el selector
• Muestra la moneda seleccionada
• Recorre las monedas disponibles
• Genera un elemento de lista HTML <li> para cada moneda (excluyendo la seleccionada actualmente)
• Genera enlaces en los que se puede hacer clic para cambiar la moneda

Ahora, veamos cómo crear este tipo de plantillas para sus propios selectores de moneda.

Añadir una plantilla de selector de moneda a su tema

Puede añadir un directorio a su tema para guardar las plantillas de sus selectores de moneda personalizados.

• Si está desarrollando un tema que planea distribuir o vender, incluya las plantillas directamente en el tema. De esta manera, todos los usuarios de su tema podrán usar los selectores de moneda que cree.
• Si está personalizando un tema existente, cree las plantillas dentro de un tema hijo. Esto evita que sus cambios se sobrescriban cuando se actualice el tema padre.

Use la siguiente estructura de carpetas para las plantillas de su selector personalizado:

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

Para crear esta estructura:

1. Dentro de su tema (o tema hijo), cree una carpeta llamada wpml. WPML Multilingual & Multicurrency for WooCommerce usa esta convención de nomenclatura porque funciona junto con WPML.
2. Dentro de wpml, cree una carpeta templates.
3. Dentro de templates, cree una carpeta currency-switchers.
4. Dentro de currency-switchers, cree una subcarpeta para cada selector personalizado que cree, por ejemplo, my-template.

Dentro de cada carpeta de selector personalizado (por ejemplo, my-template), necesitará:

• template.php: Obligatorio. Este es su archivo de plantilla PHP principal.
  
• config.json: Obligatorio. Este archivo proporciona a WCML metadatos sobre su selector de moneda.
  
• Cualquier archivo CSS o JS opcional: inclúyalos si su selector usa estilos personalizados o interactividad.

Diseñar el archivo template.php

El archivo template.php define el diseño y el comportamiento de su selector de moneda personalizado. Usa PHP estándar y genera el HTML que se renderizará en el front-end.

Dentro de su plantilla, puede usar las siguientes variables proporcionadas por WPML Multilingual & Multicurrency for WooCommerce:

• $css_classes (cadena): clases CSS aplicadas al contenedor principal.
• $currencies (matriz): una lista de las monedas disponibles.
• $selected_currency (cadena): la moneda seleccionada actualmente.
• $format (cadena): una cadena que define cómo debe mostrarse la moneda.
• WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ): un método estático usado para formatear y mostrar cada etiqueta de moneda.

Al escribir su plantilla, siga las mejores prácticas de la interfaz de usuario de WordPress para asegurarse de que su selector sea accesible y coherente con otros elementos del tema. Asegúrese también de escapar la salida dinámica usando funciones como esc_attr() y wp_kses_post() para mantener su código seguro.

Configurar opciones en el archivo config.json

Cada selector de moneda personalizado debe incluir un archivo config.json. Este archivo proporciona a WPML Multilingual & Multicurrency for WooCommerce información básica sobre su selector de moneda, como su nombre y cualquier recurso CSS o JS que necesite.

Campos obligatorios

El archivo debe definir el nombre del selector de moneda:

{
  "name": "My custom switcher"
}

No es necesario que añada un prefijo al nombre. WPML Multilingual & Multicurrency for WooCommerce lo gestionará automáticamente en función del tema o plugin al que pertenezca el selector.

Campos opcionales

Además del nombre obligatorio, puede incluir dos campos opcionales:

• css: una lista de archivos CSS para cargar desde su carpeta de plantillas. Por defecto, WPML Multilingual & Multicurrency for WooCommerce pondrá en cola automáticamente todos los archivos .css de la carpeta de plantillas, pero puede anular ese comportamiento con este campo.

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

• js: una lista de archivos JavaScript para cargar desde su carpeta de plantillas. Use solo JavaScript puro a menos que su tema o plugin ya incluya una biblioteca JS como jQuery.

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

Este es un config.json completo que incluye todos los campos:

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

Añadir plantillas de selectores de moneda a la carpeta uploads

También puede guardar las plantillas de sus selectores de moneda personalizados en la carpeta uploads de WordPress. Esto es útil si quiere mantener las plantillas a salvo de las actualizaciones de temas o plugins.

Coloque sus plantillas en la siguiente ruta:

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

WPML Multilingual & Multicurrency for WooCommerce analiza automáticamente esta ruta en busca de plantillas de selectores de moneda.

Añadir plantillas de selectores de moneda a un plugin

Si está creando un plugin y quiere incluir selectores de moneda personalizados, debe indicarle a WPML Multilingual & Multicurrency for WooCommerce dónde encontrarlos.

Use el filtro wcml_cs_directories_to_scan para registrar el directorio de plantillas. Añada este código a su archivo principal del plugin:

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' );

A continuación, WPML Multilingual & Multicurrency for WooCommerce analizará la carpeta de plantillas dentro de su plugin. Debe colocar cada selector de moneda personalizado en su propia subcarpeta, de esta manera:

my-plugin/templates/my-template/

Ejemplo completo: selector de moneda personalizado

Este ejemplo muestra cómo crear un selector de moneda completo con su propia carpeta, plantilla, configuración y estilos opcionales.

1. En su tema o tema hijo, cree la siguiente carpeta:

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

1. Cree un archivo config.json dentro de la carpeta:

{
"name": "Custom currency switcher"
}

1. Cree un archivo template.php para mostrar la moneda seleccionada y una lista de las demás:
   

<?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. Si quiere personalizar la apariencia, añada un archivo style.css:

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

Usar selectores de moneda personalizados en plantillas PHP

Una vez que haya creado un selector de moneda personalizado, puede usarlo en sus plantillas PHP llamando a la acción wcml_currency_switcher.

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

El valor de switcher_style depende de dos cosas: la ubicación del selector y el nombre definido en su config.json. WCML genera el slug automáticamente usando este formato:

Ubicación del selector de moneda personalizado	Cómo se genera el slug
Carpeta del tema	Slug del tema + nombre limpio del selector
Carpeta del plugin	Slug del plugin + nombre limpio del selector
Carpeta “uploads”	“uploads-” + nombre limpio del selector

Por lo tanto, supongamos que:

• Su tema es Twenty Seventeen
• El config.json de su selector contiene:

{ "name": "My custom switcher" }

Entonces, el slug generado será:

twenty-seventeen-my-custom-switcher

Use esto como el valor para switcher_style en el fragmento de código anterior.