Heiko Jansen > Mojolicious-Plugin-CountryDropDown-0.06 > Mojolicious::Plugin::CountryDropDown

Download:
Mojolicious-Plugin-CountryDropDown-0.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.06   Source  

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.

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:

AUTHORS ^

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
syntax highlighting: