Mojolicious::Plugin::CountryDropDown - Provide a localizable dropdown where users can select a country
version 0.06
use Mojolicious::Plugin::CountryDropDown; sub startup { my $self = shift; $self->plugin('CountryDropDown'); ...
In your controller:
get '/' => sub { my $self = shift; $self->csf_conf({ language => 'de' }); # this sets the default language ...
In your template (this time with TemplateToolkit syntax):
[% h.country_select_field({ html_attr => { class => 'shiny', } }) %]
Mojolicious::Plugin::CountryDrowDown - use a localized dropdown ("select" field) to let your users select countries in your HTML forms.
Version 0.06
Version 0.04 was the first public release and considered a beta release!
Version 0.05_0x and later include some extensive API changes and are generally incompatible with 0.04 - so please watch out when updating!
You may pass a hash ref on plugin registration. The following keys are currently recognized:
Language code (string). The language used for the country names.
Valid values are those known to Locale::Country::Multilingual. Invalid values will be silently ignored. See section "LANGUAGE FALLBACKS" below.
Country code (string). Sets the country to be selected by default.
Valid values are those known to Locale::Country::Multilingual. Invalid values (i.e. unknown codes) will be accepted but of course have no effect when generating the form (unless you add artificial country names for these codes using the names config key). See section "CODESETS" below.
names
Array reference with a list of country codes which are put to the top of the select field in the order in which they appear in this list. A spacer option is added after them and before the following list of countries. The countries specified here aren´t currently removed from the following list so that they will appear twice within the select form field. If one of these preferred countries is also "select"ed, the pre-selection will happen in the prepended section of preferred countries.
Valid values are country codes known to Locale::Country::Multilingual. Invalid values will be silently ignored. See section "CODESETS" below.
Array reference with a list of country codes which are removed from the list.
Hash reference whose pairs will be used as HTML attributes within the opening "select" tag. No validation is performed with regard to any HTML doctype!
The attribute "name" will always be set for the "select" element. By default it's value will be "country".
The attribute "id" will also be set for the "select" element by default. The default value is the currently configured value for the "name" attribute. Unlike with the "name" attribute you can remove the "id" attribute by setting the configured value to "undef".
Hash reference with pairs of country codes and associated names. The names specified here will be used instead of the "official" names as provided by Locale::Country::Multilingual. The replacement happens without taking the currently used language into account!
The hash keys have to be country codes from the appropriate codeset! See section "CODESETS" below.
On the other hand you can use this to inject extra "countries" but it's up to you to provide unique codes and translate the names appropriately to the currently used language.
Codeset id as used by Locale::Country::Multilingual. Either LOCALE_CODE_ALPHA_2, LOCALE_CODE_ALPHA_3 or LOCALE_CODE_NUMERIC. By default, 2-letter country codes (LOCALE_CODE_ALPHA_2) are used.
LOCALE_CODE_ALPHA_2
LOCALE_CODE_ALPHA_3
LOCALE_CODE_NUMERIC
This module will use a fallback hierarchy to determine which language it has to use for the country names.
Highest precedence lies with a parameter to the current function call.
Next the value from the configuration is used, if set.
If in use in the application the Mojolicious plugin I18N is used next and asked for the language it chose.
I18N
Finally, if none of the previous methods provided us with a value (or if none of them represented a language that is supported by Locale::Country::Multilingual) the last fallback will be the english language ("en").
Especially if you're using the I18N plugin it's ususally your best option to not explicitly set a language.
Any of the three codesets used by Locale::Country::Multilingual (i.e. ALPHA_2, ALPHA_3 and NUMERIC) are accepted - but you have to make sure that you consistenly use the same codeset across function calls and config values.
ALPHA_2
ALPHA_3
NUMERIC
Helper method that creates the html fragment with the select field.
Optionally takes a hash reference with configuration values. See section "CONFIGURATION" above for values which are currently allowed / recognized. These values override the current configuration but are used only for the current method call.
Returns the name for the given country code. The code can be from any of the three supported codesets.
my $code = 'DE'; # ALPHA_2 code my $name = $app->code2country($code); # returns "Germany" unless a # different language was set
From which language the name is taken is determined by following the fallback hierarchy described above.
Optionally you may specifiy the language to use as second param.
my $lang = 'fr'; my $name = $app->code2country( $code, $lang ); # returns "Allemange"
The value of the language parameter is used only for the current method call.
Returns the code for the given country name:
my $code = $self->country2code( 'Allemange', 'fr' ); # returns "DE" my $code = $self->country2code( 'Deutschland', 'de', 'NUMERIC' ); # returns "276"
Make sure that the name is given in the currently configured default language or specifiy the language as second param!
If you want to get a code from a different codeset than the default ALPHA_2 you can specifiy the codeset as third param. If you want to specifiy a codeset but no language you need to pass an undefined value as second param.
The values given for the language and codeset parameters are used only for the current method call.
Returns a hash ref indexed by the codes with the country names as values.
Please remember that hashes are unsorted. Therefore, the configuration entries for preferred countries are also ignored.
Returns a hash ref with the current configuration if no param is given. Otherwise resets or updates configuration values, depending on the contents of the hash ref. See section "CONFIGURATION" above for the hash keys which are currently allowed / recognized.
$c->csf_conf( { language => 'en', select => 'DE', prefer => [ 'DE', 'AT', 'CH', ], attr => { class => 'shinycss', id => 'myId', } })
The actions taken depend on the content of the hash:
If there's no key for a configuration entry the currently configured value is retained.
If there is a key for a configuration entry but the value is undef the respective configuration entry is removed (or reset to it's default value).
If there is a key for a configuration entry and it carries a non-undef value, then that value replaces the configured value.
There is no way to "modify" a configuration entry (e.g. append additional html attributes)!
If the hash is empty (i.e. if you call $c->csf_conf({})), the whole configuration is reset.
$c->csf_conf({})
Renee Baecker <module@renee-baecker.de>
Heiko Jansen <jansen@hbz-nrw.de>
Skye Shaw <sshaw AT lucas.cis.temple.edu>
This software is Copyright (c) 2012 by Hochschulbibliothekszentrum NRW (hbz).
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007
To install Mojolicious::Plugin::CountryDropDown, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious::Plugin::CountryDropDown
CPAN shell
perl -MCPAN -e shell install Mojolicious::Plugin::CountryDropDown
For more information on module installation, please visit the detailed CPAN module installation guide.