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

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

Territories are displayed with their Unicode flag emoji and localized name. The list of territories, display style, sort order, and display format are all configurable.

Summary

Types

select_options()

territory()

Territory type passed to a collator for ordering in the select box.

Functions

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

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

territory_options(options \\ [])

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

Types

select_options()

@type select_options() :: [
  territories: [atom() | binary(), ...],
  locale: Localize.locale() | Localize.LanguageTag.t(),
  collator: function(),
  mapper: (territory() -> String.t()),
  selected: atom() | binary(),
  style: :standard | :short | :variant
]

territory()

@type territory() :: %{territory_code: atom(), name: String.t(), flag: String.t()}

Territory type passed to a collator for ordering in the select box.

Functions

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 territory list that can be used with a Phoenix.HTML.Form.t.

Arguments

form is a Phoenix.HTML.Form.t/0 form.
field is a Phoenix.HTML.Form.field/0 field.
options is a Keyword.t/0 list of options.

Options

:territories defines the list of territories to be displayed in the select tag. The default is Localize.Territory.territory_codes/0.
:style is the format of the territory name. The options are :standard (the default), :short and :variant.
:locale defines the locale to be used to localise the description of the territories. The default is the locale returned by Localize.get_locale/0.
:collator is a function used to sort the territories. The default collator sorts by name.
:mapper is a function that creates the text to be displayed in the select tag for each territory. The default function is &({&1.flag <> " " <> &1.name, &1.territory_code}).
:selected identifies the territory that is 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

A Phoenix.HTML.safe/0 select tag, or
{:error, {module(), binary()}} if validation fails.

Examples

iex> Localize.HTML.Territory.select(:my_form, :territory, selected: :AU)

territory_options(options \\ [])

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

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

Arguments

options is a Keyword.t/0 list of options.

Options

See Localize.HTML.Territory.select/3 for options.

Returns

A list of {display_name, territory_code} tuples, or
{:error, {module(), binary()}} if validation fails.