User Country

This part of the 4.x documentation is for eZ Publish 4.0, only reference section is common for all eZ Publish 4.x versions as well as eZ Publish 5.x "LegacyStack", please select the version you are using for the most up to date documentation!

The "Country dependent VAT" approach supposes that each of your users can be assigned a country. The next subsections reveal how this can be achieved. Note that the list of available countries and their properties (calling codes, etc.) can be configured from within an override for the "country.ini" configuration file.

Adding a new attribute to a user class

It is necessary to add an attribute of the country datatype to your user class otherwise it will be impossible to assign a country to a user. The following text reveals how this can be done.

Access the "Setup" tab in the administration interface, click "Classes" on the left and select the "Users" class group. You should see the list of classes assigned to this group. Find your user class there and click the "Edit" button located in the same line of the list. You will be taken to the class edit interface.
Select the "Country" datatype from the drop-down list located in the bottom, click the "Add attribute" button and edit the newly added attribute as shown below. The following screenshot shows the fragment of the class edit interface with newly added attribute of the country datatype.

Country Attribute

The system will add a drop-down list called "Country" (the name of the newly added attribute) in the object edit interface for users. You can assign a country to the user that is being edited by selecting the desired country from this list.
Specify the identifier of the newly added attribute in the "UserCountryAttribute" setting located under the "[VATSettings]" section of an override for the "settings/shop.ini" configuration file.

Assigning a country to a user

If your user class contains an attribute of the country datatype then a country can be assigned to a user in one of the following ways:

A new user will be asked to specify his/her country when filling in the registration form.
A site administrator will be able to assign a country to a user when editing a user's details (as described in the "Managing users" section of the "User manual").
A site administrator can add a toolbar that allows a user to change his country "on-the-fly".

Adding a toolbar for customers

It is recommended that you add a possibility for a user to choose his/her country "on-the-fly" using the "User country" toolbar. To do this, add the following line into the "[Toolbar_right]" section of the "settings/siteaccess/example/toolbar.ini.append.php" file where "example" is your siteaccess name:

Tool[]=user_country

This setting instructs the system to display the country selection toolbar on the right. When a user selects a country, the system will immediately update product prices according to the VAT rules specified for the selected country.

In order to avoid problems with content caching, you will have to specify "user_preferred_country" in the "CachedViewPreferences[full]" setting for all siteaccesses. To do this, open the "site.ini.append.php" configuration file located in the "settings/siteaccess/example" directory (replace "example" with the actual name of the siteaccess) and edit it. If the "[ContentSettings]" section of the configuration file already contains something like

CachedViewPreferences[full]=<list_of_user_preferences>

then you will have to append a semicolon and "user_preferred_country" at the end of the line, for example:

CachedViewPreferences[full]=admin_navigation_content=0;
admin_navigation_details=0;<...>;admin_bookmarkmenu=1;
admin_left_menu_width=13;user_preferred_country=''

Note that this configuration line tends to be very long. It is simplified in the example above (a lot of settings were replaced with <...> in order to keep things short).

If the "[ContentSettings]" section does not contain a line that starts from "CachedViewPreferences[full]", create it:

CachedViewPreferences[full]=user_preferred_country=''

If this setting is not specified, your customers will have problems when changing the country (the interface will not be updated because of the cache problem).

Using alternative country datatypes

There is an additional possibility to use an alternative country datatype instead of the built-in country datatype. This means that you can integrate an alternative datatype to the system so that the user's country will be stored in the same way by the datatype, by the VAT rules management interface and by the shop user registration module (shop/userregister). The following list reveals how this can be achieved.

Make sure your datatype's content is either a hash having "value" key or an object capable of getting and setting "value" attribute (like eZPersistentObject). It doesn't matter how the content is actually stored to database, but objectAttributeContent() method must return an array/object. The returned value (usually a country code) is then compared to VAT rules' countries.
Override the "view.tpl" and "edit.tpl" templates located in the "templates/shop/country" directory of the standard design in your datatype extension so that countries can be displayed and edited in the VAT rules management interface and the shop user registration module.