(Quick Reference)

1 Guide - Reference Documentation

Authors: Stefan Armbruster

Version: 0.4

1 Guide

Introduction

A common requirement in many applications is to deal with countries and/or continents. The plugin's goal is to apply the DRY principle to these requirements.

In short, the plugin offers:

populated domain classes for countries and continents
i18n for continent and country names (for now, af, de, en, es fr, it, nb_NO and pt_BR locales)
tags for simple usage of

localized names
select boxes: for all countries, for all continents, for all countries of a continent or for a defined set of countries. The select box contents are automatically sorted by the the localized country/continent name.

In future this plugin will be extended, some ideas are

provide a IP address -> country conversion
add more languages
provide templates for scaffolding

The plugin is licensend under the Apache Public license.

authors and contributors

The plugin is authored by Stefan Armbruster.

Contributors:

Robert Fletcher: translation to Afrikaans (af)
Christopher Kolstad: translation to Norge (nb_NO)
Luxas Teixeira: translations to Spanish (es), French (fr), Italian (it), Portugese (pt_BR)

Installation

Installation is done like every other plugin:

grails install-plugin countries

When starting up the application, the Country and Continent domain classes are populated during the bootstrapping process. The list of available countries is loaded from web-app/countries.csv, web-app/domains.csv and web-app/capitals.csv. If your application needs only a subset of the complete list, copy countries.csv to your app's web-app and remove countries out of scope. If you need the rebuild the complete country list, call 'grails fetch-country-list'.

Domain classes

The plugin contains three domain classes. grails.plugin.countries.Region is an abstract base class for grails.plugin.countries.Country and grails.plugin.countries.Continent. continent and country are related to each other with a bidirectional 1:n relation, so each continent has multiple countries and each country refers to one continent. The Country domain class holds the 2- and 3 letter codes of ISO 3166 as well as the name of country's capital. N.B. the country name itself is not stored in the domain class but is available in i18n properties files by following the convention country.<3 letter code>. So when e.g. lookup up localized names for Germany, you have to use property country.GER. The same applies for continents. Since there seems no standard abbreviation for continents the plugin uses:

AF: Afrika
AS: Asia
OC: Australia
EU: Europe
NA: North America
SA: South America
AN: Antarctica

The domainclasses are populated during Grails' bootstrap process, so we have 252 countries for now.

The author cannot assure that the country data is 100% accurate. If a country is missing in the list, or any errors are found, please file a JIRA.

TagLib

The plugin comes with a taglib providing easy access to localized filenames and for country/continent related select boxes. For details, see the tag description in the left hand frame.

Example

This short example demonstrates the usage and the capabilities of the plugin. It is assumed that you have created some grails project. A domain class Address uses Country :

import grails.plugins.countries.Countryclass Address {
	String street
	String no
	String zip
	String city
	String state
	Country country
}

Assume a gsp used for creating address labels, the controller exposes a Address instance using address:

Placeholder for name
${address.street} ${address.no}
${address.zip} ${address.city} ${address.state}<country:name object="${address.country}"/>

During data entry, a select box should be used. The box should display each available country:

…
<country:select name="country.id" value="${fieldValue(bean:address,field:'country.id')}" noSelection="['':'select please:']"/>
...

release history

0.4.0 2012-09-20

upgrade to Grails 2.1.0
adding spock tests for taglib
upgrade country data from wikipedia
introduced Region as abstract base class

0.2.1

added contributed language nb_NO, cheers to Christopher Kolstad
changed mapping of Country.key and Continent.key to 'ckey' in the database, since some db's don't like 'key' as a column name
introduced Region domain class: Country and Continent are now subclasses of Region
locale dependent sorting using Collators in Taglib

0.2 2010-08-07:

added languages:

af: contributed by Robert Fletcher
es, fr, it, pt_BR: contributed by Lucas Frare Teixeira

country list is now maintained out CountryBootstrap.groovy in a seperate csv file
reworked properties file to consistently use ISO-3166 3-letter-code as key

0.1.1 2010-08-04: bugfix: plugin unusable with Grails <= 1.3.3
0.1 2010-08-04: initial release