/ 
Mojolicious-Plugin-CountryDropDown-0.06
River stage zero No dependents
/ Mojolicious::Plugin::CountryDropDown

NAME

Mojolicious::Plugin::CountryDropDown - Provide a localizable dropdown where users can select a country

VERSION

version 0.06

SYNOPSIS

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', } }) %]

NAME

Mojolicious::Plugin::CountryDrowDown - use a localized dropdown ("select" field) to let your users select countries in your HTML forms.

VERSION

Version 0.06

WARNINGS

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!

CONFIGURATION

You may pass a hash ref on plugin registration. The following keys are currently recognized:

language

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.

select

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.

prefer

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.

exclude

Array reference with a list of country codes which are removed from the list.

Valid values are country codes known to Locale::Country::Multilingual. Invalid values will be silently ignored. See section "CODESETS" below.

html_attr

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".

names

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

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.

LANGUAGE FALLBACKS

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.

  • 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.

CODESETS

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.

METHODS/HELPERS

country_select_field ( [ $hashref ] )

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.

code2country ( $code [, $language ] )

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.

country2code ( $name [, $language [, $codeset ] ] )

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.

csf_country_list ( [ $hashref ] )

Returns a hash ref indexed by the codes with the country names as values.

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.

Please remember that hashes are unsorted. Therefore, the configuration entries for preferred countries are also ignored.

csf_conf ( [ $hashref ] )

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.

AUTHORS

  • Renee Baecker <module@renee-baecker.de>

  • Heiko Jansen <jansen@hbz-nrw.de>

  • Skye Shaw <sshaw AT lucas.cis.temple.edu>

COPYRIGHT AND LICENSE

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