ExAdmin v0.7.4 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
  • actions - 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

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

Add a action that acts on 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

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

Macros

action_item(opts, fun)

Add a custom action button to the page.

Examples

The following example demonstrates adding a Backup Now link to the index page, with no other action buttons due to the clear_action_items! call.

clear_action_items!

action_item :index, fn ->
  ExAdmin.Register.link_to "Backup Now", "/admin/backuprestores/backup", "data-method": :post, id: "backup-now"
end
actions(atom, opts \\ quote() do [] end)

Define which actions will be displayed.

Examples

actions :all, except: [:new, :destroy, :edit]
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!()
collection_action(name, fun)

Add a action that acts on 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

def backup_action(conn, _params) do
  Repo.insert %BackupRestore{}
  Controller.put_flash(conn, :notice, "Backup complete.")
  |> Controller.redirect(to: ExAdmin.Utils.get_route_path(conn, :index))
end
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
  • 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 only: [:name, :email, :inserted_at]
filter except: [:encrypted_password]
filter(field, opts \\ quote() do [] end)
member_action(name, fun)

Add an id based action.

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.get_route_path(conn, :index))
end
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