Pax.Interface behaviour (Pax v0.0.1-dev.20251023)

View Source

Pax.Interface enables the creation of CRUD interfaces based on Phoenix.LiveView.

The @pax assign

The @pax assign contains information on how to build the page.

This module defines a struct and some helper functions for assigning values into it easily.

Fields

  • module - The module that is using the Pax Interface
  • config - The processed Pax.Config map.
  • adapter - The adapter module to use for the interface
  • plugins - A list of plugins to use for the interface
  • action - The current action being performed, one of :index, :show, :edit, :new or :delete
  • objects - A list of objects to display, for the :index action
  • object - The current object being displayed in :show, :edit or :delete actions
  • object_count - The number of objects in the :objects list
  • path - The path of the URL of the current page, as a %URI{} with only path and query fields set.
  • form - The form to use for the current object in :new or :edit actions
  • singular_name - The singular name of the object
  • plural_name - The plural name of the object
  • object_name - The name of the object being displayed
  • index_path - The path to the index page
  • index_query - An encoded query for the Index page, if any. Used by Detail Interface views for index links.
  • new_path - The path to the new page
  • show_path - The path to the show page
  • edit_path - The path to the edit page
  • fields - A list of fields to display in the index page
  • criteria - A map of various criteria for loading data, see the Criteria section
  • private - A map of private values for pax internals and plugins to use, see the Private section

Criteria

The :criteria map is used to pass information to the data loading callbacks or the adapter for basic operations, such as fetching objects for the index pages, or fetching individual objects for the show, edit and delete pages. The main purpose of the criteria is to decouple the interface and plugins from the process of loading data, so they can concentrate on building the UI and handling user interactions, and just instruct the data loading layer on what to fetch with the given criteria.

Any keys can be set in the criteria, since it's a map, but adapter(s) will only be expecting certain keys to be set, and the interface and plugins will only set certain keys. All of these interactions should be documented in the respective modules.

Example:

%{
  search: "rock",
  filter: %{
    artist_id: 123,
    %{
      field: :release_year,
      op: :>=,
      value: 2000
    }
  },
  order_by: [asc_nulls_first: :rating],
  limit: 10,
  offset: 10,
}

Private

The :private map is used to store data for plugins to use. The private map is keyed by a prefix, which is typically the name of the plugin. This allows plugins to store their own data without interfering with each other. The private map is not intended to be used by the interface or the implementing module using Pax.

Summary

Types

object()

Callbacks

pax_adapter(socket)
pax_config(socket)
pax_init(params, session, socket)
pax_plugins(socket)

Functions

assign_pax(socket_or_assigns, keyword_or_map)
assign_pax(socket_or_assigns, key, value)

Assigns a value to the :pax assign in the socket or assigns map.

assign_pax_criteria(socket_or_assigns, keyword_or_map)
assign_pax_criteria(socket_or_assigns, key, value)

Assigns a value to the :criteria map in the :pax assign in the socket or assigns map.

assign_pax_private(socket_or_assigns, prefix, keyword_or_map)
assign_pax_private(socket_or_assigns, prefix, key, value)

Assigns the value to the :private map under the prefix in the :pax assign in the assigns.

ensure_pax_private(socket_or_assigns, prefix)

Makes sure that the given prefix exists in the :private map in the :pax assign in the socket or assigns map.

Types

object()

@type object() :: %{required(atom()) => any()}

Callbacks

pax_adapter(socket)

@callback pax_adapter(socket :: Phoenix.LiveView.Socket.t()) ::
  nil | module() | {module(), keyword()} | {module(), module(), keyword()}

pax_config(socket)

@callback pax_config(socket :: Phoenix.LiveView.Socket.t()) :: keyword() | map()

pax_init(params, session, socket)

@callback pax_init(
  params :: Phoenix.LiveView.unsigned_params() | :not_mounted_at_router,
  session :: map(),
  socket :: Phoenix.LiveView.Socket.t()
) :: {:cont, Phoenix.LiveView.Socket.t()} | {:halt, Phoenix.LiveView.Socket.t()}

pax_plugins(socket)

@callback pax_plugins(socket :: Phoenix.LiveView.Socket.t()) :: [Pax.Plugin.pluginspec()]

Functions

assign_pax(socket_or_assigns, keyword_or_map)

assign_pax(socket_or_assigns, key, value)

Assigns a value to the :pax assign in the socket or assigns map.

assign_pax_criteria(socket_or_assigns, keyword_or_map)

assign_pax_criteria(socket_or_assigns, key, value)

Assigns a value to the :criteria map in the :pax assign in the socket or assigns map.

assign_pax_private(socket_or_assigns, prefix, keyword_or_map)

assign_pax_private(socket_or_assigns, prefix, key, value)

Assigns the value to the :private map under the prefix in the :pax assign in the assigns.

ensure_pax_private(socket_or_assigns, prefix)

Makes sure that the given prefix exists in the :private map in the :pax assign in the socket or assigns map.