Création de sélecteurs de devise personnalisés à l’aide de fichiers de modèle

De nombreux sites et thèmes ont besoin d’un sélecteur de devise adapté à leur design personnalisé. Découvrez comment créer votre propre sélecteur de devise en utilisant PHP.

Comprendre les modèles PHP pour les sélecteurs de devise

Voici un exemple de base de modèle PHP pour un sélecteur de devise :

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

Ce modèle :

• Ouvre les balises HTML conteneurs <div> et <ul> qui structurent le sélecteur
• Affiche la devise sélectionnée
• Parcourt les devises disponibles
• Génère un élément de liste HTML <li> pour chaque devise (à l’exclusion de celle actuellement sélectionnée)
• Génère des liens cliquables pour changer de devise

Voyons maintenant comment créer de tels modèles pour vos propres sélecteurs de devise.

Ajouter un modèle de sélecteur de devise à votre thème

Vous pouvez ajouter un répertoire à votre thème pour y stocker vos modèles de sélecteur de devise personnalisés.

• Si vous développez un thème que vous prévoyez de distribuer ou de vendre, incluez les modèles directement dans le thème. Ainsi, tous les utilisateurs de votre thème pourront utiliser les sélecteurs de devise que vous créez.
• Si vous personnalisez un thème existant, créez les modèles dans un thème enfant. Cela évite que vos modifications ne soient écrasées lors de la mise à jour du thème parent.

Utilisez la structure de dossiers suivante pour vos modèles de sélecteur personnalisés :

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

Pour construire cette structure :

1. Dans votre thème (ou thème enfant), créez un dossier nommé wpml. WPML Multilingual & Multicurrency for WooCommerce utilise cette convention de nommage car il fonctionne avec WPML.
2. Dans wpml, créez un dossier templates.
3. Dans templates, créez un dossier currency-switchers.
4. Dans currency-switchers, créez un sous-dossier pour chaque sélecteur personnalisé que vous concevez, par exemple, my-template.

Dans chaque dossier de sélecteur personnalisé (par exemple, my-template), vous aurez besoin de :

• template.php — Requis. Il s’agit de votre fichier de modèle PHP principal.
  
• config.json — Requis. Ce fichier fournit à WCML des métadonnées sur votre sélecteur de devise.
  
• Tout fichier CSS ou JS optionnel — Incluez-les si votre sélecteur utilise un style ou une interactivité personnalisés.

Conception du fichier template.php

Le fichier template.php définit la disposition et le comportement de votre sélecteur de devise personnalisé. Il utilise du PHP standard et génère le code HTML qui sera rendu sur l’interface publique.

À l’intérieur de votre modèle, vous pouvez utiliser les variables suivantes fournies par WPML Multilingual & Multicurrency for WooCommerce :

• $css_classes (chaîne de texte) : classes CSS appliquées au conteneur principal.
• $currencies (tableau) : une liste des devises disponibles.
• $selected_currency (chaîne de texte) : la devise actuellement sélectionnée.
• $format (chaîne de texte) : une chaîne de texte qui définit la manière dont la devise doit être affichée.
• WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ) : une méthode statique utilisée pour formater et afficher chaque étiquette de devise.

Lors de la rédaction de votre modèle, suivez les bonnes pratiques de l’interface utilisateur de WordPress pour vous assurer que votre sélecteur est accessible et cohérent avec les autres éléments du thème. Assurez-vous également d’échapper les sorties dynamiques à l’aide de fonctions telles que esc_attr() et wp_kses_post() pour sécuriser votre code.

Définition des options dans le fichier config.json

Chaque sélecteur de devise personnalisé doit inclure un fichier config.json. Ce fichier fournit à WPML Multilingual & Multicurrency for WooCommerce des informations de base sur votre sélecteur de devise, telles que son nom et les ressources CSS ou JS dont il a besoin.

Champs requis

Le fichier doit définir le nom du sélecteur de devise :

{
  "name": "My custom switcher"
}

Vous n’avez pas besoin d’ajouter de préfixe au nom. WPML Multilingual & Multicurrency for WooCommerce s’en chargera automatiquement en fonction du thème ou de l’extension auquel le sélecteur appartient.

Champs optionnels

En plus du nom requis, vous pouvez inclure deux champs optionnels :

• css : une liste de fichiers CSS à charger depuis votre dossier de modèle. Par défaut, WPML Multilingual & Multicurrency for WooCommerce mettra automatiquement en file d’attente tous les fichiers .css du dossier de modèle, mais vous pouvez remplacer ce comportement avec ce champ.

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

• js : une liste de fichiers JavaScript à charger depuis votre dossier de modèle. N’utilisez que du JavaScript pur, à moins que votre thème ou extension n’inclue déjà une bibliothèque JS comme jQuery.

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

Voici un fichier config.json complet qui inclut tous les champs :

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

Ajouter des modèles de sélecteur de devise au dossier des téléversements

Vous pouvez également stocker vos modèles de sélecteur de devise personnalisés dans le dossier des téléversements de WordPress. Cela est utile si vous souhaitez protéger les modèles des mises à jour de thème ou d’extension.

Placez vos modèles dans le chemin suivant :

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

WPML Multilingual & Multicurrency for WooCommerce analyse automatiquement ce chemin à la recherche de modèles de sélecteur de devise.

Ajouter des modèles de sélecteur de devise à une extension

Si vous créez une extension et que vous souhaitez inclure des sélecteurs de devise personnalisés, vous devez indiquer à WPML Multilingual & Multicurrency for WooCommerce où les trouver.

Utilisez le filtre wcml_cs_directories_to_scan pour enregistrer le répertoire de modèles. Ajoutez ce code à votre fichier d’extension principal :

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 analysera ensuite le dossier templates de votre extension. Vous devez placer chaque sélecteur de devise personnalisé dans son propre sous-dossier, comme ceci :

my-plugin/templates/my-template/

Exemple complet : sélecteur de devise personnalisé

Cet exemple montre comment créer un sélecteur de devise complet avec son propre dossier, modèle, configuration et styles optionnels.

1. Dans votre thème ou thème enfant, créez le dossier suivant :

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

1. Créez un fichier config.json dans le dossier :

{
"name": "Custom currency switcher"
}

1. Créez un fichier template.php pour afficher la devise sélectionnée et une liste des autres devises :
   

<?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 vous souhaitez personnaliser l’apparence, ajoutez un fichier style.css :

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

Utiliser des sélecteurs de devise personnalisés dans des modèles PHP

Une fois que vous avez créé un sélecteur de devise personnalisé, vous pouvez l’utiliser dans vos modèles PHP en appelant l’action wcml_currency_switcher.

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

La valeur switcher_style dépend de deux éléments : l’emplacement du sélecteur et le nom défini dans son config.json. WCML génère le slug automatiquement en utilisant ce format :

Emplacement du sélecteur de devise personnalisé	Comment le slug est généré
Dossier du thème	Slug du thème + nom du sélecteur nettoyé
Dossier de l’extension	Slug de l’extension + nom du sélecteur nettoyé
Dossier « uploads »	« uploads- » + nom du sélecteur nettoyé

Supposons donc que :

• Votre thème est Twenty Seventeen
• Le config.json de votre sélecteur contient :

{ "name": "My custom switcher" }

Alors le slug généré sera :

twenty-seventeen-my-custom-switcher

Utilisez ceci comme valeur pour switcher_style dans l’extrait de code ci-dessus.