Aurora.Uix.Layout.Options behaviour (Aurora UIX v0.1.0)

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

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.

render_binary(assigns, value)

Renders a given value as a binary within a HEEx template.

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.

render_binary(assigns, value)

@spec render_binary(map(), term()) :: Phoenix.LiveView.Rendered.t()

Renders a given value as a binary within a HEEx template.

This helper function is used to safely render a value by embedding it into an assigns map and then rendering it with a ~H sigil. The value is first passed through raw/1 to prevent HTML escaping.

Parameters

  • assigns (map()) - The assigns map for the template.
  • value (term()) - The value to be rendered.

Returns

  • Phoenix.LiveView.Rendered.t() - The rendered HEEx content containing the value.

Examples

iex> assigns = %{}
iex> rendered = Aurora.Uix.Layout.Options.render_binary(assigns, "Hello, World!")
iex> Phoenix.HTML.safe_to_string(rendered)
"Hello, World!"