Skip to content

Using the filter hooks

Jump to bottom
Yordan Soares edited this page Jun 13, 2021 · 3 revisions

States, Cities, and Places for WooCommerce introduced two filter hooks for handling the States and Places in all the available countries.

Available filter hooks

You can use two filter hooks that allows you handling both the list of States and Places:

  • scpwoo_custom_states_xx: It allows you to handle the States of a given country. The xx at the end must be replaced by the two-letter country code in lower case.
  • scpwoo_custom_places_xx: It allows you to handle the Places of a given country. The xx at the end must be replaced by the two-letter country code in lower case.

Note: "States" is the generic name equivalent to first-level administrative divisions likes States, Provinces, Regions, Departments or whatever this subdivision is called in your country. In the same way, "Places" is the generic name equivalent to second-level administrative divisions likes Cities, Municipalities, Districts, Communes or whatever this subdivision is called in your country.

How to use

Below you will find code snippets from three different scenarios that will allow you to easily modify the lists of states and places. These code snippets must be copied to the functions.php file of your current active theme or within a custom plugin (recommended).

For purposes of example, we'll work with the states of Venezuela, but these examples are valid for any country. In the same way, the methods can also be applied to places.

Disabling specific States or Places

In some countries there are very remote states, forest or desert areas where it's very difficult to send packages or where there is not even coverage of shipments. In these cases it is often useful to disable these states (or places) from the drop-down menu.

You can disable country specific states by using the unset() function and passing the variable $states with the keys of the country and each state you want to disable. E.g.: unset($states['VE']['AM']); to disable Amazonas state.

The following code snippet shows an example about how to use the filter hook to disable specific states:

/**
 * Disable specific States of Venezuela
 */

function scpwoo_remove_states_of_venezuela($states) {

  global $states;

  unset($states['VE']['AM']); // Amazonas
  unset($states['VE']['DE']); // Delta Amacuro
  unset($states['VE']['NE']); // Nueva Esparta

  return $states['VE'];
}
// Fire our custom data in States of Venezuela dropdown
add_filter('scpwoo_custom_states_ve', 'scpwoo_remove_states_of_venezuela' );

Adding custom States and Places or overwriting the name of existing ones

Other possible scenarios could be adding new states (which may be unofficial or disputed) or changing the name of an existing one.

In the first case, when you want to add a new state, you have to be sure that the key you are going to use doesn't exist in the current list of States. Then, you need to pass the key of the country and the key of the new state you want to add and a name value. E.g.: $states['VE']['D1'] = 'Los Roques';

In the second case, you have to pass the key of the existing state you want to overwrite and the new name value. E.g.: $states['VE']['LG'] = 'La Guaira';, this state formerly called Vargas.

The following code snippet shows an example about how to use the filter hook to add custom states and overwrite the name of an existing one:

/**
 * Adding custom States to Venezuela
 * or overwriting the name of an existing one
 */

function scpwoo_add_states_of_venezuela($states) {

  global $states;

  // You can add new States...
  $states['VE']['D1'] = 'Los Roques'; // Federal Dependency
  $states['VE']['D2'] = 'La Orchila'; // Federal Dependency
  $states['VE']['D3'] = 'Las Aves'; // Federal Dependency

  // ...or overwriting the name of an existing one
  $states['VE']['LG'] = 'La Guaira'; // Formerly: Vargas

  return $states['VE'];
}
// Fire our custom data in States of Venezuela dropdown
add_filter('scpwoo_custom_states_ve', 'scpwoo_add_states_of_venezuela' );

Adding new States or Places from scratch

Many of the State and Places available in this plugin are submitted by users living in those locations. All of them are reviewed by the maintainers of the plugin using references such as ISO 3166-2, Wikipedia and others.

But there may still be cases where the list has many omissions, places with incorrect or outdated names, areas that no longer belong, or have recently belonged to your country. You may also need to manage your own array keys or just customize from scratch for some reason, such as just showing a region of your country, e.g. The Andean region of Venezuela.

To start with a blank slate, you have to omit the variable of the return function, that is, the function should not receive $states (or $places) as parameter.

The following code snippet shows an example about how to use the filter hook to add new states from scratch:

/**
 * My custom States of Venezuela
 */

//  Skip adding the function parameter...
function scpwoo_my_custom_states_of_venezuela() {  

  // ...to begin customizing your data from scratch
  $states['VE']['VE1'] = 'Táchira'; // Andean State
  $states['VE']['VE2'] = 'Mérida'; // Andean State
  $states['VE']['VE3'] = 'Trujillo'; // Andean State

  return $states['VE'];
}
// Fire our custom data in Provinces of Algeria dropdown
add_filter('scpwoo_custom_states_ve', 'scpwoo_my_custom_states_of_venezuela' );
Clone this wiki locally