Aurora.Uix.Layout.Options behaviour (Aurora UIX v0.1.6-rc.4)

Copy Markdown

Provides a framework for defining and retrieving layout-specific options.

Intended to be used by layout modules (e.g., Index, Form, Show) to establish a common interface for handling options. Works by introspecting the calling module to automatically discover available options

Usage

To use this module, you should use Aurora.Uix.Layout.Options, :layout_type in your layout-specific option module, where :layout_type is an atom representing the layout (e.g., :index, :form, :show).

defmodule MyLayout.Options do
  use Aurora.Uix.Layout.Options, :my_layout

  # The `get_default/2` function is required for option discovery.
  def get_default(assigns, :my_option, _default_opts \ []) do
    # implementation
  end
end

Function-valued options

Two distinct function mechanisms are supported, and they are not interchangeable:

  • Layout options (e.g. :page_title, :edit_title, :new_action_label) accept an arity-1 function that receives assigns and returns a Phoenix.LiveView.Rendered.t(). See get_option/3.
  • Resource name/title metadata (set via auix_resource_metadata/3, consumed as assigns.auix.name / assigns.auix.title) additionally accepts a 0-arity function returning a binary(), resolved through parse_value/1. This is what every title, subtitle and action-label default interpolates when building its display string.

Summary

Callbacks

available_options()

Retrieves the list of available options for the layout.

get(assigns, option)

Fetches the value of a specific layout option.

Functions

available_options(layout_type)

Retrieves all available options for a given layout type.

get(assigns, option)

Retrieves a layout option for the given assigns and option key.

get_option(assigns, value, option)

Gets an option value, processing it if it's a function or a title.

parse_value(name)

Normalizes a value into a display binary.

Callbacks

available_options()

@callback available_options() :: list()

Retrieves the list of available options for the layout.

Returns

list(tuple()) - A list of tuples, where each tuple contains the layout type and the option name.

get(assigns, option)

@callback get(assigns :: map(), option :: atom()) :: any()

Fetches the value of a specific layout option.

Parameters

  • assigns (map()) - The assigns map.
  • option (atom()) - The option to retrieve.

Returns

any() - The value of the option.

Functions

available_options(layout_type)

@spec available_options(atom()) :: [atom()]

Retrieves all available options for a given layout type.

It fetches the options from all registered layout option modules and filters them based on the provided layout_type.

Parameters

  • layout_type (atom()) - The type of layout to filter options for (e.g., :index, :form).

Returns

  • list(atom()) - A list of option atoms available for the specified layout type.

get(assigns, option)

@spec get(map(), atom()) :: {:ok, term()} | {:not_found, atom()}

Retrieves a layout option for the given assigns and option key.

This function delegates the option retrieval to specialized modules (ShowOptions, FormOptions, IndexOptions). If the option is not found in any of the delegated modules, it logs a warning and returns a :not_found tuple.

Parameters

  • assigns (map()) - The assigns map, which must contain an :auix key with a %{layout_tree: %{tag: atom, name: binary()}} structure.
  • option (atom()) - The option key to retrieve.

Returns

  • {:ok, term()} - If the option is found, returns a tuple with :ok and the option value.
  • {:not_found, atom()} - If the option is not found or the tag is unsupported.

Examples

iex> assigns = %{auix: %{layout_tree: %{tag: :show, name: "resource"}}}
iex> Aurora.Uix.Layout.Options.get(assigns, :unsupported_option)
{:not_found, :unsupported_option}

iex> Aurora.Uix.Layout.Options.get(%{}, :page_title)
{:not_found, :page_title}

get_option(assigns, value, option)

@spec get_option(map(), term(), atom()) :: {:ok, term()}

Gets an option value, processing it if it's a function or a title.

Parameters

  • assigns (map()) - The assigns map.
  • value (term()) - The value of the option.
  • option (atom()) - The option key.

Returns

  • {:ok, term()} - A tuple with :ok and the processed option value.

parse_value(name)

@spec parse_value(nil | binary() | function()) :: binary()

Normalizes a value into a display binary.

Used to resolve resource name/title metadata (and similar values) into the binary ultimately interpolated into title, subtitle and action-label defaults. Unlike the arity-1 functions accepted by get_option/3 (which receive assigns), this accepts a 0-arity function, letting name/title be computed independently of the render context.

Parameters

  • value (nil | binary() | function()) - The raw value to normalize:

    • nil resolves to "".
    • A binary() is returned as-is.
    • A 0-arity function is called and its result returned.
    • Any other value is converted with to_string/1.

Returns

  • binary() - The resolved display value.

Examples

iex> Aurora.Uix.Layout.Options.parse_value(nil)
""

iex> Aurora.Uix.Layout.Options.parse_value("Product")
"Product"

iex> Aurora.Uix.Layout.Options.parse_value(fn -> "Product" end)
"Product"