forked from tfwright/live_admin
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.md.eex
123 lines (80 loc) · 5.18 KB
/
README.md.eex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
<!-- This README was generated with docout (https://github.com/tfwright/docout). Edits should be made to the formatter instead of this file, other changes will be overridden on compile. -->
# LiveAdmin
[](https://hex.pm/packages/live_admin)
[](https://github.com/tfwright/live_admin/actions)
An admin UI for Phoenix applications built on [Phoenix LiveView](https://github.com/phoenixframework/phoenix_live_view) and [Ecto](https://github.com/elixir-ecto/ecto/).
Significant features:
* First class support for multi tenant applications via Ecto's `prefix` option
* Overridable views and API
* Easily add custom actions at the schema and record level
* Ability to edit (nested) embedded schemas
* i18n via [Gettext](elixir-gettext/gettext)
## Installation
First, ensure your Phoenix app has been configured to use [LiveView](https://hexdocs.pm/phoenix_live_view/installation.html).
Add to your app's `deps`:
```elixir
{:live_admin, "~> <%= app_version %>"}
```
Configure a module to act as a LiveAdmin resource:
```elixir
defmodule MyApp.MyResource do
use LiveAdmin.Resource, schema: MyApp.Schema
end
```
*Note: if you use an Ecto schema you can omit the `schema' option.*
In your Phoenix router, inside a scope configured to run LiveView (`:browser` if you followed the default installation), add the resource to a LiveAdmin instance:
```elixir
import LiveAdmin.Router
scope "/" do
pipe_through: :browser
live_admin "/my_admin" do
admin_resource "/my_schemas", MyApp.MyResource
end
end
```
Finally, tell LiveAdmin what Ecto repo to use to run queries in your `runtime.ex`:
```
config :live_admin, ecto_repo: MyApp.Repo
```
That's it, now an admin UI for `MyApp.Schema` will be available at `/my_admin/my_schemas`.
## Configuration
One of the main goals of LiveAdmin is to require as little config as possible.
It should work out of the box, with only the above, for the vast majority of common
app admin needs.
However, if you want to customize the behavior of one or more resources, including how records
are rendered or changes are validated, or to add custom behaviors, there are a variety of configuration options
available. This includes component overrides if you would like to completely control
every aspect of a particular resource view, like the edit form. For a complete list of options, see the `LiveAdmin.Resource` docs.
For additional convenience and control, configuration in LiveAdmin can be set at 3 different levels.
From most specific to most general, they are resource, admin instance, and global.
For concrete examples of the various config options and to see them in action, consult the [development app](#development-environment).
### Resource
The second argument passed to `use LiveAdmin.Resource` will configure only that specific resource,
in any LiveView it is used. If the module is not an Ecto schema, the `:schema` option must be passed.
If you would like the same schema to behave differently in different LiveAdmin instances, or different
routes in the same instance, you must create multiple resource modules to contain that configuration.
### Admin instance
The second argument passed to `live_admin` will configure defaults for all resources in the group
that do not specify the same configuration. Currently only component overrides and the repo can be
configured at this level.
### Global
All resource configuration options can also be set in the LiveAdmin app runtime config. This will set a global
default to apply to all resources unless overridden in their individual config, or the LiveAdmin instance.
Additionally, the following options can only be set at the global level:
* `css_overrides` - a binary or MFA identifying a function that returns CSS to be appended to app css
* `session_store` - a module implementing the `LiveAdmin.Session.Store` behavior, used to persist session data
* `gettext_backend` - a module implementing the [Gettext API](https://hexdocs.pm/gettext/Gettext.html#module-gettext-api) that will be used for translations
## Multi tenancy
To enable Multi tenant support, simply implement a `prefixes/0` function in your Ecto Repo module that returns a list of prefixes.
A dropdown will be added to the top nav bar that will allow you to switch between tenants.
## i18n
LiveAdmin wraps all static strings in the UI with Gettext calls, but currently it does *not* provide any locales by default.
To enable i18n, implement a `locales/0` function returning a list of binary locale names on your Gettext Backend module.
Unfortunately it is not currently possible to use Gettext's utilities to automatically extract the pot files so you will need to do this manually.
To avoid conflicts with your own app's translations, it is recommended to use a separate Gettext backend for LiveAdmin.
## Development environment
This repo has been configured to run the application in [Docker](https://www.docker.com/) using [Compose](https://docs.docker.com/compose/).
The Phoenix app is running the `app` service, so all mix command should be run there. Examples:
* `docker compose run web mix test`
---
README generated with [docout](https://github.com/tfwright/docout)