README.md

# Torch

Torch is a rapid admin generator for Phoenix apps, in the same vein as Rails ActiveAdmin or ExAdmin.
It uses generators rather than DSLs to ensure that the code remains maintainable over the long term.

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed as:

  1. Add `torch` to your list of dependencies in `mix.exs`:

    ```elixir
    def deps do
      [{:torch, "~> 0.2.0-rc.2"}]
    end
    ```

  2. Ensure `torch` is started before your application:

    ```elixir
    def application do
      [applications: [:torch]]
    end
    ```
    
  3. Add `torch` to your `package.json` dependencies. Then, run `npm install`.
  
    ```json
    "dependencies": {
      "phoenix": "file:../../deps/phoenix",
      "phoenix_html": "file:../../deps/phoenix_html",
      "torch": "file:../../deps/torch"
    },
    ```
  
  4. Run `mix torch.install` to install the relevant Torch files. Follow the instructions it gives after it completes.
  
## Usage
  
Run `mix torch.gen.html` to generate admin controllers and views for a given model. For example, if we wanted to generate an admin area for a `Post` model, we could run this command:

```bash
$ mix torch.gen.html Admin Post posts title:string body:text inserted_at:date
Success!

You should now add a route to the new controller to your `router.ex`, within the `:admin` scope:

    scope "/admin", Example, as: :admin do
      pipe_through :browser

      resources "/posts", PostController
    end

And update the `layout/admin.html.eex` navigation:

    <header id="main-header">
      <nav>
        <h1>Torch Admin</h1>
        <ul>
          <li><%= Torch.NavigationView.nav_link @conn, "Posts", admin_post_path(@conn, :index) %></a>
        </ul>
      </nav>
    </header>
```

The generator created the following files for us:

```
web/templates/admin/post/index.html.eex
web/templates/admin/post/edit.html.eex
web/templates/admin/post/new.html.eex
web/templates/admin/post/_form.html.eex
web/templates/admin/post/_filters.html.eex
web/controllers/admin/post_controller.ex
web/views/admin/post_view.ex
```

If you hook up the routes as described above, you'll see a fully featured CRUD interface for posts, including sophisticated filtering, sorting and search.

If you want to change anything, you can! The code is all generated within your project, so there are no DSLs to learn, and you rarely have to extend anything to get the job done.

## CSS Customization

Torch provides its CSS in two ways:

1. A precompiled css file in `priv/static/css/torch.css`.
2. SASS styles in `web/static/css/torch.sass`

If you want to customize the look and feel of your admin, you should use the SASS styles. Update your `app.scss` file to look like this:

    ```sass
    @import "admin_variables";
    @import "../../../node_modules/torch/web/static/css/torch";
    ```
    
The `_admin_variables.scss` file was automatically generated by `mix torch.install`. Now that it is loaded before the torch styles, you can change its variables to change how the Torch admin appears.

If you're not using SASS, then you will need to configure your asset pipeline to compile the precompiled `torch.css`. Brunch can be configured to do this like so:

    ```json
    stylesheets: {
      joinTo: {
        'css/app.css': /^(web|node_modules)/
      }
    }

    ...
    
    npm: {
      enabled: true
      styles: {
        torch: [
          'priv/static/torch.css'
        ]
      }
    }
    ```