Localize.HTML.Locale (Localize Web v0.2.0)

Copy Markdown View Source

Generates HTML <select> tags and option lists for localized locale display.

Locales are displayed with their localized display name. A special :identity mode renders each locale's name in its own language. The list of locales, sort order, and display format are all configurable.

Summary

Types

locale()
mapper()
select_options()

Functions

locale_options(options \\ [])

Generates 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 \\ [])

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

Types

locale()

@type locale() :: %{
  locale: String.t(),
  display_name: String.t(),
  language_tag: Localize.LanguageTag.t()
}

mapper()

@type mapper() :: (locale() -> String.t())

select_options()

@type select_options() :: [
  {:locales, [atom() | binary(), ...]}
  | {:locale, Localize.locale() | Localize.LanguageTag.t() | :identity}
  | {:collator, function()}
  | {:mapper, function()}
  | {:selected, atom() | binary()}
  | {atom(), any()}
]

Functions

locale_options(options \\ [])

@spec locale_options(select_options()) :: [tuple()] | {:error, {module(), binary()}}

Generates 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 Localize.HTML.Locale.select/3 for options.

Returns

  • A list of {display_name, locale_string} tuples, or

  • {:error, {module(), binary()}} if validation fails.

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

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

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

Arguments

Options

  • :locales defines the list of locales to be displayed in the select tag. The default is Localize.all_locale_ids/0 with meta locales excluded.

  • :locale defines the locale used to localise the display names. The default is the locale returned by Localize.get_locale/0. If set to :identity then each locale in :locales will be rendered in its own locale.

  • :collator is a function used to sort the locales. The default collator sorts by display name.

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

  • :selected identifies the locale to be selected by default in the select tag. The default is nil.

  • :prompt is a prompt displayed at the top of the select box.

Returns

Examples

iex> Localize.HTML.Locale.select(:my_form, :locale_list, selected: "en")