View Source Cldr.HTML.Locale (Cldr HTML v1.6.0)

Implements an HTML Form select specifically localised locale display.

Summary

Types

locale()
mapper()
select_options()

Functions

locale_options(options \\ [])

Generate a list of options for a locale list that can be used with Phoenix.HTML.Form.options_for_select/2 or to create a <datalist>.

select(form, field, options \\ [])

Generate an HTML select tag for a locale list that can be used with a Phoenix.HTML.Form.t.

Types

Link to this type

locale()

View Source 
@type locale() :: %{
  locale: String.t(),
  display_name: String.t(),
  language_tag: Cldr.LanguageTag.t()
}
Link to this type

mapper()

View Source 
@type mapper() :: (locale() -> String.t())
Link to this type

select_options()

View Source 
@type select_options() :: [
  {:locales, [atom() | binary(), ...]}
  | {:locale, Cldr.Locale.locale_name() | Cldr.LanguageTag.t()}
  | {:collator, function()}
  | {:mapper, function()}
  | {:backend, module()}
  | {:selected, atom() | binary()}
  | {atom(), any()}
]

Functions

Link to this function

locale_options(options \\ [])

View Source 
@spec locale_options(select_options()) ::
  [tuple()] | {:error, {Cldr.UnknownLocaleError, binary()}}

Generate a list of options for a locale list that can be used with Phoenix.HTML.Form.options_for_select/2 or to create a <datalist>.

Arguments

Options

See Cldr.HTML.Locale.select/3 for options.

Link to this function

select(form, field, options \\ [])

View Source 
@spec select(
  form :: Phoenix.HTML.Form.t(),
  field :: Phoenix.HTML.Form.field(),
  select_options()
) :: Phoenix.HTML.safe() | {:error, {Cldr.UnknownLocaleError, binary()}}

Generate an HTML select tag for a locale list that can be used with a Phoenix.HTML.Form.t.

Arguments

Options

For select options see Phoenix.HTML.Form.options_for_select/2

  • :locales defines the list of locales to be displayed in the the select tag. The list defaults to Cldr.known_locale_names/0. If :backend is specified then the list of locales known to that backend is returned. If no :backend is specified the locales known to Cldr.default_backend!/0 is returned.

  • :locale defines the locale to be used to localise the description of the list of locales. The default is the locale returned by Cldr.get_locale/1 If set to :identity then each locale in the :locales list will be rendered in its own locale.

  • :backend is any backend module. The default is Cldr.default_backend!/0

  • :collator is a function used to sort the locales in the selection list. It is passed a list of maps where each map represents a locale. The default collator sorts by locale_1.display_name < locale_2.display_name. As a result, default collation sorts by code point which will not return expected results for scripts other than Latin.

  • :mapper is a function that creates the text to be displayed in the select tag for each locale. It is passed a map with three fields: :display_name, :locale and :language_tag. The default mapper is &{&1.display_name, &1.locale}. See t:locale.

  • :selected identifies the locale that is to be selected by default in the select tag. The default is nil. This is passed to the form generator.

  • :prompt is a prompt displayed at the top of the select box. This is passed unmodified to the form generator.

Notes

If :locale is set to :identity then each locale in :locales will be used to render its own display name. In this case each locale in :locales must also be configured in the :backend or an error will be returned.

Examples 

 Cldr.HTML.Locale.select(:my_form, :locale_list, selected: "en")

 Cldr.HTML.Locale.select(:my_form, :locale_list,
   locales: ["zh-Hant", "ar", "fr"],
   mapper: &({&1.display_name, &1.locale}))