Designing Custom Currency Switchers Using Template Files

Dario

Updated

October 18, 2024

Many sites and themes require a custom currency switcher, that follows their design. This tutorial explains how to create custom currency switchers, using HTML templates and without writing PHP.

Introduction to Twig templates for currency switchers

Twig is a popular templating engine and allows to design things using HTML and pseudo code.

The following is an example of a Twig template:

This template does the following:

1. Opens the container DIV and UL tags for the currency switcher.
2. Iterates through different currencies.
3. Outputs a list item (LI) for each currency.
4. Inside each list item, outputs a link that switches to this currency.
5. Outputs the currency template.
6. Closes all the nested tags.

Not too complicated, right? Let’s go over the process of creating such templates for your own currency switchers.

Adding a currency switcher template to your theme

You can add a directory to your theme to hold your custom currency switcher templates. You are selling your theme, include these templates inside it and all your theme’s users will be able to use them. If you are customizing an existing theme, create the custom currency switcher templates in a child theme. This way your edits are not lost every time the theme is updated.

You need to use the following folder structure for the currency switcher templates:

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

This means that you should create a wpml folder inside the root of your theme (or child theme). Don’t be confused by the “wpml” name, this is correct one to use since WooCommerce Multilingual works with WPML, naturally.

Inside the wpml folder, create the templates/currency-switchers folders. Lastly, create subdirectories for the different templates that you create (in our example “my-template”) inside the currency-switchers directory.

You need to create the following files inside your template directory (i.e. “my-template”):

• template.twig file (required)
• config.json file (required)
• CSS files (optional)
• JS files (optional)

Designing the template.twig file

The template.twig file is the main template you are designing and uses the Twig syntax. In this main template, you can use the following variables:

• css_classes (string)
• currencies (array)
• selected_currency (string)
• get_formatted_price (function with 2 arguments: currency and format)
• format (string)

Setting options in the config.json file

Every currency switcher must include a file named config.json. It provides WCML the information about the switcher.

In this files, you can use the following fields:

• name (required): The name of the template. No need to prefix it, WCML will do this with the theme or plugin name. This is the only required field.
• css (optional): By default it will scan and enqueue all existing CSS files in the template directory. However, you can pass a JSON array of CSS files inside the template directory. Example: “css”: [“style.css”, “responsive.css”] .
• js (optional): By default it will scan and enqueue all existing JS files in the template directory. However, you can pass a JSON array of JS files inside the template directory.
• Example: “js”: [“script.js”, “click-script.js”] . Note that the script should be written in pure Javascript except if the theme or plugin includes some other library by itself.

The following example provides the most basic config.json file:

{
"name":           "My custom switcher",
}

 

The following is a more complete example, including additional (optional) fields:

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

Adding a currency switcher template to your uploads folder

You can also place your custom currency switcher(s) into the WordPress uploads folder. This way your templates are safe from being overwritten when your theme or plugin is updated.

To do this, place your custom currency switcher templates into the ../wp-content/uploads/wpml/templates/currency-switchers folder.

WCML automatically scans this path for currency switcher templates.

Adding a currency switcher template to your plugin

For plugins, you need to manually define where WCML need to scan for currency switcher templates. This can be done using the wcml_cs_directories_to_scan hook.

Use the following code in the main plugin’s file.

The templates folder should have one or more sub-folders in it (e.g. ../templates/my-dropdown/ ).

The currency switcher template needs to go into the following folder structure:

../my-plugin/templates/my-template

Currency switcher example

Let’s consider an example of a custom currency switcher with its own CSS classes, structure, and styles.

1. Create your custom template folder in mytheme/wpml/templates/currency-switchers/custom-currency-switcher/
2. Create a config.json file like the following:

{
"name": "Custom currency switcher"
}

3. Create a template.twig file like like the following:

4. To add custom CSS styles, create a style.css file like the following:

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

Using custom currency switchers in PHP templates

WooCommerce Multilingual allows you to use the custom currency switchers you design inside PHP templates. To do this, you need to use the correct slug that identifies your custom currency switcher.

The slug for your custom switcher is generated depending on the sanitized name of your template, as defined in its config.json file, and the template’s location:

Location of the custom currency switcher	How the slug is generated
Theme folder	Theme slug + sanitized switcher name
Plugin folder	Plugin slug + sanitized switcher name
“uploads” folder	“uploads-” + sanitized switcher name

Let’s consider the following example:

The name of your custom currency switcher is My custom switcher.
You are using the Twenty Seventeen theme and the template files for your switchers are located in the theme’s folder.
The slug to use with your custom switcher is twenty-seventeen-my-custom-switcher, as shown in the following example.

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

The PHP code version is best when you manually add the currency switcher to PHP templates.