Progettare selettori di valuta personalizzati utilizzando i file di template

Molti siti e temi hanno bisogno di un selettore di valuta che si adatti al loro design personalizzato. Scopri come creare il tuo selettore di valuta utilizzando PHP.

Comprendere i template PHP per i selettori di valuta

Ecco un esempio di base di un template PHP per un selettore di valuta:

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

Questo template:

• Apre i tag HTML contenitore <div> e <ul> che strutturano il selettore
• Mostra la valuta selezionata
• Esegue un ciclo tra le valute disponibili
• Restituisce un elemento di lista HTML <li> per ogni valuta (esclusa quella attualmente selezionata)
• Restituisce link cliccabili per cambiare la valuta

Ora, vediamo come creare questi template per i tuoi selettori di valuta.

Aggiungere un template per il selettore di valuta al tuo tema

Puoi aggiungere una directory al tuo tema per contenere i template personalizzati del tuo selettore di valuta.

• Se stai sviluppando un tema che intendi distribuire o vendere, includi i template direttamente nel tema. In questo modo, tutti gli utenti del tuo tema potranno utilizzare i selettori di valuta che crei.
• Se stai personalizzando un tema esistente, crea i template all'interno di un tema child. Questo impedisce che le tue modifiche vengano sovrascritte quando il tema genitore viene aggiornato.

Usa la seguente struttura di cartelle per i template personalizzati del tuo selettore:

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

Per creare questa struttura:

1. All'interno del tuo tema (o tema child), crea una cartella chiamata wpml. WPML Multilingual & Multicurrency for WooCommerce utilizza questa convenzione di denominazione perché funziona insieme a WPML.
2. All'interno di wpml, crea una cartella templates.
3. All'interno di templates, crea una cartella currency-switchers.
4. All'interno di currency-switchers, crea una sottocartella per ogni selettore personalizzato che costruisci, ad esempio, my-template.

All'interno di ogni cartella del selettore personalizzato (ad esempio, my-template), avrai bisogno di:

• template.php — Obbligatorio. Questo è il tuo file di template PHP principale.
  
• config.json — Obbligatorio. Questo file fornisce a WCML i metadati sul tuo selettore di valuta.
  
• Eventuali file CSS o JS opzionali — Includili se il tuo selettore utilizza stili personalizzati o interattività.

Progettare il file template.php

Il file template.php definisce il layout e il comportamento del tuo selettore di valuta personalizzato. Utilizza PHP standard e restituisce l'HTML che verrà visualizzato sul front-end.

All'interno del tuo template, puoi utilizzare le seguenti variabili fornite da WPML Multilingual & Multicurrency for WooCommerce:

• $css_classes (stringa): Le classi CSS applicate al contenitore principale.
• $currencies (array): Un elenco delle valute disponibili.
• $selected_currency (stringa): La valuta attualmente selezionata.
• $format (stringa): Una stringa che definisce come deve essere visualizzata la valuta.
• WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ): Un metodo statico utilizzato per formattare e visualizzare l'etichetta di ogni valuta.

Quando scrivi il tuo template, segui le best practice dell'interfaccia utente di WordPress per assicurarti che il tuo selettore sia accessibile e coerente con gli altri elementi del tema. Assicurati anche di eseguire l'escape dell'output dinamico utilizzando funzioni come esc_attr() e wp_kses_post() per mantenere sicuro il tuo codice.

Impostare le opzioni nel file config.json

Ogni selettore di valuta personalizzato deve includere un file config.json. Questo file fornisce a WPML Multilingual & Multicurrency for WooCommerce le informazioni di base sul tuo selettore di valuta, come il suo nome e gli eventuali asset CSS o JS di cui ha bisogno.

Campi obbligatori

Il file deve definire il nome del selettore di valuta:

{
  "name": "My custom switcher"
}

Non hai bisogno di aggiungere un prefisso al nome. WPML Multilingual & Multicurrency for WooCommerce lo gestirà automaticamente in base al tema o al plugin a cui appartiene il selettore.

Campi opzionali

Oltre al nome obbligatorio, puoi includere due campi opzionali:

• css: Un elenco di file CSS da caricare dalla tua cartella dei template. Per impostazione predefinita, WPML Multilingual & Multicurrency for WooCommerce metterà automaticamente in coda tutti i file .css nella cartella dei template, ma puoi sovrascrivere questo comportamento con questo campo.

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

• js: Un elenco di file JavaScript da caricare dalla tua cartella dei template. Utilizza solo JavaScript puro, a meno che il tuo tema o plugin non includa già una libreria JS come jQuery.

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

Ecco un config.json completo che include tutti i campi:

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

Aggiungere i template del selettore di valuta alla cartella uploads

Puoi anche memorizzare i template personalizzati del tuo selettore di valuta nella cartella uploads di WordPress. Questo è utile se vuoi mantenere i template al sicuro dagli aggiornamenti del tema o del plugin.

Posiziona i tuoi template nel seguente percorso:

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

WPML Multilingual & Multicurrency for WooCommerce scansiona automaticamente questo percorso alla ricerca di template per i selettori di valuta.

Aggiungere i template del selettore di valuta a un plugin

Se stai creando un plugin e vuoi includere selettori di valuta personalizzati, devi indicare a WPML Multilingual & Multicurrency for WooCommerce dove trovarli.

Usa il filtro wcml_cs_directories_to_scan per registrare la directory dei template. Aggiungi questo codice al file principale del tuo 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' );

WPML Multilingual & Multicurrency for WooCommerce scansionerà quindi la cartella templates all'interno del tuo plugin. Devi posizionare ogni selettore di valuta personalizzato nella sua sottocartella, in questo modo:

my-plugin/templates/my-template/

Esempio completo: selettore di valuta personalizzato

Questo esempio mostra come creare un selettore di valuta completo con la sua cartella, il template, la configurazione e gli stili opzionali.

1. Nel tuo tema o tema child, crea la seguente cartella:

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

1. Crea un file config.json all'interno della cartella:

{
"name": "Custom currency switcher"
}

1. Crea un file template.php per visualizzare la valuta selezionata e un elenco delle altre:
   

<?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. Se vuoi personalizzare l'aspetto, aggiungi un file style.css:

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

Utilizzare i selettori di valuta personalizzati nei template PHP

Una volta creato un selettore di valuta personalizzato, puoi utilizzarlo nei tuoi template PHP richiamando l'azione wcml_currency_switcher.

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

Il valore switcher_style dipende da due cose: la posizione del selettore e il nome definito nel suo config.json. WCML genera lo slug automaticamente utilizzando questo formato:

Posizione del selettore di valuta personalizzato	Come viene generato lo slug
Cartella del tema	Slug del tema + nome del selettore sanificato
Cartella del plugin	Slug del plugin + nome del selettore sanificato
Cartella “uploads”	“uploads-” + nome del selettore sanificato

Quindi, supponiamo che:

• Il tuo tema sia Twenty Seventeen
• Il config.json del tuo selettore contenga:

{ "name": "My custom switcher" }

Allora lo slug generato sarà:

twenty-seventeen-my-custom-switcher

Utilizza questo come valore per switcher_style nello snippet di codice qui sopra.