# ExAdmin
[![Build Status][travis-img]][travis] [![Hex Version][hex-img]][hex] [![License][license-img]][license]
[travis-img]: https://travis-ci.org/smpallen99/ex_admin.svg?branch=master
[travis]: https://travis-ci.org/smpallen99/ex_admin
[hex-img]: https://img.shields.io/hexpm/v/ex_admin.svg
[hex]: https://hex.pm/packages/ex_admin
[license-img]: http://img.shields.io/badge/license-MIT-brightgreen.svg
[license]: http://opensource.org/licenses/MIT
Note: This version has been updated to support both Ecto 1.1 and Ecto 2.0. See [Installation](#installation) for more information.
ExAdmin is an auto administration package for [Elixir](http://elixir-lang.org/) and the [Phoenix Framework](http://www.phoenixframework.org/), a port/inspiration of [ActiveAdmin](http://activeadmin.info/) for Ruby on Rails.
Checkout the [Live Demo](http://demo.exadmin.info/admin). The source code can be found at [ExAdmin Demo](https://github.com/smpallen99/ex_admin_demo).
Checkout this [Additional Live Demo](http://demo2.exadmin.info/admin) for examples of many-to-many relationships, nested attributes, and authentication.
See the [docs](https://hexdocs.pm/ex_admin/) and the [Wiki](https://github.com/smpallen99/ex_admin/wiki) for more information.
## Usage
ExAdmin is an add on for an application using the [Phoenix Framework](http://www.phoenixframework.org) to create an CRUD administration tool with little or no code. By running a few mix tasks to define which Ecto Models you want to administer, you will have something that works with no additional code.
Before using ExAdmin, you will need a Phoenix project and an Ecto model created.
### Installation
Add ex_admin to your deps:
#### Hex
mix.exs
```elixir
defp deps do
...
{:ex_admin, "~> 0.8"},
...
end
```
#### GitHub with Ecto 2.0
mix.exs
```elixir
defp deps do
...
{:ex_admin, github: "smpallen99/ex_admin"},
...
end
```
#### GitHub with Ecto 1.1
mix.exs
```elixir
defp deps do
...
{:ex_admin, github: "smpallen99/ex_admin"},
{:phoenix_ecto, "~> 2.0.0", override: true}, # the override is necessary
{:ecto, "~> 1.1", override: true}, # the override is necessary
...
end
```
Add some admin configuration and the admin modules to the config file
config/config.exs
```elixir
config :ex_admin,
repo: MyProject.Repo,
module: MyProject,
modules: [
MyProject.ExAdmin.Dashboard,
]
```
Fetch and compile the dependency
```
mix do deps.get, deps.compile
```
Configure ExAdmin:
```
mix admin.install
```
Add the admin routes
web/router.ex
```elixir
defmodule MyProject.Router do
use MyProject.Web, :router
use ExAdmin.Router
...
scope "/", MyProject do
...
end
# setup the ExAdmin routes on /admin
scope "/admin", ExAdmin do
pipe_through :browser
admin_routes()
end
```
Add the paging configuration
lib/my_project/repo.ex
```elixir
defmodule MyProject.Repo do
use Ecto.Repo, otp_app: :my_project
use Scrivener, page_size: 10
end
```
Edit your brunch-config.js file and follow the instructions that the installer appended to this file. This requires you copy 2 blocks and replace the existing blocks.
Start the application with `iex -S mix phoenix.server`
Visit http://localhost:4000/admin
You should see the default Dashboard page.
## Getting Started
### Adding an Ecto Model to ExAdmin
To add a model, use `admin.gen.resource` mix task:
```
mix admin.gen.resource MyModel
```
Add the new module to the config file:
config/config.exs
```elixir
config :ex_admin,
repo: MyProject.Repo,
module: MyProject,
modules: [
MyProject.ExAdmin.Dashboard,
MyProject.ExAdmin.MyModel,
]
```
Start the phoenix server again and browse to `http://localhost:4000/admin/my_model`
You can now list/add/edit/and delete `MyModel`s.
### Customizing the index page
Use the `index do` command to define the fields to be displayed.
admin/my_model.ex
```elixir
defmodule MyProject.ExAdmin.MyModel do
use ExAdmin.Register
register_resource MyProject.MyModel do
index do
selectable_column()
column :id
column :name
actions() # display the default actions column
end
end
end
```
### Customizing the form
The following example shows how to customize the form with the `form` macro:
```elixir
defmodule MyProject.ExAdmin.Contact do
use ExAdmin.Register
register_resource MyProject.Contact do
form contact do
inputs do
input contact, :first_name
input contact, :last_name
input contact, :email
input contact, :category, collection: MyProject.Category.all
end
inputs "Groups" do
inputs :groups, as: :check_boxes, collection: MyProject.Group.all
end
end
end
end
```
### Customizing the show page
The following example illustrates how to modify the show page.
```elixir
defmodule MyProject.ExAdmin.Question do
use ExAdmin.Register
register_resource MyProject.Question do
menu priority: 3
show question do
attributes_table # display the defaults attributes
# create a panel to list the question's choices
panel "Choices" do
table_for(question.choices) do
column :key
column :name
end
end
end
end
end
```
## Custom Types
Support for custom field types is done in two areas, rendering fields, and input controls.
### Rendering Custom Types
Use the `ExAdmin.Render.to_string/` protocol for rendering types that are not supported by ExAdmin.
For example, to support rendering a tuple, add the following file to your project:
```elixir
# lib/render.ex
defimpl ExAdmin.Render, for: Tuple
def to_string(tuple), do: inspect(tuple)
end
```
### Input Type
Use the `:field_type_matching` config item to set the input type.
For example, given the following project:
```elixir
defmodule ElixirLangMoscow.SpeakerSlug do
use EctoAutoslugField.Slug, from: [:name, :company], to: :slug
end
defmodule ElixirLangMoscow.Speaker do
use ElixirLangMoscow.Web, :model
use Arc.Ecto.Model
alias ElixirLangMoscow.SpeakerSlug
schema "speakers" do
field :slug, SpeakerSlug.Type
field :avatar, ElixirLangMoscow.Avatar.Type
end
end
```
Add the following to your project's configuration:
```elixir
config :ex_admin,
# ...
field_type_matching: %{
ElixirLangMoscow.SpeakerSlug.Type => :string,
ElixirLangMoscow.Avatar.Type => :file
}
```
## Theme Support
ExAdmin supports 2 themes. The new AdminLte2 theme is enabled by default. The old ActiveAdmin theme is also supported for those that want backward compatibility.
### Changing the Theme
To change the theme to ActiveAdmin, at the following to your `config/config.exs` file:
config/config.exs
```elixir
config :ex_admin,
theme: ExAdmin.Theme.ActiveAdmin,
...
```
### Changing the AdminLte2 Skin Color
The AdminLte2 theme has a number of different skin colors including blue, black, purple, green, red, yellow, blue-light, black-light, purple-light, green-light, red-light, and yellow-light
To change the skin color to, for example, purple:
config/config.exs
```elixir
config :ex_admin,
skin_color: :purple,
...
```
### Enable Theme Selector
You can add a theme selector on the top right of the menu bar by adding the following to your `config/config.exs` file:
config/config.exs
```elixir
config :ex_admin,
theme_selector: [
{"AdminLte", ExAdmin.Theme.AdminLte2},
{"ActiveAdmin", ExAdmin.Theme.ActiveAdmin}
],
...
```
## Authentication
ExAdmin leaves the job of authentication to 3rd party packages. For an example of using [Coherence](https://github.com/smpallen99/coherence) checkout the [Contact Demo Project](https://github.com/smpallen99/contact_demo).
Visit the [Wiki](https://github.com/smpallen99/ex_admin/wiki/Add-authentication) for more information on adding Authentication.
## Contributing
We appreciate any contribution to ExAdmin. Check our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and [CONTRIBUTING.md](CONTRIBUTING.md) guides for more information. We usually keep a list of features and bugs [in the issue tracker][1].
## References
* Detailed Example [ExAdmin Demo](https://github.com/smpallen99/ex_admin_demo)
* For a brief tutorial, please visit [Elixir Survey Tutorial](https://github.com/smpallen99/elixir_survey_tutorial)
* [Live Demo](http://demo.exadmin.info/admin)
* [Docs](https://hexdocs.pm/ex_admin/)
[1]: https://github.com/smpallen99/ex_admin/issues
[2]: http://groups.google.com/group/exadmin-talk
## License
`ex_admin` is Copyright (c) 2015-2016 E-MetroTel
The source code is released under the MIT License.
Check [LICENSE](LICENSE) for more information.
