1 Introduction

It uses JavaScript autocomplete to give the user right help. The autocomplete takes into account country name alternatives and different relevance for different countries (see Countries i18n chapter). Moreover, it allows i18n localization of country names, alternatives and also relevancy.

The plugin is based on JavaScript implementation of country selector of Baymard Institute, see project on Github.

Example of rendered country selector:

1.1 Change Log

1.2 Roadmap

• Cashing of parsed i18n country codes
• Translations to CZ

1.3 Known Issues

2 Configuration

2.1 Countries i18n

It allows to set-up following properties for each country:

1. Country Code - Plugin uses ISO 3166-1 alpha-3 codes for countries but you can set your own. Country codes are the values returned when the user submit the country selector. They could be easily mapped to domain class property. Examples: GBR , DEU , etc.
2. Country Name - It is the actual country name the user sees in autocomplete. Examples: United Kingdom , Germany , etc.
3. Country Alternatives - Alternative strings which should be used for autocomplete. When the user starts typing an alternative he should receive a proper country name. Examples: GB Great Britain England UK Wales Scotland Northern Ireland for United Kingdom, DE Bundesrepublik Deutschland for Germany.
4. Relevancy - The relevancy specifies the order of results in autocomplete. Country selector sorts the countries by their relevancy first (higher relevancy ~ higher position in autocomplete) and than alphabetically. Examples: United States relevancy 3.5 , United Kingdom relevancy 2.5

Having these properties in i18n allows to set different values for different locale. It allows for example to set a different relevancy for different locale, i.e. Sweden would have higher relevancy than Switzerland in Sweden locale but this would be vice versa for Switzerland locale.

2.1.1 Countries Customization in i18n

org.grails.plugin.countrySelector.CZE=Czech Republic
org.grails.plugin.countrySelector.CZE.alternatives=CZ Česká Ceska
org.grails.plugin.countrySelector.CZE.relevancy=1.5
org.grails.plugin.countrySelector.DNK=Denmark
org.grails.plugin.countrySelector.DNK.alternatives=DK Danmark
org.grails.plugin.countrySelector.DNK.relevancy=1.5

The country code is the last part of the first property key, the value specifies the country name. Alternatives are space separated names. Similarly, relevancy is used for country position in the country selector.

By default custom property files are merged with the plugin specified. You can set all country specifiactions (name, alternatives, relevancy) or just few of them. The custom specification has higher priority during merging. New countries could be defined if it is required.

You can also decide to use your custom i18n settings by default (for example, this can be used when you would like to define custom country codes, or just reduce the number of possible countries). Set following in Config.groovy

grails.plugin.countrySelector.messageSource.useOnlyCustom = true

2.1.2 Supported Languages

3 Utility Clases

3.1 CountrySelectorService

Example domain class Address.groovy

class Address {
   def countrySelectorService
   String country
   static constraints = {
      country(nullable: false, blank: false, validator: {val, obj ->
               def allowedCountryCodes = obj.countrySelectorService.allowedCountryCodes()
               if(!allowedCountryCodes.contains(val))
                  return "org.grails.plugins.countrySelector.country.notAllowed"
            })
   }
}

The Address class is usually an embedded class placed in groovy/src for a certain domain class. To use the countrySelectorService, you need to inject the service differently:

import grails.util.Holders
class Address {
   String country
   static constraints = {
      country(nullable: false, blank: false, validator: {val, obj ->
               def allowedCountryCodes = obj.countrySelectorService.allowedCountryCodes()
               if(!allowedCountryCodes.contains(val))
                  return "org.grails.plugins.countrySelector.country.notAllowed"
            })
   }
   private static getCountrySelectorService() {
      def grailsApplication = Holders.getGrailsApplication()
      grailsApplication.mainContext.countrySelectorService
   }
}

4 Autocomplete

4.1 jQuery Autocomplete

If you don't want to use this autocomplete and jquery-ui dependency than simply exclude it from BuildConfig.groovy:

compile ':country-selector:0.1' {
   exclude 'jquery-ui'
}

4.2 Twitter Bootstrap Autocomplete

You can set this implementation using the resources (Resource Plugin) in ApplicationResources.groovy:

overrides {
   'country-selector-plugin-js' {
      dependsOn 'country-selector-plugin-bootstrap-js'
   }
}

The Twitter Bootstrap country selector is dependent on bootstrap-typeahead therefore Twitter Bootstrap Grails Plugin is required:

plugins {
…
    runtime ':twitter-bootstrap:2.3.2'
…
}

4.3 Custom Autocomplete

'country-selector-plugin-custom-js' {
   dependsOn 'jquery'
   resource url: 'js/application/customCountrySelectorAutocomplete.js', disposition: 'head'
}
overrides {
   'country-selector-plugin-js' {
      dependsOn 'country-selector-plugin-custom-js'
   }
}

The custom JavaScript autocomplete should follow the implementation of Baymard Institute JavaScript country selector (See Github for more details).