View Source LiveAdmin

hex package CI status

An admin UI for Phoenix applications built on Phoenix LiveView and Ecto.

Significant features:

  • Minimal required configuration
  • First class support for multi tenant applications via Ecto's prefix option
  • Overridable views and API
  • Easily add custom actions at the schema and record level
  • Ability to edit (nested) embedded schemas
  • i18n via Gettext

required-installation

(Required) Installation

One of the main design goals of LiveAdmin is to require as little config as possible. It should be useable out of the box for most internal admin use cases using defaults. If you are already running LiveView in your application, it should only take a few minutes to expose a UI for your resources.

First, ensure your Phoenix app has been configured to use LiveView.

Add to your app's deps:

{:live_admin, "~> 0.11.3"}

Configure a module to act as a LiveAdmin resource:

defmodule MyApp.Admin.Foo do
  use LiveAdmin.Resource, schema: MyApp.Foo
end

Note: if your module is an Ecto schema you can omit the schema option.

In your Phoenix router, inside a scope configured to run LiveView (:browser if you followed the default installation), add the resource to a LiveAdmin instance:

import LiveAdmin.Router

...

scope "/" do
  pipe_through: :browser

  live_admin "/admin" do
    admin_resource "/foos", MyApp.Admin.Foo
  end
end

Finally, tell LiveAdmin what Ecto repo to use to run queries in your runtime.ex:

config :live_admin, ecto_repo: MyApp.Repo

That's it, now an admin UI for MyApp.Schema will be available at /my_admin/my_schemas.

optional-configuration

(Optional) Configuration

You may want more control over how your resources appear in the UI, or which fields are editable. If you want to customize the behavior of one or more resources, including how records are rendered or changes are validated, or to add custom behaviors, there are a variety of configuration options available. This includes component overrides if you would like to completely control every aspect of a particular resource view, like the edit form. For a complete list of options, see the LiveAdmin.Resource docs.

For additional convenience and control, configuration in LiveAdmin can be set at 3 different levels. From more specific to more general, they are:

resource

Resource

The second argument passed to use LiveAdmin.Resource will configure only that specific resource, in any LiveView it is used. If the module is not an Ecto schema, the :schema option must be passed. If you would like the same schema to behave differently in different LiveAdmin instances, or different routes in the same instance, you must create multiple resource modules to contain that configuration.

scope

Scope

The second argument passed to live_admin will configure defaults for all resources in the group that do not specify the same configuration. Currently only component overrides and the repo can be configured at this level.

application

Application

All resource configuration options can also be set in the LiveAdmin app runtime config. This will set a global default to apply to all resources unless overridden in their individual config, or the LiveAdmin instance.

Additionally, the following options can only be set at the global level:

  • css_overrides - a binary or MFA identifying a function that returns CSS to be appended to app css
  • session_store - a module implementing the LiveAdmin.Session.Store behavior, used to persist session data
  • gettext_backend - a module implementing the Gettext API that will be used for translations

For concrete examples of the various config options and to see them in action, consult the development app.

features

Features

multi-tenancy

Multi tenancy

To enable Multi tenant support, simply implement a prefixes/0 function in your Ecto Repo module that returns a list of prefixes. A dropdown will be added to the top nav bar that will allow you to switch between tenants.

i18n

i18n

LiveAdmin wraps all static strings in the UI with Gettext calls, but currently it does not provide any locales by default. To enable i18n, implement a locales/0 function returning a list of binary locale names on your Gettext Backend module.

Unfortunately it is not currently possible to use Gettext's utilities to automatically extract the pot files so you will need to do this manually. To avoid conflicts with your own app's translations, it is recommended to use a separate Gettext backend for LiveAdmin.

development-environment

Development environment

This repo has been configured to run the application in Docker using Compose.

The Phoenix app is running the app service, so all mix command should be run there. Examples:

  • docker compose run web mix test

README generated with docout