Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/edisonywh/backoffice
Admin tool built with the PETAL stack
https://github.com/edisonywh/backoffice
Last synced: 6 days ago
JSON representation
Admin tool built with the PETAL stack
- Host: GitHub
- URL: https://github.com/edisonywh/backoffice
- Owner: edisonywh
- License: mit
- Created: 2021-03-25T16:48:38.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-10-09T20:51:31.000Z (about 2 years ago)
- Last Synced: 2024-12-06T15:52:18.818Z (19 days ago)
- Language: Elixir
- Size: 1.43 MB
- Stars: 217
- Watchers: 6
- Forks: 15
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Backoffice
Backoffice is an admin tool built with the PETAL stack (**P**hoenix, **E**lixir, **T**ailwind, **A**lpine, **L**iveView).
## Why did you build Backoffice?
I was working on refactoring [Slick Inbox](https://slickinbox.com). I looked at my admin tool which is built with LiveView, and didn’t like the repetitions that I saw. I am repeating a lot of the same things (search, pagination, form components, index.html etc) on every admin page that I have. They’re pretty simple pages. So why not refactor that?
I looked at the repetitive stuffs, extracted them, and then suddenly it looks like it could be general enough to be a library, so I experimented more and thus born `Backoffice`! 🎉
Another reason is that I think it would be awesome to have more LiveView projects in the open where we can learn from each other!
## What about other alternatives?
I know of three alternatives thus far:
- [Ash Admin](https://github.com/ash-project/ash_admin)
- [Torch](https://github.com/mojotech/torch)
- [Kaffy](https://github.com/aesmail/kaffy)
Ash Admin seems to only support Ash resources, and I don't use that, so that doesn't work for me.
Torch is a generator, it hooks onto the Phoenix generator and then generate resources for you. I'm not sure if I like that idea (you don't get updates for free) but I think the filter feature is pretty neat.
Kaffy is probably the most matured out of the three, and so I'll mostly be comparing to it.
1. Kaffy uses controllers, Backoffice uses LiveView
2. Kaffy works by `using` it in your router, the available paths are hidden from you, and you supply the configurations via application env, whereas Backoffice prefers explicitness (per module) and less on application env.
3. Kaffy has a more seamless experience as it magics its way across your schemas, with Backoffice it requires a longer set-up as you need to create modules per page (but more explicit).
4. Kaffy works under the assumption of your application being database-backed - Backoffice has an interesting `Resolver` concept, so you can write your own resolver and fetch your data from anywhere.
For example, with Kaffy:
```elixir
# router.exs
defmodule YourApp.Router do
use Kaffy.Routes
end
```
I’m not a fan of this idea since it’s not immediately obvious what routes are available. Kaffy routes are defined in `config.exs` (application env) which could potentially call out to a different `Config` module as well, but I prefer things to be colocated. To me, `router.exs` is the source of truth for the available routes in my app, so I prefer to keep everything centralised.
Therefore, with Backoffice:
```elixir
# router.exs
scope "/admin", YourAppWeb, do
live("/users", UserLive.Index, :index) # these are your existing pages
live("/users/:id/edit", UserLive.Index, :edit)
live("/newsletters", Backoffice.NewsletterLive.Index, layout: {Backoffice.LayoutView, :backoffice})
live("/newsletters/:id/edit", Backoffice.NewsletterLive.Single, layout: {Backoffice.LayoutView, :backoffice})
end
```
It sits right next to your existing set-up! This was my main goal, to easily see what routes are available to me.
But, as you might have noticed, this means you need to create a lot more modules, compared to Kaffy.
> I should also add that I referred to Ash Admin's and Kaffy's codebase quite a bit, so huge thanks to the contributors!
## Usage
1. Create a Layout module
```elixir
# lib/your_app_web/live/backoffice/layout.ex
# Icons are all from heroicons.com.
defmodule YourAppWeb.Backoffice.Layout do
@behaviour Backoffice.Layout
alias YourAppWeb.Routes.Helpers, as: Routes
def stylesheets do
[
Routes.static_path(YourAppWeb.Endpoint, "/css/app.css")
]
end
def scripts do
[
Routes.static_path(YourAppWeb.Endpoint, "/js/admin.js")
]
end
def logo do
Routes.static_path(YourAppWeb.Endpoint, "/images/admin-logo.svg")
end
def links do
[
%{
label: "User",
link: YourAppWeb.Router.Helpers.user_index_path(YourAppWeb.Endpoint, :index),
icon: """
"""
},
%{
label: "Nested Links",
expanded: true # default to false
links: [
%{
label: "Nested 1",
link: "#"
},
%{
label: "Nested 2",
link: "#"
}
]
}
%{
label: "LiveDashboard",
link: "/admin/dashboard",
icon: """
"""
},
]
end
end
```
2. Tell Backoffice about the layout you just created.
```elixir
# config.exs
config :backoffice, layout: YourAppWeb.Backoffice.Layout
```
3. Create a resource module:
```elixir
# lib/your_app_web/live/backoffice/users/index.ex
defmodule YourAppWeb.Backoffice.UserLive.Index do
use Backoffice.Resource.Index,
resolver: Backoffice.Resolvers.Ecto,
resolver_opts: [
repo: YourApp.Repo,
# Use preload and order_by
preload: [:mailbox, :notification_preference],
order_by: :id
],
resource: YourApp.Accounts.User
actions do
action :create, type: :page, handler: &__MODULE__.create/2
action :retry, type: :single, handler: &__MODULE__.retry/2
end
def retry(socket, resource_id) do
...
{:noreply, socket}
end
def create(socket, ids) do
ids = Enum.map(&(String.to_integer/1))
{:noreply, push_patch(socket, to: YourApp.Router.Helpers.live_path(socket, YourAppWeb.Backoffice.UserLive.Single, []))}
end
index do
field :id
field :verified, :boolean
field :age, :string, render: &__MODULE__.field/1 # 1-arity only, takes the resource itself
end
end
# lib/your_app_web/live/backoffice/users/single.ex
defmodule YourAppWeb.Backoffice.UserLive.Single do
# We name it single because it handles both :new and :edit.
use Backoffice.Resource.Single,
resolver: Backoffice.Resolvers.Ecto,
resolver_opts: [
repo: YourApp.Repo,
changeset: %{edit: &YourApp.Accounts.User.update_changeset/2},
preload: [:mailbox, :notification_preference]
],
resource: YourApp.Accounts.User
form do # default for both
field :verified, :boolean
field :username, :string
field :age, :custom, label: "Age", render: &__MODULE__.field/2 # 2-arity, `form` and `field`.
end
form :edit do # form for :edit action
...
end
form :new do # form for :new action
...
end
end
```
4. Provide the following plug in your endpoint.ex
```elixir
plug Plug.Static,
at: "/backoffice",
from: :backoffice,
gzip: false,
only: ~w(css js)
```
If `/backoffice` conflicts with one of your existing routes, you can customize the static_path in `YourAppWeb.Backoffice.Layout`
```elixir
# lib/your_app_web/live/backoffice/layout.ex
# Add this. Defaults to "/backoffice" if not overriden
def static_path(), do: "/whatever_you_want"
# ... the stylesheets, scripts, logo and links function
end
# lib/your_app_web/endpoint.ex
defmodule MyAppWeb.Endpoint do
# Add this instead
plug Plug.Static,
at: YourAppWeb.Backoffice.Layout.static_path(),
from: :backoffice,
gzip: false,
only: ~w(css js)
# ... other plugs
end
5. Set-up your resource module in the router.
```elixir
scope "/admin", YourAppWeb, do
live("/users", Backoffice.UserLive.Index, layout: {Backoffice.LayoutView, :backoffice})
live("/users/:id/edit", Backoffice.UserLive.Single, layout: {Backoffice.LayoutView, :backoffice})
end
```
6. You are done!
## Resolvers?
One interesting tidbit about Backoffice is that Backoffice itself doesn't make any assumption about where your data is from. This is pretty cool as it means Backoffice can ingest data from everywhere and display them!
The only requirement/caveat is:
- You need to build your own Resolver
- Your resource still needs to be a schema (embedded or not)
For example, you can write up an API resolver like this.
```elixir
defmodule Todo do
use Ecto.Schema
@primary_key false
embedded_schema do
field :userId, :string
field :id, :string
field :completed, :boolean
field :title, :string
end
end
defmodule Backoffice.Resolvers.API do
@behaviour Backoffice.Resolver
@impl true
def load(Todo, resolver_opts, _page_opts) do
url = Keyword.fetch!(resolver_opts, :url)
resp = HTTPoison.get!(url)
entries =
resp.body |> Jason.decode!(keys: :atoms) |> Enum.take(20) |> Enum.map(&struct!(Todo, &1))
# This is required for the pagination buttons to work
%Backoffice.Page{
entries: entries,
page_number: 1,
page_size: 10,
total_entries: 100,
total_pages: 5
}
end
@impl true
def search(mod, resource, resolver_opts, page_opts) do
load(resource, resolver_opts, page_opts)
end
end
```
## Widgets and Widget Protocol
Backoffice currently ships with one widget, `Backoffice.PlainWidget`.
To display widgets, just do:
```elixir
# lib/your_app_web/live/backoffice/user.ex
def widgets(socket) do
[
%Backoffice.PlainWidget{
title: "Total Collection",
data: "12"
}
]
end
```
Widgets in Backoffice are rendered with a protocol, so it is very easy for you to write one. You can refer to `Backoffice.PlainWidget`.
```elixir
defmodule YourWidget do
defimpl Backoffice.Widget do
def render do
{:safe, "Your Widget here"}
end
end
end
```
You can also render widget in your own custom page, just do `Backoffice.Widget.render(widget)`.
## Custom pages
Backoffice sits right next to your existing routes, this means to render custom pages, you need to:
```elixir
live("/dashboard", Admin.DashboardLive, layout: {Backoffice.LayoutView, :backoffice})
```
That's it! If you visit `/dashboard` it'll sit nicely next to the rest of the Backoffice layout. If you want to add it to the `links` on the left panel, update the `links/0` function in the layout module you supplied to Backoffice.
## Actions
Backoffice has two kinds of actions: `Page` and `Single`.
Page actions go on the top right of the page, whereas `Single` actions go inside each row.
Here's what an example actions set-up look like.
```elixir
actions do
action :create, type: :page, handler: &__MODULE__.create/2 # :label & :confirm are valid options
action :retry, type: :single, handler: &__MODULE__.retry/2
end
def retry(socket, resource_id) do
...
{:noreply, socket}
end
# Right now second argument to create is nil, but we might pass down list of ids down the road.
def create(socket, nil) do
{:noreply, push_patch(socket, to: YourApp.Router.Helpers.user_index_live(socket, :new, []))}
end
```
## Notifications
Backoffice has a neat little notification pop-up, you can also use it in your custom actions, or anyway you like.
For example,
```elixir
actions do
action :notify, type: :single, handler: &__MODULE__.notify/2
end
def notify(socket, id) do
# `push_notification/2` is an API provided by `Backoffice.LiveView.Helpers`.
{:noreply, push_notification(socket, title: "Editing #{id}", subtitle: "Subtitle")}
end
```
You can decide to show the notification pop-up when the resource is successfully updated for example, or you could use it on your Dashboard and hook it up to PubSub (maybe to monitor every purchase!), like so:
```elixir
# lib/your_app_web/live/backoffice/users/index.ex
defmodule YourAppWeb.Backoffice.UserLive.Index do
...
def mount(params, session, socket) do
if connected?(socket), do: Phoenix.PubSub.subscribe(My.PubSub, "info")
do_mount(params, session, socket) # `do_mount` is needed for backoffice to function.
end
def handle_info({:info, text}, socket) do
{:noreply, push_notification(socket, level: :info, title: "PubSub", subtitle: text)}
end
...
end
```
There's three level of notifications available right now, `:info`, `:success` and `:error`. E.g: `push_notification(socket, level: :error)`. Defaults to `:info`.
If you want to use notification in your custom page, there are two things you need. Refer to `Backoffice.LiveView.Helpers.push_notification/2` for more information.
There's also a slight caveat, you can't use `push_redirect` with `push_notification`, because [`push_redirect` doesn't work with `push_event`](https://github.com/phoenixframework/phoenix_live_view/blob/v0.15.4/lib/phoenix_live_view/utils.ex#L208-L214) (which is what `push_notification` uses under the hood). For that reason, Backoffice provides a callback so you can still do redirection, just do `push_notification(socket, redirect: url)`.
## Can I use Backoffice in production?
You sure can, but I would not really advise it. Backoffice is pre-release and in active development now, so it's bound to have a lot of breaking API changes. Use at your own risk.
For what it's worth, I am dogfooding it in production with [Slick Inbox](https://slickinbox.com).
There are quite a number of issues right now:
- [ ] Index & Form fields default might not be the best (form fields right now attempts to show assocs, but you need to explicitly preload it and you can't really edit them yet.)
- [ ] Association support is not great (it kinda works, but needs more testing/documentation)
- [ ] etc...
But, I encourage you to try it out anyway and contribute, and together we can make Backoffice great :)
## What's next for Backoffice?
Honestly I'd really love for the community to contribute more, as I've mentioned before, Slick's admin tool usage is pretty basic, so I'm fairly certain there are a lot of use cases that Backoffice is not equipped to handle. I'd also love to learn more LiveView patterns and/or tips & tricks from the community.
Other than that, here are some things I hope to improve:
- [ ] Better support for associations?
- [ ] Custom color/theme
- [ ] Better animations
- [ ] Datepicker support
- [ ] LiveComponent support (It is possible now, but I want to refine the API)
- [ ] Implement a test suite..
- [ ] Localization support?
- [ ] Authorisation?
- [ ] Better documentations
## Installation
Backoffice is not yet available on Hex, so to try it out you'd need to point to this Git repo.
```elixir
def deps do
[
{:backoffice, git: "https://github.com/edisonywh/backoffice"}
]
end
```