NAME

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

VERSION

version 0.0503

SYNOPSIS

    use Mojolicious::Plugin::CountryDropDown;

    sub startup {
        my $self = shift;

        $self->plugin('CountryDropDown');
        ...

In your controller:

    get '/' => sub {
        my $self = shift;

        $self->country_select_field_conf({ lang => 'de' }); # this sets the default language 
        ...

In your template (this time with TemplateToolkit syntax):

    [% h.country_drop_down({ lang => 'fr', attr => { class => 'shiny', } }) %]

NAME

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

VERSION

version 0.0502

NAME

Mojolicious::Plugin::CountryDrowDown - use a dropdown ("select" field) to select countries in your form.

WARNINGS

Version 0.04 was the first public release and considered a beta release! Version 0.05_02 includes some API changes and there may be some more coming before version 0.06 is released - so please watch out when updating!

CONFIGURATION

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

lang

Language code. The default language for the country names. Valid values are those known to Locale::Country::Multilingual|Locale::Country::Multilingual.

selected

Country code (ISO 3166 Alpha 2). Sets the country to be selected by default. Valid values are those known to Locale::Country::Multilingual|Locale::Country::Multilingual.

prefer

Array reference pointing to 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 "selected", the pre-selection will happen in the prepended section of preferred countries (and only there).

attr

Hash reference whose pairs will be used as HTML attributes within the opening "select" tag. No validation is performed in regard to any HTML doctype!

Please refer to the Locale::Country::Multilingual docs for a list of available languages. If you specify an unsupported language, or no "lang" at all, "en" will be used as fallback / default!

The attribute "name" will always be set for the "select" element. By default it´s value will be "country".

The attribute "id" will be set for the "select" element by default, too. Again the default value is "country". Unlike the "name" attribute you can remove this attribute by setting the value to "undef".

METHODS/HELPERS

code2country

Returns the name for the given country code (ISO 3166 Alpha 2).

    my $code = 'DE';
    my $name = $self->code2country($code); # returns "Germany" unless a
                                           # different default language was set

The currently configured value is used to determine the language of the country name. Optionally you may specifiy the language to use as second param.

    my $lang = 'fr';
    my $name = $self->code2country( $code, $lang ); # returns "Allemange"

The language given as second argument is used only for the current method call.

country2code

Returns the Alpha 2 code for the given country name:

    my $code = $self->country2code( 'Allemange', 'fr' ); # returns "DE"

    my $code = $self->country2code( 'Deutschland', 'de' ); # returns "DE"

Make sure that the name is given in the currently configured default language or specifiy the language as second param!

The language given as second argument is used only for the current method call.

countrysf_conf

Updates the configuration of default values. Takes a hash ref. See "CONFIGURATION" above for values which are currently allowed / recognized. Would typically be used within the program code, not the template.

    $c->country_conf( {
        lang      => 'en',
        selected  => 'DE',
        preferred => [ 'DE', 'AT', 'CH', ],
        attr      => { class => 'shinycss', id => 'myId', }
    })

Configuration values are updated / added; i.e.: if you omit the key "selected" in this method call it´s former value will be retained. You need to explicitly set any value to "undef" to remove it.

This rule also applies to "attr": Keys present there are preserved unless explicitly overwritten or set to "undef".

countrysf_conf_reset

Removes or resets all configuration values.

country_select_field

Helper method that creates the html fragment with the select field.

Optionally takes a hash reference with configuration values. See "CONFIGURATION" above for values which are currently allowed / recognized. These values are used only for the current method call.

get_country_list

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

You may pass a language code as param to determine the language used for the country names.

AUTHORS

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

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

• Skye Shaw <shaw [at] cpan.org>

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

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

cpanm Mojolicious::Plugin::CountryDropDown

perl -MCPAN -e shell
install Mojolicious::Plugin::CountryDropDown