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

Generates HTML <select> tags and option lists for localized unit-of-measure display.

Units are displayed with their localized display name. The list of units, display style (long, short, narrow), sort order, and display format are all configurable.

Summary

Types

select_options()

Functions

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

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

unit_options(options \\ [])

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

Types

select_options()

@type select_options() :: [
  units: [atom() | binary(), ...],
  locale: Localize.locale() | Localize.LanguageTag.t(),
  collator: function(),
  mapper: (tuple() -> String.t()),
  selected: atom() | binary(),
  style: :long | :short | :narrow
]

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

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

:units is a list of units to be displayed in the select.
:style is the style of unit name to be displayed. The options are :long, :short and :narrow. The default is :long.
:locale defines the locale to be used to localise the description of the units. The default is the locale returned by Localize.get_locale/0.
:collator is a function used to sort the units. The default collator sorts by display name.
:mapper is a function that creates the text to be displayed in the select tag for each unit. It receives a tuple {display_name, unit_code}. The default is the identity function.
:selected identifies the unit 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.Unit.select(:my_form, :unit, selected: :foot)

unit_options(options \\ [])

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

Generates a list of options for a unit 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.Unit.select/3 for options.

Returns

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