ExAdmin v0.8.2 ExAdmin.Register

Allows registering a resource or a page to be displayed with ExAdmin.

For each model you wanted rendered by ExAdmin, use the register_resource call. For each general page (like a dashboard), use the register_page call.

To allow ExAdmin to manage the resource with defaults, do not place any additional code in the block of register_resource.

Examples

Register the Survey.Answer model with all defaults.

defmodule Survey.ExAdmin.Answer do
  use ExAdmin.Register

  register_resource Survey.Answer do
  end
end

Commands available in the register_resource do block

  • menu - Customize the properties of the menu item
  • index - Customize the index page
  • show - Customize the show page
  • form - Customize the form page
  • query - Customize the Ecto queries for each page
  • options - Change various options for a resource
  • member_action - Add a custom action for id based requests
  • filter - Disable/Customize the filter pages
  • controller - Override the default controller
  • action_items - Define which actions are available for a resource
  • batch_actions - Customize the batch_actions shown on the index page
  • csv - Customize the csv export file
  • collection_action - Add a custom action for collection based requests
  • clear_action_items! - Remove the action item buttons
  • action_item - Defines custom action items
  • changesets - Defines custom changeset functions

Summary

Macros

Add a custom action button to the page

Define which actions will be displayed. Action labels could be overriden with labels option

Add an after filter to a controller

Disable the batch_actions button the index page

Add a before_filter to a controller

Override the changeset function for update and create actions. By default, changeset/2 for the resource will be used

Clear the default [:edit, :show, :new, :delete] action items

Add a action that acts on a collection and adds a link to the index page

Add a column to a table

Override the controller for a resource

Override an action on a controller

Customize the filter pages on the right side of the index page

Add an id based action and show page link

Customize the menu of a page

Customize the resource admin page by setting options for the page

Add a plug to the controller

Add query options to the Ecto queries

Redirect to a given path

Register a static page

Register an Ecto model

Add a row to the attributes table on the show page

Scope the index page

Add a sidebar to the page

Drag&drop control for sortable tables

Functions

custom_action_actions(actions, custom_actions, module, type)

Macros

action_item(opts, fun)

Add a custom action button to the page.

Examples

The following example demonstrates how to add a custom button to your index page, with no other action buttons due to the clear_action_items! call.

clear_action_items!

action_item :index, fn ->
  action_item_link "Something Special", href: "/my/custom/route"
end

An example of adding a link to the show page

action_item :show, fn id ->
  action_item_link "Show Link", href: "/custom/link", "data-method": :put, id: id
end
action_items(opts \\ nil)

Define which actions will be displayed. Action labels could be overriden with labels option.

Examples

action_items except: [:new, :delete, :edit]
action_items only: [:new]
action_items labels: [delete: "Revoke"]

Notes:

  • this replaces the deprecated actions/2 macro
  • action_items macro will not remove any custom actions defined by the action_item macro.
after_filter(name, opts \\ [])

Add an after filter to a controller.

The after filter is executed after the controller action(s) are executed and before the page is rendered/redirected. In the case of update and create, it is only called on success.

Normally, the function should return the conn struct. However, you can also return a {conn, params, resource} to modify the params and resource.

Examples

controller do
  after_filter :do_after, only: [:create, :update]

  def do_after(conn, params, resource, :create) do
    user = Repo.all(User) |> hd
    resource = Product.changeset(resource, %{user_id: user.id})
    |> Repo.update!
    {Plug.Conn.assign(conn, :product, resource), params, resource}
  end
  def do_after(conn, _params, _resource, :update) do
    Plug.Conn.assign(conn, :answer, 42)
  end
end
batch_actions(bool)

Disable the batch_actions button the index page.

Examples

batch_actions false
before_filter(name, opts \\ [])

Add a before_filter to a controller.

The before filter is executed before the controller action(s) are executed.

Normally, the function should return the conn struct. However, if you want to modify the params, then return the tuple {conn, new_parms}.

Examples

The following example illustrates how to add a sync action that will be run before the index page is loaded.

controller do
  before_filter :sync, only: [:index]

  def sync(conn, _) do
    BackupRestore.sync
    conn
  end
end

controller do
  before_filter :no_change, except: [:create, :modify]

  def no_change(conn, params) do
    {conn, put_in(params, [:setting, :no_mod], true)}
  end
end
changesets(opts)

Override the changeset function for update and create actions. By default, changeset/2 for the resource will be used.

Examples

The following example illustrates how to add a sync action that will be run before the index page is loaded.

changeset create: &__MODULE__.create_changeset/2,
          update: &__MODULE__.update_changeset/2

def create_changeset(model, params) do
  Ecto.Changeset.cast(model, params, ~w(name password), ~w(age))
end

def update_changeset(model, params) do
  Ecto.Changeset.cast(model, params, ~w(name), ~w(age password))
end
clear_action_items!()

Clear the default [:edit, :show, :new, :delete] action items.

Can be used alone, or followed with action_item to add custom actions.

collection_action(name, fun, opts \\ [])

Add a action that acts on a collection and adds a link to the index page.

Examples

The following example shows how to add a backup action on the index page.

collection_action :backup, &__MODULE__.backup_action/2, label: "Backup Database!"

def backup_action(conn, _params) do
  Repo.insert %BackupRestore{}
  Controller.put_flash(conn, :notice, "Backup complete.")
  |> Controller.redirect(to: ExAdmin.Utils.admin_resource_path(conn, :index))
end

The above example adds the following:

  • a custom backup action to the controller, accessible by the route /admin/:resource/collection/backup
  • a “Backup Database!” action link to the show page

Options

  • an optional label: “Button Label” (shown above)
column(name, opts \\ [], fun \\ nil)

Add a column to a table.

Can be used on the index page, or in the table attributes on the show page.

A number of options are valid:

  • label - Change the name of the column heading
  • fields - Add the fields to be included in an association
  • link - Set to true to add a link to an association
  • fn/1 - An anonymous function to be called to render the field
  • collection - Add the collection for a belongs_to association
controller(controller_mod)

Override the controller for a resource.

Allows custom actions, filters, and plugs for the controller. Commands in the controller block include:

  • define_method - Create a controller action with the body of the action
  • before_filter - Add a before_filter to the controller
  • after_filter - Add an after callback to the controller
  • redirect_to - Redirects to another page
  • plug - Add a plug to the controller
define_method(name, list)

Override an action on a controller.

Allows the customization of controller actions.

Examples

Override the index action to redirect to the root page.

controller do
  define_method(:index) do
    redirect_to "/"
  end
end
filter(disable)

Customize the filter pages on the right side of the index page.

Examples

Disable the filter view:

filter false

Only show index columns and filters for the specified fields:

filter [:name, :email, :inserted_at]
filter [:name, :email, :inserted_at, labels: [email: "EMail Address"]]
filter only: [:name, :email, :inserted_at], label: [email: "EMail Address"]
filter except: [:encrypted_password], labels: [name: "Full Name"]

Note: Restricting fields with the filter macro also removes the field columns

  from the default index table.
filter(field, opts \\ quote() do [] end)
member_action(name, fun, opts \\ [])

Add an id based action and show page link.

Member actions are those actions that act on an individual record in the database.

Examples

The following example illustrates how to add a restore action to a backup and restore page.

member_action :restore,  &__MODULE__.restore_action/2

...

def restore_action(conn, params) do
  case BackupRestore.restore Repo.get(BackupRestore, params[:id]) do
    {:ok, filename} ->
      Controller.put_flash(conn, :notice, "Restore #{filename} complete.")
    {:error, message} ->
      Controller.put_flash(conn, :error, "Restore Failed: #{message}.")
  end
  |> Controller.redirect(to: ExAdmin.Utils.admin_resource_path(conn, :index))
end

The above example adds the following:

  • a custom restore action to the controller, accessible by the route /admin/:resource/:id/member/restore
  • a “Restore” action link to the show page

Options

  • an optional label: “Button Label”
options(opts)

Customize the resource admin page by setting options for the page.

The available actions are:

  • TBD
plug(name, opts \\ [])

Add a plug to the controller.

Add custom plugs to a controller.

Example

controller do
  plug :my_plug, the_answer: 42
end
query(list)

Add query options to the Ecto queries.

For the most part, use query to setup preload options. Query customization can be done for all pages, or individually specified.

Examples

Load the belongs_to :category, has_many :phone_numbers, and the has_many :groups for all pages for the resource.

query do
  %{
    all: [preload: [:category, :phone_numbers, :groups]],
  }
end

Load the has_many :contacts association, as well as the has_many :phone_numbers of the contact

query do
  %{show: [preload: [contacts: [:phone_numbers]]] }
end

A more complicated example that defines a default preload, with a more specific preload for the show page.

query do
  %{
    all: [preload: [:group]],
    show: [preload: [:group, messages: [receiver: [:category, :phone_numbers]]]]
  }
end

Change the index page default sort order to ascending.

query do
  %{index: [default_sort_order: :asc]}
end

Change the index page default sort field and order.

query do
  %{index: [default_sort: [asc: :name]]}
end

Change the index page default sort field.

query do
  %{index: [default_sort_field: :name]}
end
redirect_to(path)

Redirect to a given path.

Use this command in a controller block to redirect to another page.

register_page(name, list)

Register a static page.

Use register_page to create a static page, like a dashboard, or welcome page to the admin interface.

See the default dashboard page for an example.

register_resource(mod, list)

Register an Ecto model.

Once registered, ExAdmin adds the resource to the administration pages. If no additional code is added to the do block, the resource will be rendered with defaults, including:

  • A paginated index page listing all columns in the model’s database table
  • A details page (show) listing fields and simple associations
  • New and edit pages
  • A menu item
  • A CSV export link on the index page

Default Association Rendering

ExAdmin will render an association using the following algorithm in the following order:

  • Look for a :name field in the association
  • Look for a display_name/1 function in the Admin Resource Module
  • Look for a display_name/1 function in the Model’s Module
  • Use the 2nd field in the Model’s schema
row(name, opts \\ [], fun \\ nil)

Add a row to the attributes table on the show page.

See column/3 for a list of options.

scope(name)

Scope the index page.

Examples

  scope :all, default: true

  scope :available, fn(q) ->
    now = Ecto.Date.utc
    where(q, [p], p.available_on <= ^now)
  end

  scope :drafts, fn(q) ->
    now = Ecto.Date.utc
    where(q, [p], p.available_on > ^now)
  end

  scope :featured_products, [], fn(q) ->
    where(q, [p], p.featured == true)
  end

  scope :featured
scope(name, opts_or_fun)
scope(name, opts, fun)
sidebar(name, opts \\ [], list)

Add a sidebar to the page.

The available options are:

  • :only - Filters the list of actions for the filter.
  • :except - Filters out actions in the except atom or list.

Examples

sidebar "ExAdmin Demo", only: [:index, :show] do
  Phoenix.View.render ExAdminDemo.AdminView, "sidebar_links.html", []
end

sidebar :Orders, only: :show do
  attributes_table_for resource do
    row "title", fn(_) -> { resource.title } end
    row "author", fn(_) -> { resource.author } end
  end
end

# customize the panel

sidebar "Expert Administration", box_attributes: ".box.box-warning",
            header_attributes: ".box-header.with-border.text-yellow" do
  Phoenix.View.render MyApp.AdminView, "sidebar_warning.html", []
end
sort_handle_column(fa_icon_name \\ "bars")

Drag&drop control for sortable tables.

fa_icon_name is one of Font Awesome icons, default - ”bars”