Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@danielberkompas
danielberkompas committed Jul 15, 2016
1 parent cb87032 commit 77c738d
Show file tree
Hide file tree
Showing 19 changed files with 388 additions and 95 deletions.
2 changes: 2 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

[![Build Status](https://semaphoreci.com/api/v1/projects/b2c7b27b-ce6c-4b1c-b2a4-df3390f80380/870178/badge.svg)](https://semaphoreci.com/ir/torch)

![Screenshot](screenshot.png)

A rapid admin generator for Phoenix apps. See more details in the [README](/apps/torch/README.md).

## Development
Expand Down
2 changes: 1 addition & 1 deletion apps/example/lib/mix/tasks/regenerate.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ defmodule Mix.Tasks.Regenerate do
File.rm_rf!("web/templates/admin/")
File.rm_rf!("web/controllers/admin/")
File.rm_rf!("web/views/admin/")
Mix.Task.run "torch.gen", ~w(#{format} Admin Post posts title:string body:text draft:boolean inserted_at:date updated_at:date category_id:references:category,categories:id,name)
Mix.Task.run "torch.gen", ~w(#{format} Admin Post posts title:string body:text draft:boolean inserted_at:date updated_at:date category_id:references:category,categories:id,name author_id:references:author,authors:id,name)
Mix.Task.reenable("torch.gen")
Mix.Task.run "torch.gen", ~w(#{format} Admin Author authors name:string email:string inserted_at:date updated_at:date)
Mix.Task.reenable("torch.gen")
Expand Down
9 changes: 9 additions & 0 deletions apps/example/web/controllers/admin/post_controller.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ defmodule Example.Admin.PostController do
plug :put_layout, {Example.LayoutView, "admin.html"}
plug :scrub_params, "post" when action in [:create, :update]
plug :assign_categories
plug :assign_authors

@filtrex [
%Config{type: :boolean, keys: ~w(draft)},
Expand Down Expand Up @@ -95,4 +96,12 @@ defmodule Example.Admin.PostController do
|> Enum.map(&({&1.name, &1.id}))
assign(conn, :categories, categories)
end

defp assign_authors(conn, _opts) do
authors =
Example.Author
|> Repo.all
|> Enum.map(&({&1.name, &1.id}))
assign(conn, :authors, authors)
end
end
2 changes: 1 addition & 1 deletion apps/example/web/models/post.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ defmodule Example.Post do
"""
def changeset(struct, params \\ %{}) do
struct
|> cast(params, [:title, :body, :draft, :category_id])
|> cast(params, [:title, :body, :draft, :category_id, :author_id])
|> validate_required([:title, :body, :draft])
end
end
5 changes: 5 additions & 0 deletions apps/example/web/templates/admin/post/_filters.html.eex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@
<%= filter_assoc_select(:post, :category_id, @categories, @conn.params) %>
</div>

<div class="field">
<label>Author</label>
<%= filter_assoc_select(:post, :author_id, @authors, @conn.params) %>
</div>

<div class="field">
<label>Title</label>
<%= filter_select(:post, :title, @conn.params) %>
Expand Down
6 changes: 6 additions & 0 deletions apps/example/web/templates/admin/post/_form.html.eex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,12 @@
<%= error_tag f, :category_id %>
</div>

<div class="field">
<%= label f, :author %>
<%= select f, :author_id, @authors, prompt: "Choose one" %>
<%= error_tag f, :author_id %>
</div>

<div class="field">
<%= submit "Submit", class: "torch-button" %>
</div>
Expand Down
4 changes: 2 additions & 2 deletions apps/example/web/templates/admin/post/index.html.eex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@
<thead>
<tr>
<th><%= table_link(@conn, "Title", :title) %></th>
<th><%= table_link(@conn, "Body", :body) %></th>
<th><%= table_link(@conn, "Draft", :draft) %></th>
<th><%= table_link(@conn, "Category", :category_id) %></th>
<th><%= table_link(@conn, "Author", :author_id) %></th>

<th><span>Actions<span></th>
</tr>
Expand All @@ -23,9 +23,9 @@
<%= for post <- @posts do %>
<tr>
<td><%= post.title %></td>
<td><%= post.body %></td>
<td><%= post.draft %></td>
<td><%= table_assoc_display_name(post, :category_id, @categories) %>
<td><%= table_assoc_display_name(post, :author_id, @authors) %>

<td class="torch-actions">
<%= link "Edit", to: admin_post_path(@conn, :edit, post) %>
Expand Down
180 changes: 104 additions & 76 deletions apps/torch/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,46 +1,116 @@
# 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.
Torch is a rapid admin generator for Phoenix apps. It uses generators rather than DSLs to ensure that the code remains maintainable.

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed as:
To install Torch, perform the following steps:

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

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

2. Ensure `torch` is started before your application:
2. Ensure `:torch` is started in your applications list in `mix.exs`:

```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.

def application do
[applications: [:torch]]
end
```

3. Add `torch` to your `package.json` dependencies. Then, run `npm install`.

```diff
"dependencies": {
"phoenix": "file:deps/phoenix",
"phoenix_html": "file:deps/phoenix_html",
+ "torch": "file:deps/torch"
},
```

4. Import `torch.js` in your `app.js`:

```js
import "torch"
```

5. Run `mix torch.install (eex|slim)` to install the relevant Torch files. You can choose between `eex` templates and `slim` templates. If you choose to use `slim` templates, you will need to [install Phoenix Slim](https://github.com/slime-lang/phoenix_slime).

6. Set up CSS as described below.

## Setting up CSS

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`

### Customization Using Sass Variables

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:

```css
@import "admin_variables";
@import "../../../node_modules/torch/web/static/css/torch";
```

Then, update your `brunch-config.js` sass settings to make Brunch watch your node_modules directory:

```js
plugins: {
sass: {
mode: 'native',
includePaths: ['node_modules']
}
}
```

Then, simply uncomment and customize the variables in `web/static/css/_admin_variables.scss` to change how Torch is styled.

### Using Precompiled CSS

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:

1. Add `node_modules` to the watched directories for `stylesheets`.

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

2. Add `torch` to the npm configuration:

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

## 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:

Run `mix torch.gen (eex|slim)` to generate admin controllers and views for a given Ecto schema module. Torch expects you to have already defined the schema in your project.

For example, if we wanted to generate an admin area for a `Post` model we already have, we could run this command:

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

And the output would be:

```bash
Success!

You should now add a route to the new controller to your `router.ex`, within the `:admin` scope:
Expand All @@ -63,7 +133,7 @@ And update the `layout/admin.html.eex` navigation:
</header>
```

The generator created the following files for us:
The command created the following files for us:

```
web/templates/admin/post/index.html.eex
Expand All @@ -75,52 +145,10 @@ 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 hook up the routes as described above, you'll see a fully featured CRUD interface for posts, including sophisticated filtering, sorting and search at <http://localhost:4000/admin/posts>.

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.
To learn more about the `torch.gen` task, run:

## 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. You will also need to update your `brunch-config.js` SASS settings:

```json
plugins: {
sass: {
mode: 'native',
includePaths: ['node_modules']
}
}
```

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'
]
}
}
```
```
mix help torch.gen
```
Loading

0 comments on commit 77c738d

Please sign in to comment.