# `Localize.HTML.Territory`
[🔗](https://github.com/kipcole9/localize_web/blob/main/lib/localize/html/territory.ex#L1)

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.

# `select_options`

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

# `territory`

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

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

# `select`

```elixir
@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 `t:Phoenix.HTML.Form.t/0` form.

* `field` is a `t:Phoenix.HTML.Form.field/0` field.

* `options` is a `t: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 `t: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`

```elixir
@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 `t: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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*