Leading manufacturer of innovative products
", "industry" => "Manufacturing", "founded_date" => "1950-03-15", "featured" => true }, metadata: %{ "tags" => ["manufacturing", "industrial"], "contact_email" => "info@acme.com" } }) # Get all records for an entity records = PhoenixKitEntities.EntityData.list_by_entity(brand_entity.uuid) # Search by title results = PhoenixKitEntities.EntityData.search_by_title("Acme", brand_entity.uuid) # `t` ```elixir @type t() :: %PhoenixKitEntities.EntityData{ __meta__: term(), children: term(), created_by_uuid: term(), creator: term(), data: term(), date_created: term(), date_updated: term(), entity: term(), entity_uuid: term(), metadata: term(), parent: term(), parent_uuid: term(), position: term(), slug: term(), status: term(), title: term(), uuid: term() } ``` # `bulk_delete` ```elixir @spec bulk_delete( [String.t()], keyword() ) :: {non_neg_integer(), nil} | {:error, :referenced_by_external | :has_children} ``` Bulk hard-deletes records by UUIDs. Prefer `bulk_trash/2` for soft-delete. Use this for emptying-the-trash flows where the records are confirmed unreferenced. Catches `Postgrex.Error` for FK / NOT NULL violations and returns `{:error, :referenced_by_external}` so the admin UI can flash a friendly message rather than 500. The transaction rolls back on this error β no records are deleted. ## Options * `:actor_uuid` β UUID of the user performing the bulk delete. ## Examples iex> PhoenixKitEntities.EntityData.bulk_delete(["uuid1", "uuid2"], actor_uuid: admin.uuid) {2, nil} iex> PhoenixKitEntities.EntityData.bulk_delete([referenced_uuid]) {:error, :referenced_by_external} # `bulk_restore_from_trash` ```elixir @spec bulk_restore_from_trash( [String.t()], keyword() ) :: {non_neg_integer(), nil} ``` Bulk restores trashed records to `"published"` status. Only rows currently `"trashed"` are touched. Logs `entity_data.bulk_restored` with the affected count. ## Examples iex> EntityData.bulk_restore_from_trash(["uuid1", "uuid2"], actor_uuid: admin.uuid) {2, nil} # `bulk_trash` ```elixir @spec bulk_trash( [String.t()], keyword() ) :: {non_neg_integer(), nil} ``` Bulk soft-deletes records by setting their status to `"trashed"`. Returns `{count, nil}` for the number of records actually trashed (already-trashed records are skipped via the WHERE clause). Logs a single `entity_data.bulk_trashed` row. ## Examples iex> EntityData.bulk_trash(["uuid1", "uuid2"], actor_uuid: admin.uuid) {2, nil} # `bulk_update_positions` ```elixir @spec bulk_update_positions( [{binary(), integer()}], keyword() ) :: :ok | {:error, :too_many_uuids | term()} ``` Bulk updates positions for multiple records. Accepts a list of `{uuid, position}` tuples. Each record is updated individually to trigger events and maintain consistency. ## Options * `:entity_uuid` β when provided, the WHERE clause also filters on `entity_uuid`, so a stray UUID from another entity in the input list cannot have its position rewritten by the wrong scope. The LV reorder paths always pass this; programmatic callers should too unless they really intend cross-entity rewrites. Returns `{:error, :too_many_uuids}` if more than `1000` pairs are supplied β the cap protects the transaction from N+1 unbounded `update_all` work and from a malformed LV payload turning into a long-running write storm. ## Examples iex> bulk_update_positions([{"uuid1", 1}, {"uuid2", 2}, {"uuid3", 3}], entity_uuid: e_uuid) :ok # `bulk_update_status` ```elixir @spec bulk_update_status([String.t()], String.t(), keyword()) :: {non_neg_integer(), nil} ``` Bulk updates the status of multiple records by UUIDs. Returns a tuple with the count of updated records and nil. Logs a single `entity_data.bulk_status_changed` activity row carrying the count + new status. Per-record `entity_data.updated` rows are NOT emitted β bulk operations log at the operation level so the audit trail doesn't explode. ## Options * `:actor_uuid` β UUID of the user performing the bulk update. Threaded through to the activity log entry. ## Examples iex> PhoenixKitEntities.EntityData.bulk_update_status(["uuid1", "uuid2"], "archived", ...> actor_uuid: admin.uuid) {2, nil} # `change` ```elixir @spec change(t(), map()) :: Ecto.Changeset.t() ``` Returns an `%Ecto.Changeset{}` for tracking entity data changes. ## Examples iex> PhoenixKitEntities.EntityData.change(record) %Ecto.Changeset{data: %PhoenixKitEntities.EntityData{}} # `changeset` ```elixir @spec changeset(t() | Ecto.Changeset.t(), map()) :: Ecto.Changeset.t() ``` Creates a changeset for entity data creation and updates. Validates that entity exists, title is present, and data validates against entity definition. Automatically sets date_created on new records. # `count_by_entity` ```elixir @spec count_by_entity( binary(), keyword() ) :: non_neg_integer() ``` Counts records for an entity. Excludes trashed records by default. Pass `include_trashed: true` to count everything. ## Examples iex> PhoenixKitEntities.EntityData.count_by_entity(entity_uuid) 42 iex> PhoenixKitEntities.EntityData.count_by_entity(entity_uuid, include_trashed: true) 45 # `count_external_references` ```elixir @spec count_external_references(t(), map() | nil) :: non_neg_integer() ``` Counts external (parent-app) rows that reference this record. Reads `:reverse_references` from `Application.get_env/2` β a list of `{entity_name, count_fn}` tuples where `count_fn` is a 1-arity function that takes the entity_data uuid and returns a non-negative integer. Returns the total count across all matching callbacks for the record's entity, or `0` if no callbacks are registered. **Informational only β NOT a delete-blocker.** Soft-delete keeps the row alive regardless of how many parent rows reference it; this count is just for the admin UI to surface "Used by N rows" hints before the operator clicks Trash or Permanently delete. Don't wire it into the actual delete path. ## Performance β pass `entity` when the caller already has it The single-arg form preloads `:entity` on every call. Parent-app callers rendering many records in a loop can pass the already-loaded entity as the second arg to skip the per-call N+1: entity = Entities.get_entity!(entity_uuid) Enum.map(records, fn record -> EntityData.count_external_references(record, entity) end) ## Configuration # In parent app config: config :phoenix_kit_entities, reverse_references: [ {"order_status", &MyApp.Orders.count_orders_with_status/1}, {"sub_order_status", &MyApp.Orders.count_sub_orders_with_status/1} ] Multiple callbacks per entity name are supported β every matching tuple's count contributes to the total. Useful when the same entity_data acts as a controlled vocabulary for several parent tables (e.g. `orders` and `audit_log` both referencing `order_status`). # `create` ```elixir @spec create( map(), keyword() ) :: {:ok, t()} | {:error, Ecto.Changeset.t()} ``` Creates an entity data record. ## Examples iex> PhoenixKitEntities.EntityData.create(%{entity_uuid: entity_uuid, title: "Test"}) {:ok, %PhoenixKitEntities.EntityData{}} iex> PhoenixKitEntities.EntityData.create(%{title: ""}) {: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`. # `delete` ```elixir @spec delete( t(), keyword() ) :: {:ok, t()} | {:error, Ecto.Changeset.t() | :referenced_by_external | :has_children} ``` Hard-deletes an entity data record. Prefer `trash/2` for soft-delete β it keeps the row alive so parent-app FK references stay valid. Use this only when the record is genuinely unreferenced (e.g. emptying the trash bin). Catches `Postgrex.Error` for FK / NOT NULL violations and returns `{:error, :referenced_by_external}` so the admin UI can render a friendly flash instead of a 500. The row stays in the DB on this error. ## Examples iex> PhoenixKitEntities.EntityData.delete(record) {:ok, %PhoenixKitEntities.EntityData{}} iex> # parent_app.orders has a NOT NULL FK to this row iex> PhoenixKitEntities.EntityData.delete(record) {:error, :referenced_by_external} # `delete_data` ```elixir @spec delete_data( t(), keyword() ) :: {:ok, t()} | {:error, Ecto.Changeset.t() | :referenced_by_external} ``` Alias for delete/1 for consistency with LiveView naming. # `descendant_uuids` ```elixir @spec descendant_uuids(binary() | nil, binary(), keyword()) :: [binary()] ``` Returns all descendant UUIDs of a record (children, grandchildren, β¦). Used by the parent picker to exclude rows that would create a cycle. Walks the in-memory tree of the same entity rather than recursing through the DB. Trashed rows are excluded by default β they cannot meaningfully participate in a new cycle and including them would leak trashed rows into the picker's exclusion set. Returns `[]` for unknown / NULL `uuid`. ## Options * `:include_trashed` β when `true`, include trashed descendants # `descendant_uuids_from_rows` ```elixir @spec descendant_uuids_from_rows(binary() | nil, [t()]) :: [binary()] ``` Same as `descendant_uuids/3` but operates on an already-loaded row list. Pair with `tree_from_rows/1` when both shapes are needed from one fetch. # `filter_by_status` ```elixir @spec filter_by_status( String.t(), keyword() ) :: [t()] ``` Gets records filtered by status across all entities. When `status` is `"trashed"`, returns trashed records. For all other statuses, the query is implicitly scoped (status filter excludes trashed by virtue of matching a different status). ## Examples iex> PhoenixKitEntities.EntityData.filter_by_status("draft") [%PhoenixKitEntities.EntityData{status: "draft"}, ...] # `get` ```elixir @spec get( any(), keyword() ) :: t() | nil ``` Gets a single entity data record by UUID. Returns the record if found, nil otherwise. ## Examples iex> PhoenixKitEntities.EntityData.get("550e8400-e29b-41d4-a716-446655440000") %PhoenixKitEntities.EntityData{} iex> PhoenixKitEntities.EntityData.get("invalid") nil # `get!` ```elixir @spec get!( binary(), keyword() ) :: t() ``` Gets a single entity data record by UUID. Raises `Ecto.NoResultsError` if the record does not exist. ## Examples iex> PhoenixKitEntities.EntityData.get!("550e8400-e29b-41d4-a716-446655440000") %PhoenixKitEntities.EntityData{} iex> PhoenixKitEntities.EntityData.get!("nonexistent-uuid") ** (Ecto.NoResultsError) # `get_all_title_translations` ```elixir @spec get_all_title_translations(t()) :: %{optional(String.t()) => String.t() | nil} ``` Gets all title translations for a record. Returns a map of language codes to title strings. ## Examples iex> get_all_title_translations(record) %{"en-US" => "My Product", "es-ES" => "Mi Producto", "fr-FR" => "Mon Produit"} # `get_all_translations` ```elixir @spec get_all_translations(t()) :: %{optional(String.t()) => map()} ``` Gets translations for all languages in a record. Returns a map of language codes to their merged data. For flat records, returns the data under the primary language key. ## Examples iex> get_all_translations(record) %{ "en-US" => %{"name" => "Acme", "category" => "Tech"}, "es-ES" => %{"name" => "Acme EspaΓ±a", "category" => "Tech"} } # `get_by_slug` ```elixir @spec get_by_slug(binary(), String.t(), keyword()) :: t() | nil ``` Gets a single entity data record by entity and slug. Returns the record if found, nil otherwise. ## Examples iex> PhoenixKitEntities.EntityData.get_by_slug(entity_uuid, "acme-corporation") %PhoenixKitEntities.EntityData{} iex> PhoenixKitEntities.EntityData.get_by_slug(entity_uuid, "invalid") nil # `get_data!` ```elixir @spec get_data!( binary(), keyword() ) :: t() ``` Alias for get!/2 for consistency with LiveView naming. # `get_data_stats` ```elixir @spec get_data_stats(binary() | nil) :: %{ total_records: non_neg_integer(), published_records: non_neg_integer(), draft_records: non_neg_integer(), archived_records: non_neg_integer(), trashed_records: non_neg_integer() } ``` Gets statistical data about entity data records. `total_records` is the count of *non-trashed* records (the visible total). `trashed_records` is reported separately so the admin can surface the trash-bin badge. ## Examples iex> PhoenixKitEntities.EntityData.get_data_stats() %{ total_records: 150, published_records: 120, draft_records: 25, archived_records: 5, trashed_records: 3 } # `get_raw_translation` ```elixir @spec get_raw_translation(t(), String.t()) :: map() ``` Gets the raw (non-merged) data for a specific language. For secondary languages, returns only the override fields (not merged with primary). Useful for seeing which fields have explicit translations. ## Examples iex> get_raw_translation(record, "es-ES") %{"name" => "Acme EspaΓ±a"} # `get_title_translation` ```elixir @spec get_title_translation(t(), String.t()) :: String.t() | nil ``` Gets the title translation for a specific language. Reads from `data[lang]["_title"]` (unified JSONB storage). Falls back to the old `metadata["translations"]` location for unmigrated records, and finally to the `title` column. ## Examples iex> get_title_translation(record, "en-US") "My Product" iex> get_title_translation(record, "es-ES") "Mi Producto" # `get_translation` ```elixir @spec get_translation(t(), String.t()) :: map() ``` Gets the data fields for a specific language, merged with primary language defaults. For multilang records, returns `Map.merge(primary_data, language_overrides)`. For flat (non-multilang) records, returns the data as-is. ## Examples iex> get_translation(record, "es-ES") %{"name" => "Acme EspaΓ±a", "category" => "Tech"} iex> get_translation(flat_record, "en-US") %{"name" => "Acme", "category" => "Tech"} # `list_all` ```elixir @spec list_all(keyword()) :: [t()] ``` Returns all entity data records ordered by creation date. Trashed records are excluded by default. Pass `include_trashed: true` to return them too β used by admin trash views and reverse-reference checks. ## Examples iex> PhoenixKitEntities.EntityData.list_all() [%PhoenixKitEntities.EntityData{}, ...] # `list_all_data` ```elixir @spec list_all_data(keyword()) :: [t()] ``` Alias for list_all/1 for consistency with LiveView naming. # `list_by_entity` ```elixir @spec list_by_entity( binary(), keyword() ) :: [t()] ``` Returns all entity data records for a specific entity. Trashed records are excluded by default. Pass `include_trashed: true` to return them too. ## Examples iex> PhoenixKitEntities.EntityData.list_by_entity(entity_uuid) [%PhoenixKitEntities.EntityData{}, ...] # `list_by_entity_and_status` ```elixir @spec list_by_entity_and_status(binary(), String.t(), keyword()) :: [t()] ``` Returns entity data records filtered by entity and status. ## Examples iex> PhoenixKitEntities.EntityData.list_by_entity_and_status(entity_uuid, "published") [%PhoenixKitEntities.EntityData{status: "published"}, ...] # `list_data_by_entity` ```elixir @spec list_data_by_entity( binary(), keyword() ) :: [t()] ``` Alias for list_by_entity/2 for consistency with LiveView naming. # `list_data_by_status` ```elixir @spec list_data_by_status( String.t(), keyword() ) :: [t()] ``` Alias for filter_by_status/2 for consistency with LiveView naming. # `list_trashed_by_entity` ```elixir @spec list_trashed_by_entity( binary(), keyword() ) :: [t()] ``` Returns trashed records for a specific entity, ordered by most recently updated (the default trash-bin view). ## Examples iex> PhoenixKitEntities.EntityData.list_trashed_by_entity(entity_uuid) [%PhoenixKitEntities.EntityData{status: "trashed"}, ...] # `list_tree` ```elixir @spec list_tree( binary(), keyword() ) :: [%{record: t(), depth: non_neg_integer()}] ``` Returns the entity's records as a depth-ordered flat list for WordPress-style indented rendering β parents precede their children, siblings preserve the entity's current sort order. Each element is `%{record: %EntityData{}, depth: integer}` where depth `0` is a root row. ## Options * `:include_trashed` β when `true`, include trashed rows (default `false`) * `:lang` β resolve multilingual fields to the given locale. Display-only β see the warning on `resolve_language/2` before writing a resolved record back * any other opt accepted by `list_by_entity/2` # `move_to_position` ```elixir @spec move_to_position(t(), integer()) :: :ok | {:error, term()} ``` Moves a record to a specific position within its entity, shifting other records. Records between the old and new positions are shifted up or down by 1 to make room. This is the operation that a drag-and-drop UI would call. ## Examples iex> move_to_position(record, 3) :ok # `next_position` ```elixir @spec next_position(binary()) :: non_neg_integer() ``` Gets the next available position for an entity's data records. ## Examples iex> next_position(entity_uuid) 6 # `public_alternates` ```elixir @spec public_alternates(map(), map(), keyword()) :: %{ canonical: String.t(), alternates: [%{locale: String.t(), href: String.t()}] } ``` Returns hreflang alternates and a canonical URL for a record across all enabled languages. When the same record serves at both the unprefixed primary-language URL (`/products/my-item`) and a per-locale prefixed URL (`/es/products/mi-item`), search engines can index both as duplicate content. Use this helper to emit `` and `` tags alongside `public_path/3` so the duplication is declared rather than competing. ## Output shape %{ canonical: "https://site.com/en/products/my-item", alternates: [ %{locale: "en", href: "https://site.com/en/products/my-item"}, %{locale: "es", href: "https://site.com/es/products/mi-item"}, %{locale: "x-default", href: "https://site.com/en/products/my-item"} ] } The primary-language `canonical`/`href` shape follows the site-wide `default_language_no_prefix` setting (prefixed by default, as shown above; unprefixed β `/products/my-item` β when the setting is ON). Locales are emitted as base codes (`"en"`, `"es"`) β matching the locale prefix policy used in `public_path/3` and Google's hreflang docs (which recommend `xx` over `xx-XX` unless region targeting is required). ## Options * `:base_url` β explicit absolute URL prefix (e.g. `"https://shop.example.com"`). Falls back to the `site_url` setting, then `""` (which yields path-only `href` values β useful in tests but not in production HTML). * `:routes_cache` β pre-built cache from `UrlResolver.build_routes_cache/0` (avoid rebuilding per call when emitting many records). * `:primary_locale` β overrides the locale considered "canonical". Defaults to `Multilang.primary_language/0` with rescue fallback to the first enabled locale. When the Multilang module is unavailable or only one language is enabled, the result has a single canonical entry and no `:alternates`. # `public_path` ```elixir @spec public_path(map(), map(), keyword()) :: String.t() ``` Returns a public path for a record, respecting locale and the configured URL pattern. URL pattern resolution chain (shared with `PhoenixKitEntities.SitemapSource`): 1. `entity.settings["sitemap_url_pattern"]` 2. Router introspection (via `PhoenixKit.Modules.Sitemap.RouteResolver`) 3. Per-entity setting `sitemap_entity_