Localize.HTML.Subdivision (Localize Web v1.1.0)

Generates HTML <select> tags and option lists for the subdivisions of a territory — US states, Canadian provinces, French departments and so on.

Subdivision codes in CLDR carry their territory: California is :usca, not :ca. The territory is stripped from the option value, so a form receives "ca" and stores the subdivision as it is written in an address. The :full_codes option keeps the CLDR form where the value must remain globally unique.

Summary

Types

select_options()

subdivision()

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

Functions

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

Returns a <select> tag of the subdivisions of a territory.

subdivision_options(options \\ [])

Returns the subdivisions of a territory as a list of {name, code} tuples.

Types

select_options()

@type select_options() :: [
  territory: atom() | binary(),
  locale: Localize.locale() | Localize.LanguageTag.t(),
  collator: function(),
  mapper: (subdivision() -> String.t()),
  selected: atom() | binary(),
  full_codes: boolean()
]

subdivision()

@type subdivision() :: %{
  subdivision_code: String.t(),
  full_code: atom(),
  name: String.t()
}

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

Functions

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

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

Returns a <select> tag of the subdivisions of a territory.

Arguments

form is a Phoenix.HTML.Form.t/0.
field is the field name in form.
options is a keyword list of options.

Options

:territory is the territory whose subdivisions are listed, for example :US. Required.
:locale is any locale returned by Localize.all_locale_ids/0. The default is Localize.get_locale/0.
:full_codes keeps the CLDR subdivision code (:usca) as the option value rather than stripping the territory ("ca"). The default is false.
:selected is the subdivision to mark as selected. Accepts either form of the code.
:collator orders the subdivisions. The default sorts by localized name using Localize.Collation.sort/2, so the order is correct for the locale.
:mapper builds each option from a subdivision/0. The default is &{&1.name, &1.subdivision_code}.

Remaining options are passed to PhoenixHTMLHelpers.Form.select/4.

Returns

A Phoenix.HTML.safe/0 <select> tag, or
{:error, exception} if the territory or locale is invalid.

Examples

Localize.HTML.Subdivision.select(:address, :state, territory: :US)

Localize.HTML.Subdivision.select(:address, :state, territory: :US, locale: :fr)

subdivision_options(options \\ [])

@spec subdivision_options(select_options()) :: [tuple()] | {:error, term()}

Returns the subdivisions of a territory as a list of {name, code} tuples.

Takes the same options as select/3.

Returns

A list of {name, code} tuples, or
{:error, exception} if the territory or locale is invalid.

Examples

iex> {name, code} = Localize.HTML.Subdivision.subdivision_options(territory: :US) |> hd()
iex> {name, code}
{"Alabama", "al"}