Country State Manager (c5.6)

Documentation

Installation

concrete5.6+

Prior to installing Country State Manager you need to manually copy the Country List helper and States Provinces List helper files to create root level overrides. (You do not need to copy the bug-fixed version of the address attribute controller - this file is already fixed in the concrete5.6+ core). The files you need to copy are:

countries.php

  • From: /packages/jl_country_state_manager/helpers/lists/countries.php
  • To: site-root/helpers/lists/countries.php

states_provinces.php

  • From: /packages/jl_country_state_manager/helpers/lists/states_provinces.php
  • To: site-root/helpers/lists/states_provinces.php

Once you have copied these 2 files, run the normal dashboard installer at Dashboard > Install. This will test for the above files and proceed with the normal installation once those files are in place. Once installed, the Country State Manager and associated Import and Export pages are available from Dashboard > World.

concrete5.5.x

Prior to installing Country State Manager you need to manually copy the Country List helper and States Provinces List helper files to create root level overrides. You also need to copy a bug-fixed version of the address attribute controller (this file is already fixed in the concrete5.6+ core). The files you need to copy are:

countries.php

  • From: /packages/jl_country_state_manager/helpers/lists/countries.php
  • To: site-root/helpers/lists/countries.php

states_provinces.php

  • From: /packages/jl_country_state_manager/helpers/lists/states_provinces.php
  • To: site-root/helpers/lists/states_provinces.php

controller.php

  • From: /packages/jl_country_state_manager/models/attribute/types/address/controller.php
  • To: site-root/models/attribute/types/address/controller.php

Once you have copied these 3 files, run the normal dashboard installer at Dashboard > Install. This will test for the above files and proceed with the normal installation once those files are in place. Once installed, the Country State Manager and associated Import and Export pages are available from Dashboard > World.

concrete5.4.2.2 (and earlier versions)

For versions of concrete5 prior to 5.5, you first need to copy the root level overrides as for concrete5.5. However, only a reduced part of Country State Manager is compatible with versions of concrete5 prior to version 5.5. When you run the installer from Dashboard > Add Functionality, only the Import and Export pages of the Country State Manager will be installed and available from Dashboard > World.

This reduced installation provides a minimal method for managing the Countries and States/Provinces lists in concrete5.4.2.2 by exporting and importing the lists as text that can be edited with a text editor.

This addon may also install and function in this reduced capability for even earlier versions of concrete5, but has not been tested to do so.

Upgrades

There is also a possibility that upgrades to this package will require the above files to be copied. When necessary, details will be given in the upgrade/version notes.

Functionality provided

The Country State Manager provides dashboard interfaces to edit the list of Countries and associated list of States and Provinces.

From dashboard pages you can: Add, Copy, Edit, Delete and Sort countries and states within countries. Lists can be exported and imported as text for offline editing and copying between systems.

If the Flags addon is also installed, the Country State Manager will associate national flags with countries.

Other parts of concrete5 such as address fields in forms and the address attribute will then use these revised lists. However, the Country State Manager does not replace such form and attribute elements.

For example, you could use the Country State Manager to add Scotland to the list of countries and add an associated list of Scottish counties. If the Flags addon is installed, the Scottish flag will also be associated. You could then create similar entries for the other countries in the United Kingdom and move them all to the top of the country list.

In the address attribute and address form elements, countries in the United Kingdom would then appear at the top of the select list. Users would be able to select Scotland and counties within Scotland.

Important Limitation

While the edited country and states and provinces lists will be shown in select lists of the address attribute and form elements, other aspects of the display of the address attribute or form elements will not be changed. With the standard concrete5 address attribute and form elements, you will not see  associated flags. Such functionality is outside the scope of the Country State Manager addon.

What the Country State Manager provides is a data interface that other addons may then use to enrich such form elements.

Getting Started

As we have already mentioned Scotland in our example above, our getting started exercise will be to add Scotland to the list.

Go to Dashboard > World > Country State Manager. If the default country list is not already shown, click the Install Defaults button and then Save.

Find the entry for the United Kingdom and click the '+' button to copy it. The Country State Manager will show a warning that there is a duplicate entry. Click on the edit button of the copy and the Edit Country dialog will pop up.

Change the country code to SCT (the ISO code for Scotland) and edit the country name to Scotland. If you have the Flags addon installed, the St Andrew flag will be automatically shown.

Then scroll through the list of States & Provinces - which in this case actually shows UK counties - and delete all those that are not in Scotland by clicking the associated waste bin button.

If any are missing (and the default list from concrete5 may well be out of date), you can use the '+' button to insert a row and add the missing counties. If you want to change the sort order, simply drag rows into place.

As an alternative method, you could export the list of counties, edit the text version of the list, and then import the revised list of counties.

When you are happy with the list, click the save button to close the dialog and return to the country list.

Back in the country list, check everything is OK and then click the save button for the country list.

Congratulations, you have just added Scotland and Scottish counties to the lists. Scotland and Scottish counties will now show as options in the address attribute and all forms that use these lists.

Continuing with the exercise. If, for example, you are managing an eCommerce site for the United Kingdom, you could repeat this for England, Wales and Northern Ireland. Then drag all countries within the UK to the top of the list where they will be easily accessible to your customers on all forms that use this list. While at it, you could also drag the Isle of Man and Jersey to the top of the list.

Further functionality

Other pages in the dashboard enable the Countries list and entire States and Provinces list to be exported as text and then imported from text.

The best way to understand the format required is to look at the exported lists.

When importing, you have the option to Replace or Revise.

Replace will replace any existing list with the imported list.

Revise will use the imported list to modify and append to the existing list, but will not delete any entries that are not in the imported list.

Configuration options

Advanced options provided through constants that can be defined in config/site.php.

  • JL_COUNTRY_STATE_MANAGER_FLAGS_ENABLED - will show flags if the Flags addon is also installed. The default value is true. Define this as false if you do not want to show flags.
  • JL_COUNTRY_STATE_MANAGER_PROTECT_CODES - will prevent country and state codes, once saved, from being modified. This is generally a good idea because messing with existing codes could break information already entered by your users. You can still copy entries and edit the codes in the copies, but once saved the codes are fixed until you delete the entry. The default value is true. Define this as false if you want to allow any code to be edited.
  • JL_COUNTRY_STATE_MANAGER_AUTOSORT - will automatically sort lists into alphabetical order, using the same sort as the default lists in in concrete5. The default value is false because users may well want to change the order of these lists. Define this as true if you want the lists to be automatically sorted and prevent them from being manually sorted.
  • JL_COUNTRY_STATE_MANAGER_ACCORDION - will prevent more than one country being expanded in the display to show states and provinces at a time. The default value is false so multiple countries can be expanded together. Define this as true and expanding one country will contract any other expanded countries.

Caution

Sort order

The address attribute, forms and other users of the Countries list and States & Provinces list generally use the list in the order provided. However, there is no guarantee that all such uses will respect the order you sort the lists into.

If you adjust the sort order, please test all situations where the list are used on your site.

Duplicate entries

The address attribute, forms and other users of the Countries list and States & Provinces list generally use the list as provided. If you have a duplicate entry it will typically be shown twice in a select control. However, there is no guarantee that all such uses will respect duplicate entries.

If you create duplicate entries, please test all situations where the lists are used on your site.

Further integration

The Country State Manager maintains the lists in the models CountryStateManagerCountryList and CountryStateManagerStateList. These models are used to respond to the events on_get_countries_list and on_get_states_provinces_list fired by the list helpers.

Developers wishing to provide further integration of the lists (for example, to create enhanced form elements or attributes) should use these models to access the enhanced lists.

 
Loader::model('country_state_manager/country_list', 'jl_country_state_manager'); 
$cl_obj = new CountryStateManagerCountryList(); 
$country_list = $cl_obj->get _list();

 

Loader::model('country_state_manager/state_list', 'jl_country_state_manager'); 
$sl_obj = new CountryStateManagerStateList(); 
$state_list = $sl_obj->get _list();

 

ISO Country Codes

Country codes are best restricted to the ISO codes as these can be correlated with flags and will provide the best overall internationalisation.