One of the lesser known corners of the ex_cldr universe is ex_cldr_html. Its not as mature as the other libraries but I make progress on it when time permits. Today I added Cldr.HTML.Territory
which is a module that implements an HTML select
helper for use in Phoenix
.
By default is returns a list of all known territories, using localised names. The default format is a Unicode flag followed by the standard name.
Background on why “territories” and not “countries”
A country is a political entity, a territory is a geographic one. For international localised applications, what constitutes a country can be a sensitive topic. Hence CLDR uses “region” or “territory”. ex_cldr
uses “territory”.
Where CLDR data differs from ISO3166
Although very closely related, CLDR uses a combination of ISO3166 Alpha-2 codes and UN.M49 for geographic areas that enclose several territories.
Differences between ISO3166 name and CLDR names
As noted in TR35, CLDR takes a more pragmatic approach to territory names. Territory names may not match the official name of the territory, and the English or French names may not match those in ISO 3166. Reasons for this include:
- CLDR favors customary names in common parlance, not necessarily the official names.
- CLDR endeavors to provide names that are not too long, in order to avoid problems with truncation or overflow in user interfaces.
Example in the “th” locale
iex> Cldr.HTML.Territory.select(:my_form, :territory, territories: [:US, :AU],
selected: :IT, locale: "th") |> safe_to_string()
<select id="my_form_territory" name="my_form[territory]">
<option value="AU">🇦🇺 ออสเตรเลีย</option>
<option value="IT" selected>🇮🇹 อิตาลี</option>
<option value="US">🇺🇸 สหรัฐอเมริกา</option>
</select>
Documentation
Generate an HTML select tag for a territory list
that can be used with a `Phoenix.HTML.Form.t`.
Arguments
* A `Phoenix.HTML.Form.t()` form
* A `Phoenix.HTML.Form.field()` field
* A `Keyword.t()` list of options
Options
For select options see Phoenix.HTML.Form.select/4
* `:territories` defines the list of territories to be
displayed in the the `select` tag. The list defaults to
the territories returned by `Cldr.known_territories/0`.
* `:style` is the format of the territory name to be used.
The options are `:standard` (the default), `:short` and `:variant`.
Not all territories have `:short` or `:variant` names in which
case `:standard` is used for those territories.
* `:locale` defines the locale to be used to localise the
description of the territories. The default is the locale
returned by `Cldr.get_locale/1`
* `:backend` is any backend module. The default is
`Cldr.default_backend!/0`
* `:mapper` is a function that creates the text to be
displayed in the select tag for each territory. It is
passed the territory definition as a map containing the keys
`:territory_code`, `:name` and `:flag`. 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`. This
is passed unmodified to `Phoenix.HTML.Form.select/4`
* `:prompt` is a prompt displayed at the top of the select
box. This is passed unmodified to `Phoenix.HTML.Form.select/4`
Limitations
Currently the use of maps to define optgroup
s is not supported.