AshAdmin

The admin DSL block is a resource extension used to alter how a specific Ash resource behaves and appears within the ash_admin interface. You can use it to control which actions are visible, how columns are displayed in datatables, and how fields are formatted.

Key configuration areas include:

• Action Visibility: Control which read_actions, create_actions, update_actions, destroy_actions, or generic_actions are available.
• Datatable Display: Specify table_columns, table_sortable_columns, and table_filterable_columns.
• Relationship Behavior: Use label_field to define the display label for relationship selects, and relationship_select_max_items to toggle between a select dropdown and a typeahead (default is 50).
• Formatting: Use format_fields to apply custom formatting (via MFA) to date/time fields in datatables and show/update pages.

If you modify the development resources within the dev folder, you must generate new migrations using the following command:

mix generate_migrations

To set up AshAdmin manually, import AshAdmin.Router into your Phoenix router.

Important Requirements:

1. AshAdmin requires a Phoenix LiveView :browser pipeline. If your application doesn't have one, use the admin_browser_pipeline macro to define one.
2. No Prefixes: Do not place the ash_admin route inside a scope that has a module prefix (e.g., scope "/", MyAppWeb). Instead, use an empty scope scope "/" do ... end to avoid UndefinedFunctionError issues.

defmodule MyAppWeb.Router do
  use Phoenix.Router

  import AshAdmin.Router

  # Define a browser pipeline if you don't have one
  admin_browser_pipeline :browser

  # Use an empty scope (no module prefix) for AshAdmin
  scope "/" do
    pipe_through [:browser]

    ash_admin "/admin"
  end
end

If you make changes to CSS or JavaScript files, or if you update dependencies that include assets (such as Phoenix LiveView), you must recompile the assets using:

mix assets.deploy

Add ash_admin to your mix.exs dependencies.

Alternatively, use Igniter for an automated installation process, which is the recommended method.

{:ash_admin, "~> 0.13.3"}

mix igniter.install ash_admin

AshAdmin includes a built-in development app located in the dev folder, allowing you to develop without an external Phoenix application.

To set up the environment, ensure you have PostgreSQL running locally, then execute the following commands in order:

1. Create the database: mix ash_postgres.create
2. Run migrations: mix migrate
3. Migrate tenants: mix migrate_tenants
4. Run the setup task: mix setup

Once setup is complete, start the application server using: mix dev

If your application uses a strict Content Security Policy (CSP), AshAdmin's inline CSS and JavaScript may be blocked.

To fix this, you can:

1. Add the default AshAdmin nonces to your default-src allowlist in your router.
2. Or, provide your own nonces by setting the :csp_nonce_assign_key option in the ash_admin route macro.

# Option 1: Using default nonces in router
plug :put_secure_browser_headers, %{"content-security-policy" => "default-src 'nonce-ash_admin-Ed55GFnX' 'self'"}

# Option 2: Providing a custom nonce key in the route
ash_admin "/admin", csp_nonce_assign_key: :csp_nonce_value

Use AshAdmin.Domain as a domain extension to customize how a specific Ash domain is represented and behaved within the Ash Admin UI. You can control visibility, resource filtering, and naming via the admin configuration block.

# Example usage within a domain definition
# Note: The exact syntax depends on your domain definition structure
defmodule MyDomain do
  use Ash.Domain

  admin do
    name "My Custom Domain"
    show? true
    show_resources [:user, :post]
  end
end

Use the admin.form.field DSL within the admin.form block to declare non-default behavior for specific attributes in the admin UI forms.

This is useful for changing the input type (e.g., using a markdown editor) or setting constraints on file uploads.

# Example usage pattern
admin do
  form do
    field :description do
      type :markdown
    end

    field :avatar do
      type :short_text
      max_file_size 1_000_000
      accepted_extensions ".jpg", ".png"
    end
  end
end

To make your Ash data visible in the dashboard, you must perform two steps:

1. Enable the Domain extension: Add AshAdmin.Domain to your Ash.Domain and set show? true in the admin block.
2. Identify the Actor (Optional): If your application uses an actor (e.g., a User resource) to drive policies, add the AshAdmin.Resource extension to that resource and set actor? true in its admin block.

# In your Domain(s)
use Ash.Domain,
  extensions: [AshAdmin.Domain]

admin do
  show? true
end

# In your resource that acts as an actor (e.g. User)
use Ash.Resource,
  domain: YourDomain,
  extensions: [AshAdmin.Resource]

admin do
  actor? true
end