PhoenixKit.Users.CustomFields (phoenix_kit v1.5.1)

Context for managing custom user field definitions.

This module provides functionality to define, manage, and validate custom fields that can be added to user profiles. Field definitions are stored as JSON in the settings table, and actual field values are stored in the user's custom_fields JSONB column.

Field Definition Structure

Each field definition is a map with the following keys:

key - Unique identifier for the field (string)
label - Display label for the field (string)
type - Field type: text, textarea, number, boolean, date, email, url, select, radio, checkbox
required - Whether the field is required (boolean)
position - Display order (integer)
enabled - Whether the field is active (boolean)
validation - Optional validation rules (map)
default - Default value (string)
options - For select/radio/checkbox types (list of strings)

Examples

# Get all field definitions
CustomFields.list_field_definitions()

# Add a new field
CustomFields.add_field_definition(%{
  "key" => "phone",
  "label" => "Phone Number",
  "type" => "text",
  "required" => false,
  "position" => 1,
  "enabled" => true
})

# Get system configuration
CustomFields.get_config()

Summary

Functions

add_field_definition(field_def)

Adds a new field definition.

delete_field_definition(key)

Deletes a field definition by key.

get_config()

Gets the current custom fields system configuration.

get_field_definition(key)

Gets a single field definition by key.

list_enabled_field_definitions()

Returns only enabled field definitions, sorted by position.

list_field_definitions()

Returns the list of all custom field definitions.

reorder_field_definitions(ordered_keys)

Reorders field definitions by updating their position values.

save_field_definitions(definitions)

Saves the complete list of field definitions.

update_field_definition(key, updates)

Updates an existing field definition.

validate_custom_field_value(field_def, value)

Validates a user's custom field value against a field definition.

validate_field_definition(field_def)

Validates a field definition structure.

validate_user_custom_fields(user)

Validates all custom fields for a user against field definitions.

Functions

add_field_definition(field_def)

Adds a new field definition.

Validates the field structure and ensures the key is unique.

Examples

iex> add_field_definition(%{"key" => "phone", "label" => "Phone", "type" => "text"})
{:ok, _setting}

iex> add_field_definition(%{"key" => "phone"})
{:error, "Field with key 'phone' already exists"}

delete_field_definition(key)

Deletes a field definition by key.

Examples

iex> delete_field_definition("phone")
{:ok, _setting}

get_config()

Gets the current custom fields system configuration.

Returns a map with field counts.

Examples

iex> get_config()
%{
  field_count: 5,
  enabled_field_count: 3
}

get_field_definition(key)

Gets a single field definition by key.

Returns nil if not found.

Examples

iex> get_field_definition("phone")
%{"key" => "phone", "label" => "Phone Number", ...}

iex> get_field_definition("nonexistent")
nil

list_enabled_field_definitions()

Returns only enabled field definitions, sorted by position.

Examples

iex> list_enabled_field_definitions()
[%{"key" => "phone", "enabled" => true, ...}]

list_field_definitions()

Returns the list of all custom field definitions.

Examples

iex> list_field_definitions()
[
  %{
    "key" => "phone",
    "label" => "Phone Number",
    "type" => "text",
    ...
  }
]

reorder_field_definitions(ordered_keys)

Reorders field definitions by updating their position values.

Accepts a list of keys in the desired order.

Examples

iex> reorder_field_definitions(["email", "phone", "department"])
{:ok, _setting}

save_field_definitions(definitions)

Saves the complete list of field definitions.

Examples

iex> save_field_definitions([%{"key" => "phone", ...}])
{:ok, _setting}

update_field_definition(key, updates)

Updates an existing field definition.

Examples

iex> update_field_definition("phone", %{"label" => "Mobile Number"})
{:ok, _setting}

iex> update_field_definition("nonexistent", %{})
{:error, "Field with key 'nonexistent' not found"}

validate_custom_field_value(field_def, value)

Validates a user's custom field value against a field definition.

Examples

iex> validate_custom_field_value(%{"type" => "email", "required" => true}, "test@example.com")
:ok

iex> validate_custom_field_value(%{"type" => "email", "required" => true}, nil)
{:error, "Field is required"}

validate_field_definition(field_def)

Validates a field definition structure.

Checks for required keys, valid types, and proper structure.

Examples

iex> validate_field_definition(%{"key" => "phone", "type" => "text"})
:ok

iex> validate_field_definition(%{"key" => "phone", "type" => "invalid"})
{:error, "Invalid field type: invalid"}

validate_user_custom_fields(user)

Validates all custom fields for a user against field definitions.

Returns :ok if valid, or {:error, errors} with a map of field keys to error messages.

Examples

iex> validate_user_custom_fields(%User{custom_fields: %{"phone" => "555-1234"}})
:ok

iex> validate_user_custom_fields(%User{custom_fields: %{"email" => "invalid"}})
{:error, %{"email" => "Invalid email format"}}