Returns an %Ecto.Changeset{} for tracking entity changes.

Examples

iex> PhoenixKit.Modules.Entities.change_entity(entity)
%Ecto.Changeset{data: %PhoenixKit.Entities{}}

Creates a changeset for entity creation and updates.

Validates that name is unique, fields_definition is valid, and all required fields are present. Automatically sets date_created on new records.

Counts the total number of entity data records across all entities.

Examples

iex> PhoenixKit.Modules.Entities.count_all_entity_data()
243

Counts the total number of entities in the system.

Examples

iex> PhoenixKit.Modules.Entities.count_entities()
15

Counts the total number of entities created by a user.

Examples

iex> PhoenixKit.Modules.Entities.count_user_entities(1)
5

Creates an entity.

Examples

iex> PhoenixKit.Modules.Entities.create_entity(%{name: "brand", display_name: "Brand"})
{:ok, %PhoenixKit.Entities{}}

iex> PhoenixKit.Modules.Entities.create_entity(%{name: ""})
{:error, %Ecto.Changeset{}}

Note: created_by is auto-filled with the first admin or user ID if not provided, but only if at least one user exists in the system. If no users exist, the changeset will fail with a validation error on created_by.

Deletes an entity.

Note: This will also delete all associated entity_data records due to the ON DELETE CASCADE constraint defined in the database migration (V17).

Examples

iex> PhoenixKit.Modules.Entities.delete_entity(entity)
{:ok, %PhoenixKit.Entities{}}

iex> PhoenixKit.Modules.Entities.delete_entity(entity)
{:error, %Ecto.Changeset{}}

Disables data mirroring for all entities.

Examples

iex> PhoenixKit.Modules.Entities.disable_all_data_mirror()
{:ok, count}

Disables definition mirroring for all entities.

Examples

iex> PhoenixKit.Modules.Entities.disable_all_definitions_mirror()
{:ok, count}

Disables the entities system.

Sets the "entities_enabled" setting to false.

Examples

iex> PhoenixKit.Modules.Entities.disable_system()
{:ok, %Setting{}}

Enables data mirroring for all entities.

Examples

iex> PhoenixKit.Modules.Entities.enable_all_data_mirror()
{:ok, count}

Enables definition mirroring for all entities.

Examples

iex> PhoenixKit.Modules.Entities.enable_all_definitions_mirror()
{:ok, count}

Enables the entities system.

Sets the "entities_enabled" setting to true.

Examples

iex> PhoenixKit.Modules.Entities.enable_system()
{:ok, %Setting{}}

Checks if the entities system is enabled.

Returns true if the "entities_enabled" setting is true.

Examples

iex> PhoenixKit.Modules.Entities.enabled?()
false

Dynamic children function for Entities sidebar tabs.

Gets the current entities system configuration.

Returns a map with the current settings.

Examples

iex> PhoenixKit.Modules.Entities.get_config()
%{enabled: false, max_per_user: 100, allow_relations: true, file_upload: false, entity_count: 0, total_data_count: 0}

Gets a single entity by integer ID or UUID.

Returns the entity if found, nil otherwise.

Accepts:

• Integer ID (e.g., 123)
• UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
• Integer string (e.g., "123")

Examples

iex> PhoenixKit.Modules.Entities.get_entity(123)
%PhoenixKit.Entities{}

iex> PhoenixKit.Modules.Entities.get_entity("550e8400-e29b-41d4-a716-446655440000")
%PhoenixKit.Entities{}

iex> PhoenixKit.Modules.Entities.get_entity(456)
nil

Gets a single entity by integer ID or UUID.

Raises Ecto.NoResultsError if the entity does not exist.

Examples

iex> PhoenixKit.Modules.Entities.get_entity!(123)
%PhoenixKit.Entities{}

iex> PhoenixKit.Modules.Entities.get_entity!(456)
** (Ecto.NoResultsError)

Gets a single entity by its unique name.

Returns the entity if found, nil otherwise.

Examples

iex> PhoenixKit.Modules.Entities.get_entity_by_name("brand")
%PhoenixKit.Entities{}

iex> PhoenixKit.Modules.Entities.get_entity_by_name("invalid")
nil

Gets the translation for a specific language on an entity definition.

Returns the translated fields merged with the primary language values as defaults. Returns primary language values if no translation exists.

Examples

iex> get_entity_translation(entity, "es-ES")
%{"display_name" => "Productos", "display_name_plural" => "Productos", "description" => "..."}

Gets all translations for an entity definition.

Returns a map of language codes to translated fields. Only includes languages that have at least one translated field.

Examples

iex> get_entity_translations(entity)
%{
  "es-ES" => %{"display_name" => "Productos", "display_name_plural" => "Productos"},
  "fr-FR" => %{"display_name" => "Produits"}
}

iex> get_entity_translations(entity_without_translations)
%{}

Gets the maximum number of entities a single user can create.

Returns the system-wide limit for entity creation per user. Defaults to 100 if not set.

Examples

iex> PhoenixKit.Modules.Entities.get_max_per_user()
100

Gets the mirror settings for an entity.

Returns a map with mirror_definitions and mirror_data booleans. Defaults to false if not explicitly set.

Examples

iex> PhoenixKit.Modules.Entities.get_mirror_settings(entity)
%{mirror_definitions: true, mirror_data: false}

Gets the sort mode for an entity.

Returns "auto" (sort by creation date, default) or "manual" (sort by position).

Examples

iex> PhoenixKit.Modules.Entities.get_sort_mode(entity)
"auto"

Gets the sort mode for an entity by UUID.

Convenience wrapper that looks up the entity first. Returns "auto" if the entity is not found.

Examples

iex> PhoenixKit.Modules.Entities.get_sort_mode_by_uuid(entity_uuid)
"manual"

Gets summary statistics for the entities system.

Returns counts and metrics useful for admin dashboards.

Examples

iex> PhoenixKit.Modules.Entities.get_system_stats()
%{total_entities: 5, active_entities: 4, total_data_records: 150}

@spec invalidate_entities_cache() :: :ok

Invalidates the cached entity summaries in the Dashboard Registry's ETS table. Called when entity lifecycle PubSub events are received.

Returns the list of active (published) entities.

Examples

iex> PhoenixKit.Modules.Entities.list_active_entities()
[%PhoenixKit.Entities{status: "published"}, ...]

Returns the list of entities ordered by creation date.

Examples

iex> PhoenixKit.Modules.Entities.list_entities()
[%PhoenixKit.Entities{}, ...]

Lists all entities with their mirror status and data counts.

Returns a list of maps suitable for the settings UI.

Examples

iex> PhoenixKit.Modules.Entities.list_entities_with_mirror_status()
[%{id: 1, name: "test", display_name: "Test", data_count: 8, mirror_definitions: true, mirror_data: false}, ...]

@spec list_entity_summaries() :: [map()]

Returns a lightweight list of published entity summaries for sidebar display.

Selects only sidebar-relevant fields without preloading associations.

Checks if an entity uses manual sorting.

Examples

iex> PhoenixKit.Modules.Entities.manual_sort?(entity)
true

Checks if data mirroring is enabled for this entity.

Examples

iex> PhoenixKit.Modules.Entities.mirror_data_enabled?(entity)
false

Checks if definition mirroring is enabled for this entity.

Examples

iex> PhoenixKit.Modules.Entities.mirror_definitions_enabled?(entity)
true

Checks if multilang is globally enabled (Languages module has 2+ languages).

Convenience wrapper around Multilang.enabled?/0.

Examples

iex> PhoenixKit.Modules.Entities.multilang_enabled?()
true

Removes all translations for a specific language from an entity definition.

Examples

iex> remove_entity_translation(entity, "es-ES")
{:ok, %PhoenixKit.Modules.Entities{}}

@spec resolve_language(t(), String.t()) :: t()

Resolves translated fields on an entity struct for a given language.

Merges translations from settings["translations"][lang_code] onto the entity's display_name, display_name_plural, and description fields.

For the primary language (or when no translation exists), returns the entity unchanged. For secondary languages, applies override values where they exist and keeps primary values as defaults.

Examples

iex> resolve_language(entity, "es-ES")
%PhoenixKit.Modules.Entities{display_name: "Productos", ...}

iex> resolve_language(entity, "en-US")  # primary language
%PhoenixKit.Modules.Entities{display_name: "Products", ...}

@spec resolve_languages([t()], String.t()) :: [t()]

Resolves translations on a list of entity structs.

Examples

iex> resolve_languages(entities, "es-ES")
[%PhoenixKit.Modules.Entities{display_name: "Productos"}, ...]

Sets the translation for a specific language on an entity definition.

Merges the provided fields into the existing translation for that language. Empty string values are treated as "remove override" (field falls back to primary).

Examples

iex> set_entity_translation(entity, "es-ES", %{
...>   "display_name" => "Productos",
...>   "display_name_plural" => "Productos"
...> })
{:ok, %PhoenixKit.Modules.Entities{}}

Updates an entity.

Examples

iex> PhoenixKit.Modules.Entities.update_entity(entity, %{display_name: "Updated"})
{:ok, %PhoenixKit.Entities{}}

iex> PhoenixKit.Modules.Entities.update_entity(entity, %{name: ""})
{:error, %Ecto.Changeset{}}

Updates the mirror settings for an entity.

Parameters

• entity - The entity to update
• mirror_settings - Map with keys "mirror_definitions" and/or "mirror_data"

Examples

iex> PhoenixKit.Modules.Entities.update_mirror_settings(entity, %{"mirror_definitions" => true})
{:ok, %PhoenixKit.Entities{}}

Updates the sort mode for an entity.

Valid modes: "auto" (sort by creation date) or "manual" (sort by position).

When switching to manual mode, existing records retain their auto-populated positions from creation order. Admins can then reorder as needed.

Examples

iex> PhoenixKit.Modules.Entities.update_sort_mode(entity, "manual")
{:ok, %PhoenixKit.Modules.Entities{}}

Validates that a user hasn't exceeded their entity creation limit.

Checks the current number of entities created by the user against the system limit. Returns {:ok, :valid} if within limits, {:error, reason} if limit exceeded.

Examples

iex> PhoenixKit.Modules.Entities.validate_user_entity_limit(1)
{:ok, :valid}

iex> PhoenixKit.Modules.Entities.validate_user_entity_limit(1)
{:error, "You have reached the maximum limit of 100 entities"}