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 itemindex
- Customize the index pageshow
- Customize the show pageform
- Customize the form pagequery
- Customize theEcto
queries for each pageoptions
- Change various options for a resourcemember_action
- Add a custom action for id based requestsfilter
- Disable/Customize the filter pagescontroller
- Override the default controlleraction_items
- Define which actions are available for a resourcebatch_actions
- Customize the batch_actions shown on the index pagecsv
- Customize the csv export filecollection_action
- Add a custom action for collection based requestsclear_action_items!
- Remove the action item buttonsaction_item
- Defines custom action itemschangesets
- 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 a link to a path
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
Macros
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
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 theaction_item
macro.
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
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
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 the default [:edit, :show, :new, :delete] action items.
Can be used alone, or followed with action_item
to add custom actions.
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)
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 headingfields
- Add the fields to be included in an associationlink
- Set to true to add a link to an associationfn/1
- An anonymous function to be called to render the fieldcollection
- Add the collection for a belongs_to association
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 actionbefore_filter
- Add a before_filter to the controllerafter_filter
- Add an after callback to the controllerredirect_to
- Redirects to another pageplug
- Add a plug to the controller
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
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.
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”
Customize the resource admin page by setting options for the page.
The available actions are:
- TBD
Add a plug to the controller.
Add custom plugs to a controller.
Example
controller do
plug :my_plug, the_answer: 42
end
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 a given path.
Use this command in a controller block to redirect to another page.
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 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
Add a row to the attributes table on the show page.
See column/3
for a list of options.
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
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
Drag&drop control for sortable tables.
fa_icon_name
is one of Font Awesome icons,
default - ”bars”