Criar seletores de moedas personalizados usando arquivos de modelo

Muitos sites e temas precisam de um seletor de moedas que corresponda ao seu design personalizado. Aprenda a criar seu próprio seletor de moedas usando PHP.

Entender os modelos PHP para seletores de moedas

Aqui está um exemplo básico de um modelo PHP para um seletor de moedas:

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

Este modelo:

• Abre as tags HTML de contêiner <div> e <ul> que estruturam o seletor
• Exibe a moeda selecionada
• Faz um loop pelas moedas disponíveis
• Gera um item de lista HTML <li> para cada moeda (excluindo a selecionada no momento)
• Gera links clicáveis para alternar a moeda

Agora, vamos ver como criar esses modelos para seus próprios seletores de moedas.

Adicionar um modelo de seletor de moedas ao seu tema

Você pode adicionar um diretório ao seu tema para armazenar seus modelos de seletor de moedas personalizados.

• Se você estiver desenvolvendo um tema que planeja distribuir ou vender, inclua os modelos diretamente no tema. Dessa forma, todos os usuários do seu tema poderão usar os seletores de moedas que você criar.
• Se você estiver personalizando um tema existente, crie os modelos dentro de um tema filho. Isso evita que suas alterações sejam substituídas quando o tema pai for atualizado.

Use a seguinte estrutura de pastas para seus modelos de seletor personalizados:

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

Para construir essa estrutura:

1. Dentro do seu tema (ou tema filho), crie uma pasta chamada wpml. O WPML Multilingual & Multicurrency for WooCommerce usa essa convenção de nomenclatura porque trabalha em conjunto com o WPML.
2. Dentro de wpml, crie uma pasta templates.
3. Dentro de templates, crie uma pasta currency-switchers.
4. Dentro de currency-switchers, crie uma subpasta para cada seletor personalizado que você criar — por exemplo, my-template.

Dentro de cada pasta de seletor personalizado (por exemplo, my-template), você precisará de:

• template.php — Obrigatório. Este é o seu arquivo de modelo PHP principal.
  
• config.json — Obrigatório. Este arquivo fornece ao WCML metadados sobre o seu seletor de moedas.
  
• Qualquer arquivo CSS ou JS opcional — Inclua estes se o seu seletor usar estilo personalizado ou interatividade.

Criar o arquivo template.php

O arquivo template.php define o layout e o comportamento do seu seletor de moedas personalizado. Ele usa PHP padrão e gera o HTML que será renderizado no front-end.

Dentro do seu modelo, você pode usar as seguintes variáveis fornecidas pelo WPML Multilingual & Multicurrency for WooCommerce:

• $css_classes (string): classes CSS aplicadas ao contêiner principal.
• $currencies (array): uma lista de moedas disponíveis.
• $selected_currency (string): a moeda selecionada no momento.
• $format (string): uma string que define como a moeda deve ser exibida.
• WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ): um método estático usado para formatar e exibir cada rótulo de moeda.

Ao escrever seu modelo, siga as melhores práticas de interface de usuário (UI) do WordPress para garantir que seu seletor seja acessível e consistente com outros elementos do tema. Certifique-se também de escapar a saída dinâmica usando funções como esc_attr() e wp_kses_post() para manter seu código seguro.

Definir opções no arquivo config.json

Cada seletor de moedas personalizado deve incluir um arquivo config.json. Este arquivo fornece ao WPML Multilingual & Multicurrency for WooCommerce informações básicas sobre o seu seletor de moedas, como o nome e quaisquer recursos CSS ou JS de que ele precisa.

Campos obrigatórios

O arquivo deve definir o nome do seletor de moedas:

{
  "name": "My custom switcher"
}

Você não precisa adicionar um prefixo ao nome. O WPML Multilingual & Multicurrency for WooCommerce lidará com isso automaticamente com base no tema ou plugin ao qual o seletor pertence.

Campos opcionais

Além do nome obrigatório, você pode incluir dois campos opcionais:

• css: uma lista de arquivos CSS a serem carregados da sua pasta de modelo. Por padrão, o WPML Multilingual & Multicurrency for WooCommerce enfileirará automaticamente todos os arquivos .css na pasta de modelo, mas você pode substituir esse comportamento com este campo.

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

• js: uma lista de arquivos JavaScript a serem carregados da sua pasta de modelo. Use apenas JavaScript puro, a menos que seu tema ou plugin já inclua uma biblioteca JS como o jQuery.

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

Aqui está um config.json completo que inclui todos os campos:

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

Adicionar modelos de seletor de moedas à pasta de uploads

Você também pode armazenar seus modelos de seletor de moedas personalizados na pasta de uploads do WordPress. Isso é útil se você quiser manter os modelos a salvo de atualizações de temas ou plugins.

Coloque seus modelos no seguinte caminho:

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

O WPML Multilingual & Multicurrency for WooCommerce analisa automaticamente esse caminho em busca de modelos de seletor de moedas.

Adicionar modelos de seletor de moedas a um plugin

Se você estiver criando um plugin e quiser incluir seletores de moedas personalizados, precisará informar ao WPML Multilingual & Multicurrency for WooCommerce onde encontrá-los.

Use o filtro wcml_cs_directories_to_scan para registrar o diretório de modelos. Adicione este código ao arquivo principal do seu 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' );

O WPML Multilingual & Multicurrency for WooCommerce analisará a pasta de modelos dentro do seu plugin. Você precisa colocar cada seletor de moedas personalizado em sua própria subpasta, desta forma:

my-plugin/templates/my-template/

Exemplo completo: seletor de moedas personalizado

Este exemplo mostra como criar um seletor de moedas completo com sua própria pasta, modelo, configuração e estilos opcionais.

1. No seu tema ou tema filho, crie a seguinte pasta:

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

1. Crie um arquivo config.json dentro da pasta:

{
"name": "Custom currency switcher"
}

1. Crie um arquivo template.php para exibir a moeda selecionada e uma lista das outras:
   

<?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 você quiser personalizar a aparência, adicione um arquivo style.css:

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

Usar seletores de moedas personalizados em modelos PHP

Depois de criar um seletor de moedas personalizado, você pode usá-lo em seus modelos PHP chamando a ação wcml_currency_switcher.

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

O valor switcher_style depende de duas coisas: a localização do seletor e o nome definido em seu config.json. O WCML gera o slug automaticamente usando este formato:

Localização do seletor de moedas personalizado	Como o slug é gerado
Pasta do tema	Slug do tema + nome do seletor sanitizado
Pasta do plugin	Slug do plugin + nome do seletor sanitizado
Pasta “uploads”	“uploads-” + nome do seletor sanitizado

Então, digamos que:

• Seu tema seja Twenty Seventeen
• O config.json do seu seletor contenha:

{ "name": "My custom switcher" }

Então o slug gerado será:

twenty-seventeen-my-custom-switcher

Use isso como o valor para switcher_style no trecho de código acima.