Advanced operations#

Custom currency template#

Each of the currency switcher themes (such as dropdown list and buttons) have their own methods of displaying the currencies to make them look pretty and be functional. For example, the dropdown list will display the currencies like this: 

US Dollars (USD)  
Pounds Sterling (GBP)  
Euros (EUR)`

And the buttons theme will display them next to each other like this: 

USD   GBP   EUR

The display method, however, is highly customizable. It can be customized in Custom currency template field in Display section in WooCommerce All in One Currency Converter settings. To use default display settings for each switcher theme, leave this field empty. To customize it, you can use the following tags:

  • %code%
  • %name%
  • %symbol%

For example, to have the currencies displayed like this (regardless of chosen switcher theme): 

US Dollars - $ - USD  
Pounds Sterling - £ - GBP  
Euros - € - EUR

Use the following template: %name% - %symbol% - %code%

You may also want to, for example, use just the currency symbol (looks very good in buttons switcher theme). All it takes is just type in this template: %symbol%

You may also want to add some text to it, for example "Currency:" text before each currency name and its symbol in brackets. This is how to do it: Currency: %name% (%symbol%)

It really couldn't be any easier!

Custom CSS rules#

Every currency switcher theme can be easily customized visually because CSS classes are attached to each component of the switcher. To customize the way switcher is displayed, go to Display section in plugin settings and type in your CSS rules into the Custom CSS rules field. CSS classes differ for each switcher theme.

<div class="wcaiocc-switcher-dropdown wcaiocc-container">
    <p class="wcaiocc-text">{currency switcher text}</p> 
    <select class="wcaiocc-select" name="wcaiocc_change_currency_code">
        <option class="wcaiocc-option" value="{currency code}">
            {currency entry}
        </option>
    </select>
</div>

  • .wcaiocc-switcher-dropdown.wcaiocc-container is the main <div> container for the dropdown list switcher

  • .wcaiocc-text is the <p> paragraph with text specified in plugin settings

  • .wcaiocc-select is the <select> dropdown list containing currencies

  • .wcaiocc-option is the <option> item with each currency

Buttons#

<div class="wcaiocc-switcher-buttons wcaiocc-container">
    <p class="wcaiocc-text">{currency switcher text}</p> 
    <ul class="wcaiocc-list">
        <li class="wcaiocc-list-item">
            <a data-wcaiocc-currency="{currency code}" class="wcaiocc-list-item-link" href="" onclick="return false;">{currency entry}</a>
        </li>
    </ul>
</div>

  • .wcaiocc-switcher-buttons.wcaiocc-container is the main <div> container for the currency buttons

  • .wcaiocc-text is the <p> paragraph with text specified in plugin settings

  • .wcaiocc-list is the <ul> list containing currencies

  • .wcaiocc-list-item is the <li> item with each currency link

  • .wcaiocc-list-item-link is the <a> link with each currency

To change how the switcher is displayed, use the classes listed above and type the CSS code in Custom CSS rules field. For example, to change the buttons border color to red in Buttons theme, type in the following CSS rule: 

.wcaiocc-switcher-buttons.wcaiocc-container a.wcaiocc-list-item-link {  
    border-color: #FF0000;  
}

Doesn't look very pretty with this red border but you get the idea!

You will find it much easier to customize the themes if you take a look at the default Currency Converter CSS file. You can find it in css/wcaiocc-frontend.css in plugin folder. It is well-commented and easy to understand. You can use it as a template to write your own CSS rules and then paste them into Custom CSS rules field. The actual file used by the plugin is the minified version (wcaiocc-frontend.min.css), but the unminified one is more human-readable. Inspect element feature available in modern browsers (Chrome, Firefox, Opera, IE etc.) is a very useful tool in customizing the switcher themes.

WordPress filters#

WooCommerce All in One Currency Converter makes good use of WordPress filters functionality. For more information on filters, please see WordPress Codex pages, especially add_filter() function reference.

Below you can find a list of filters used by WooCommerce All in One Currency Converter.

wcaiocc_currency_switcher_output_html
#

  • Usage
<?php
function filter_switcher_html( $html_output, $params ) {
    // Process switcher HTML here  
    return $html_output;  
}  
add_filter( 'wcaiocc_currency_switcher_output_html', 'filter_switcher_html', 10, 2 );
?>
  • Parameters

This filter passes 2 parameters to the function. You can use them to either manipulate the final currency switcher HTML output or build a brand new currency switcher with this data. The function called by wcaiocc_currency_switcher_output_html filter must return an HTML code (string).

  • $html_output
    (string) Final HTML code of currency switcher

  • $params
    (array) Array with parameters. The following parameters are supplied under these array keys:

    • 'theme_id' => name of the theme (string),
    • 'active_currency' => active currency code (string),
    • 'available_currencies' => list of all available currency codes (array),
    • 'base_currency' => currency code of active currency (string),
    • 'currencies_data' => all available currencies data indexed by currency code, each currency has the following data: 'order' (int - order of the currency on currencies list), 'name' (string - currency name), 'symbol' (string - currency symbol), 'position' (string - currency symbol position), 'thousand_separator' (string), 'decimal_separator' (string), 'number_decimals' (int), 'rate' (float - currency exchange rate in relation to store's base currency), 'api' (string - currency exchange rate API) (array)    
    • 'currency_switcher_text' => text appearing above the currency switcher (string),
    • 'currency_display_template' => active currency switcher theme (string)

It is possible to use WooCommerce All in One Currency Converter backend to perform currency-switching handling and develop a completely new frontend for it. In other words - you can completely rewrite the currency switcher component. All you need to do to change the currency is send POST data to a website with WooCommerce All in One Currency Converter plugin activated. With data provided in wcaiocc_currency_switcher_html filter you can rebuild the currency switcher any way you want. To perform a currency switch send the following POST data:

'wcaiocc_change_currency_code' => $currency_code

where $currency_code is a currency code (string), for example EUR or USD. When this POST data is received, the currency will be switched to the one supplied, provided this currency has been made available in plugin settings. Otherwise, the currency will be switched to the default one.

wcaiocc_checkout_total_in_base_currency_html
#

  • Usage 
<?php
function filter_checkout_total_html( $html_output ) {  
    // Process HTML here
    return $html_output;  
}  
add_filter( 'wcaiocc_checkout_total_in_base_currency_html', 'filter_checkout_total_html', 10 );
?>
  • Parameters

This filter passes 1 parameter to the function. The function called by wcaiocc_checkout_total_in_base_currency_html filter must return an HTML code (string).

  • $html_output
    (string) Final HTML code of "Total payment:" section

You can use this filter to change the output of "Total payment:" bit on checkout pages. This filter has an effect only when 2 conditions are met: you are using reference conversion method and you have enabled option to show final payment price in store's default currency before redirecting to payment site. By default this filter returns this: 

<br /><span class="wcaiocc_checkout_total_in_base_currency">%s %s</span>

Two placeholders (string) are used to show "Total payment:" part and the actual payment amount with formatted base currency.

wcaiocc_visitor_country_code
#

  • Usage
<?php
function change_visitor_country_code( $country_code ) {  
    $new_country_code = 'PL'; // force Poland to be default geolocated country
    return $new_country_code;
}  
add_filter( 'wcaiocc_visitor_country_code', 'change_visitor_country_code', 10 );
?>
  • Parameters

This filter passes 1 parameter to the function. The function called by wcaiocc_visitor_country_code filter must return a valid 2-digit ISO 3166-1 country code (string).

  • $country_code
    (string) Visitor's country code

You can use this filter to use your own geolocation methods. Some hosting providers cache mechanisms are not allowing PHP IP geolocation and they provide custom solutions, which can be implemented using this filter. This filter will only be called when geolocation is active.

wcaiocc_{currency_code}_exchange_rate_update_value
#

  • Usage
<?php
function change_eur_exchange_rate( $value ) {  
    // Add 0.2 markup to EUR exchange rate:
    $value = $value + 0.2;  
    return $value;  
}  
add_filter( 'wcaiocc_eur_exchange_rate_update_value', 'change_eur_exchange_rate', 10 );
?>
  • Parameters

This filter passes 1 parameter to the function. The function called by wcaiocc_{currency_code}_exchange_rate_update_value filter should return an exchange rate value for the specified currency (float).

  • $value
    (float) Exchange rate for the currency specified in filter name

You can use this filter to apply markup to any of the additional currencies. For example, if you always want to add 0.5 to one of the currencies used in your store, you can hook into this filter and add 0.5 to the exchange rate value. That way every time currency exchange rate is updated, you will have it increased by 0.5.

wcaiocc_currency_switcher_themes
#

  • Usage
<?php
function add_new_switcher_theme( $themes ) {  
    // Check if theme is not already on the list:
    if (!array_key_exists('some_new_theme', $themes)){  
        // Add new theme to themes array:  
        $themes['some_new_theme'] = array(  
            'name' => 'Some new theme',  
            'image_url' => 'http://mywebsite.com/switchers/somenewtheme.png'  
        );  
    }  
}  
add_filter( 'wcaiocc_currency_switcher_themes', 'add_new_switcher_theme', 10 );
?>
  • Parameters

This filter passes 1 parameter to the function. The function called by wcaiocc_currency_switcher_themes filter should return array with all switcher themes (array).

  • $themes
    (array) Array with all switcher themes. It is a multidimensional array - each array item is an array. Each theme array must be identified by a unique key and must include a name field and image_url field. Both values are used only in plugin settings in WordPress Admin panel.

This filter is used just to register new switcher themes. The actual switcher theme must be included using another filter - wcaiocc_currency_switcher_theme_{theme_id} (described below).

wcaiocc_currency_switcher_theme_{theme_id}
#

  • Usage

Please refer to woocommerce-all-in-one-currency-converter/inc/wcaiocc-switcher-themes.php file to see real-life example on how to create themes.

  • Parameters

This filter passes 2 arguments to the function. The function called by wcaiocc_currency_switcher_theme_{theme_id} filter should return a full HTML output of the switcher. The {theme_id} used in filter name is the theme id used as an array key in wcaiocc_currency_switcher_themes filter.

  • $content
    (string) Fully HTML code of the switcher, including its logic (highlighting selected currency, listing all available currencies etc.)

  • $params
    (array) Parameters allowing you to properly form the currency switcher. The following parameters are supplied within the array: 'theme_id' (string), 'active_currency' (string), 'available_currencies' (array), 'base_currency' (string), 'currencies_data' (array), 'currency_switcher_text' (string), 'currency_display_template' (string).

In order to apply any value to this filter, you need to register the theme using the wcaiocc_currency_switcher_themes filter first. The array key the theme is registered under is the theme id you need to use when hooking into wcaiocc_currency_switcher_theme_{theme_id} filter.

Please keep in mind that the actual currency switch event is happening by sending POST data to the site. This can be done via HTML, but it is much easier to do it via JavaScript or jQuery. To see how it's done in the default themes supplied with the plugin, please see the woocommerce-all-in-one-currency-converter/js/wcaiocc-frontend.js file.

The actual POST data sending is made as simple as possible - plugin automatically creates invisible form which submits the data to server. All you have to do when creating a theme is to hook into your theme's currency switch event, assign the currency code to the form input and submit the form. This should be done like this: 

$('#wcaiocc-currency-input').val('EUR'); // assign currency code to invisible input field...  
$('#wcaiocc-currency-form').submit(); // ...and submit the form

wcaiocc_max_currencies_number
#

  • Usage
<?php
function change_max_allowed_currencies_number( $currencies_number ) {  
    // Allow plugin to use 50 different currencies:
    return 50;
}  
add_filter( 'wcaiocc_max_currencies_number', 'change_max_allowed_currencies_number', 10 );
?>
  • Parameters

This filter passes 1 argument to the function. The function called by wcaiocc_max_currencies_number filter should return a number (int) specifying how many currencies can be added in the plugin settings (Currencies section).

  • $currencies_number
    (int) Maximum number of currencies allowed in the plugin.

wcaiocc_custom_item_price_final
#

  • Usage
<?php
function change_product_price( $final_price, $price, $product ) { 
    return $final_price * 2; // return final price multiplied by 2
}  
add_filter( 'wcaiocc_custom_item_price_final', 'change_product_price', 10, 3 );
?>
  • Parameters

This filter passes 3 arguments to the function. The function called by wcaiocc_custom_item_price_final filter should return a number (float) specifying what is the final price of the specific product.

  • $final_price
    (float) Final price of the product

  • $price
    (float) Product price before plugin's conversion

  • $product
    (WC_Product) WooCommerce product object

wcaiocc_custom_reference_price_final
#

  • Usage
<?php
function change_display_product_price( $final_price, $price ) { 
    return $final_price * 2; // return final price multiplied by 2
}  
add_filter( 'wcaiocc_custom_reference_price_final', 'change_display_product_price', 10, 2 );
?>
  • Parameters

This filter passes 2 arguments to the function. The function called by wcaiocc_custom_reference_price_final filter should return a number (float) specifying what is the final price of the specific product.

  • $final_price
    (float) Final price of the product

  • $price
    (float) Product price before plugin's conversion

WordPress shortcodes#

WooCommerce All in One Currency adds couple of useful shortocodes to your WordPress environment. Shortcodes can be used on pages, posts, product descriptions etc.

wcaiocc_switcher
#

  • Usage

[wcaiocc_switcher]

  • Attributes

This shortcode does not have any attributes.

This shortcode is used to display the currency switcher. For more information, please refer to Displaying switcher via shortcode section.

wcaiocc_convert
#

  • Usage

[wcaiocc_convert price="10" format_price="false" round_decimals="true" from_currency="EUR" to_currency="GBP"]

  • Attributes

This shortcode has 5 attributes

  • price
    (required) The price you want to convert

  • format_price
    (optional) (true/false) If false, the price will be formatted using the default WooCommerce price formatting functions. If true, price will be formatted using currency formatting options specified for the target currency. If not specified, attribute is set to true.

  • round_decimals
    (optional) (true/false) If true, the decimals will be rounded. If not specified, attribute is set to false.

  • from_currency
    (optional) Code of the currency you are converting from. If not specified, attribute is set to your base currency.

  • to_currency
    (optional) Code of the currency you are converting to. If not specified, attribute is set to your active currency.

This shortcode is used to convert values to other currencies in your posts, pages, products etc. This shortcode does not have any content and does not have a closing tag, everything is specified using the attributes.