Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Geography

Geography

When you need an internationalized list of countries and their corresponding sub-countries (states/provinces), you can use the com.elasticpath.domain.misc.Geography class.

Key classes and files

  • GeographyImpl - For retrieving locale specific list of countries and sub-countries
  • Application - The bootstrapping class in cmclient.
  • ResourceRetrievalServiceImpl - Service used by the cmclient rcp application to retrieve resources from the server remotely
  • PropertiesDaoImpl - Provides loading mechanism of the properties files.
  • country.properties - This file lists the ISO 3166-2 country codes and their string values.
  • subcountry.XX.properties - This file lists the ISO 3166-2 subregion codes and their string values.XX is the ISO 3166-2 country code for the subregions country.

How the Geography Class works

The Geography class requires that the properties files containing geography information is loaded up into its properties map before use. This is done in the domainModel.xml using the com.elasticpath.persistence.dao.impl.GeographyPropertiesDaoLoaderFactoryImpl. This class reads the list of country and subcountry property files.

  1. On startup of the Commerce Manager application, the Spring context is loaded and set to ServiceLocator class
  2. The Geography singleton can be obtained using ServiceLocator.getService(ContextIdNames.GEOGRAPHY) and can be used anywhere in CM to retrieve a map of countries with internationalized names.
i.e.  geography.getCountryDisplayName(tax.getRegionCode(), Locale.getDefault());

Configuration

Properties files are stored under com.elasticpath.core/WEB-INF/conf/resources.

How Country Files Work

Country names and subregions are stored in two country properties files:

  • country.properties - stores ISO 3166-2 country codes and the country string values.
  • subcountry.XX.properties - stores the subregions of the country defined in the country.properties file. XX is the ISO 3166-2 country code for the for the subregion's parent country.

For example, Canada would be defined as CA=Canada in the country.properties and Canada's subregions would be defined in the country.CA.properties file.

Country and Subregion Formats

country.properties follow this format: XX=COUNTRY. The first two letters XX is the ISO 3166-2 country code and COUNTRY is the value shown in Cortex and Commerce Manager. Example:

CA=Canada
BE=Belgium

subcountry.XX.properties follow this format: XX=SUBREGION. The first two letters XX is the ISO 3166-2 subregion code and SUBREGION is the value shown in Cortex and Commerce Manager. Example:

AB=Alberta
BC=British Columbia

Customizing the Display Order for Countries and Subregions

Countries and subregions are, by default, sorted and displayed alphabetically. You can customize the display order. To customize the Country order, define an index value for the country code. For example, if you wanted Canada to display first and Belgium to display second, you would write the following in country.properties:

1=CA
2=BE
CA=Canada
BE=Belgium

To customize the subregion order, define and index value for the subregion. For example, if you wanted Yukon to display first and then Saskatchewan to display second, you would write the following in country.CA.properties:

1=YT
2=SK
SK=Saskatchewan
YT=Yukon
Warning:

Unexpected results may occur if the countries and subregions are not defined in the proper format.

Notes

  • To retrieve sub countries for a given country, you need to pass in the country code.
  • Sub Countries are keyed by country code. Here's a helper method to convert a country code from a country's name if you already have the map of countries.
private String getCountryCode(final String country) {
  String code = "";
  if (countryMap \!= null) {
  Map.Entry<String, String> entry = null;
  for (final Iterator< ? > itr = countryMap.entrySet().iterator(); itr.hasNext();-) {
    entry = (Map.Entry) itr.next();
    if (entry.getValue().equalsIgnoreCase(country))
    { 	code = entry.getKey();
    }
  }
  return code;
}