diff --git a/README.md b/README.md index 2ee8b8e8..bbc84b20 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,42 @@ -# Backpex + [![CI](https://github.com/naymspace/backpex/actions/workflows/ci.yml/badge.svg)](https://github.com/naymspace/backpex/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/naymspace/backpex/blob/develop/LICENSE.md) [![Hex](https://img.shields.io/hexpm/v/backpex.svg)](https://hex.pm/packages/backpex) [![Hex Docs](https://img.shields.io/badge/hex-docs-green)](https://hexdocs.pm/backpex) -Backpex is a simple admin dashboard that makes it easy to manage existing resources in your application. - -See our comprehensive [docs](https://hexdocs.pm/backpex) for more information. +# Backpex -## Screenshot ([Live Demo](https://backpex.live/admin/users)) +Welcome! Backpex is a highly customizable administration panel for Phoenix LiveView applications. Quickly create beautiful CRUD views for your existing data using configurable *LiveResources*. Backpex integrates seamlessly with your existing Phoenix application and provides a simple way to manage your resources. It is highly customizable and can be extended with your own layouts, views, field types, filters and more. -![Backpex Screenshot](priv/static/images/screenshot.png) +![Backpex Screenshot](https://github.com/naymspace/backpex/blob/develop/priv/static/images/screenshot.png) -## Development +
+ Visit our Live Demo → +
-### Requirements +## Key Features -- [Docker](https://www.docker.com/) +- **LiveResources**: Quickly create LiveResource modules for your database tables with fully customizable CRUD views. Bring your own layout or use our components. +- **Search and Filters**: Define searchable fields on your resources and add custom filters. Get instant results with the power of Phoenix LiveView. +- **Resource Actions**: Add your globally available custom actions (like user invitation or exports) with additional form fields to your LiveResources. +- **Authorization**: Handle authorization for all your CRUD and custom actions via simple pattern matching. Optionally integrate your own authorization library. +- **Field Types**: Many field types (e.g. Text, Number, Date, Upload) are supported out of the box. Easily create your own field type modules with custom logic. +- **Associations**: Handle HasOne, BelongsTo and HasMany(Through) associations with minimal configuration. Customize available options and rendered columns. +- **Metrics**: Easily add value metrics (like sums or averages) to your resources for a quick glance at your date. More metric types are in the making. -### Recommended Extensions +## Installation & Documentation -- [Editorconfig](http://editorconfig.org) -- [JavaScript Standard Style](https://github.com/standard/standard#are-there-text-editor-plugins) +See our comprehensive [installation guide](guides/get_started/installation.md) for more information on how to install and configure Backpex in your Phoenix application. -### Setup +We also provide a detailed [documentation](https://hexdocs.pm/backpex) with guides on how to use Backpex and how to customize it to your needs. -- Clone the repository. -- In `demo` directory run `cp .env.example .env` and set values accordingly. - - Generate `SECRET_KEY_BASE` via `mix phx.gen.secret`. - - Generate `LIVE_VIEW_SIGNING_SALT` via `mix phx.gen.secret 32`. -- Run `docker compose up` (`yarn watch` is triggered automatically). +## Learn More -Now you can visit [`localhost:4000`](http://localhost:4000) from your browser. +- [What is Backpex?](guides/about_backpex/what-is-backpex.md) +- [Why we built Backpex?](guides/about_backpex/why-we-built-backpex.md) +- [Contribute to Backpex](guides/about_backpex/contribute-to-backpex.md) ## License -Backpex source code is licensed under the [MIT License](LICENSE.md). +Backpex source code is licensed under the [MIT License](https://github.com/naymspace/backpex/blob/main/LICENSE.md). \ No newline at end of file diff --git a/guides/about/contribute-to-backpex.md b/guides/about/contribute-to-backpex.md new file mode 100644 index 00000000..93aa506d --- /dev/null +++ b/guides/about/contribute-to-backpex.md @@ -0,0 +1,50 @@ +# Contribute to Backpex + +We are excited to have you contribute to Backpex! We are always looking for ways to improve the project and welcome any contributions in the form of bug reports, feature requests, documentation improvements, code contributions, and more. + +## What can I contribute? + +We are in the process of writing a roadmap to outline the features we plan to implement in the future. In the meantime, you can contribute to Backpex by: + +- Reporting bugs +- Requesting new features +- Improving the documentation +- Improving the demo application +- Fixing bugs + +## Fork the repository + +In order to contribute to Backpex, you need to fork the repository. You can do this by clicking the "Fork" button in the top right corner of the repository page at [https://github.com/naymspace/backpex](https://github.com/naymspace/backpex). + +## Clone the repository + +After forking the repository, you need to clone it to your local machine. You can do this by running the `git clone` command along with the URL of your forked repository. + +## Setting up your development environment + +You first need to create a `.env` file in the `demo` directory of the project with the following content: + +```bash +SECRET_KEY_BASE= +LIVE_VIEW_SIGNING_SALT= +``` + +For development purposes you can copy the values from the `demo/.env.example` file. + +You can then start the development environment by running the following command in the root directory of the project: + +```bash +docker compose up +``` + +Backpex comes with a demo application that you can use to test the features of the project. The command will start a PostgreSQL database and the demo application on [http://localhost:4000](http://localhost:4000). + +To insert some demo data into the database, you can run the following command: + +```bash +docker compose exec app mix ecto.seed +``` + +## Making changes + +After setting up your development environment, you can start making changes to the project. We recommend creating a new branch for your changes. After submitting your changes to your forked repository, you can create a pull request to the `develop` branch of the main repository. diff --git a/guides/about/what-is-backpex.md b/guides/about/what-is-backpex.md new file mode 100644 index 00000000..81c79a6a --- /dev/null +++ b/guides/about/what-is-backpex.md @@ -0,0 +1,9 @@ +# What is Backpex? + +Backpex is a highly customizable administration panel for Phoenix LiveView applications. It allows you to quickly create CRUD views of your existing data using configurable *LiveResources*. Backpex integrates seamlessly with your existing Phoenix LiveView application and provides an easy way to manage your resources. It is highly customizable and can be extended with your own layouts, views, field types, filters and more. + +Backpex is built on top of Phoenix LiveView and provides a rich set of features to manage your resources. With Backpex, you can set up an administration panel for your application in minutes, not hours. + +Whether you want to quickly scaffold CRUD views for your existing data or build a full-fledged administration panel, Backpex has you covered. + +TODO: add screenshots of key features here diff --git a/guides/about/why-we-built-backpex.md b/guides/about/why-we-built-backpex.md new file mode 100644 index 00000000..32912629 --- /dev/null +++ b/guides/about/why-we-built-backpex.md @@ -0,0 +1,7 @@ +# Why we built Backpex? + +After building several Phoenix applications, we realized that we were repeating ourselves when it came to building administration panels. We were writing the same CRUD views, search and filter functionality over and over again. We wanted a tool that would allow us to quickly scaffold these views and focus on building the core functionality of our applications. + +The tool we wanted had to be able to serve as a simple backend administration panel in one project, while being the core of the application in another. + +We looked at existing solutions, but found that none of them offered the flexibility and customization we were looking for. We decided to develop Backpex to solve this problem and provide a highly customizable administration panel for Phoenix LiveView applications. \ No newline at end of file diff --git a/guides/actions/item-actions.md b/guides/actions/item-actions.md new file mode 100644 index 00000000..d2505b4d --- /dev/null +++ b/guides/actions/item-actions.md @@ -0,0 +1,192 @@ +# Item Actions + +An item action defines an action (such as deleting a user) that can be performed on one or more items. Unlike resource actions, item actions are not automatically performed on all items in a resource. + +An item action could be something like deleting a user, or sending an email to a specific user. + +There are multiple ways to perform an Item Action: +- use the checkboxes in the first column of the resource table to select 1-n items and trigger the action later on +- use an icon in the last column of the resource table to perform the Item Action for one item +- use the corresponding icon in the show view to perform the Item Action for the corresponding item + +If you use the first method, you must trigger the item action using the button above the resource action. If you use the second or third method, the item action is triggered immediately. + +Backpex ships with a few built-in item actions, such as `delete`, `show`, and `edit`. + +## Configuration + +To add an item action to a resource, you need to implement the [`item_actions/1`](Backpex.LiveResource.html#c:item_actions/1) callback in your resource configuration module. The function should return a list of maps, where each map represents an item action. It takes the default item actions as an argument. This way you can add your custom item actions to the default ones or even replace them. + +Let's say we want to add a `show` item action to navigate to the show view of a user and replace all other default item actions. + +First, we need to add the item action to our resource configuration module. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def item_actions([_show, _edit, _delete]) do + [ + show: %{ + module: DemoWeb.ItemAction.Show + } + ] +end +``` + +In the above example, we only return the `show` item action. This way we replace the default `show`, `edit`, and `delete` item actions with our custom `show` item action. + +## Implementing an Item Action + +An item action is a module that uses the `Backpex.ItemAction` module. To get started, you can use the `BackpexWeb` module and provide the `:item_action` option. This will import the necessary functions and macros to define an item action. + +In the following example, we define an item action to navigate to the show view of a user. + +```elixir +defmodule DemoWeb.ItemAction.Show do + use BackpexWeb, :item_action + + @impl Backpex.ItemAction + def icon(assigns) do + ~H""" + + """ + end + + @impl Backpex.ItemAction + def label(_assigns), do: Backpex.translate("Show") + + @impl Backpex.ItemAction + def handle(socket, [item | _items], _change) do + path = Router.get_path(socket, socket.assigns.live_resource, socket.assigns.params, :show, item) + {:noreply, Phoenix.LiveView.push_patch(socket, to: path)} + end +end +``` + +Like in resource actions the `handle/3` function is called when the item action is triggered. The handle function receives the socket, the items that should be affected by the action, and the parameters that were submitted by the user. + +In the above example, we define an item action to navigate to the show view of a user. The `handle/3` function is used to navigate to the show view of the user. The `Router.get_path/5` function is used to generate the path to the show view of the user. + +See `Backpex.ItemAction` for a list of all available callbacks. + +## Placement of Item Actions + +Item actions can be placed in the resource table or in the show view. You can specify the placement of the item action by using the `only` key. + +The only key must provide a list and accepts the following options + +* `:row` - display an icon for each element in the table that can trigger the Item Action for the corresponding element +* `:index` - display a button at the top of the resource table, which triggers the Item Action for selected items +* `:show` - display an icon in the show view that triggers the Item Action for the corresponding item + +The following example shows how to place the `show` item action on the index table rows only. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def item_actions([_show, _edit, _delete]) do + [ + show: %{ + module: DemoWeb.ItemAction.Show, + only: [:row] + } + ] +end +``` + +## Advanced Item Action + +In the following example, we define an item action to soft delete users. The item action will also asked the user for a reason before the user can be deleted. + +First, wee need to add the item action to our resource configuration module. + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def item_actions([show, edit, _delete]) do + Enum.concat([show, edit], + soft_delete: %{module: DemoWeb.ItemAction.SoftDelete} + ) +end +``` + +In the above example, we add the `soft_delete` item action to the default item actions. We do not add the default `delete` item action to the list of item actions. This way we replace the default `delete` item action with our custom `soft_delete` item action. + +Next, we need to implement the item action module. + +```elixir +defmodule DemoWeb.ItemAction.SoftDelete do + use BackpexWeb, :item_action + + alias Backpex.Resource + + @impl Backpex.ItemAction + def icon(assigns) do + ~H""" + + """ + end + + @impl Backpex.ItemAction + def fields do + [ + reason: %{ + module: Backpex.Fields.Textarea, + label: "Reason", + type: :string + } + ] + end + + @required_fields ~w[reason]a + + @impl Backpex.ItemAction + def changeset(change, attrs) do + change + |> cast(attrs, @required_fields) + |> validate_required(@required_fields) + end + + @impl Backpex.ItemAction + def label(_assigns), do: Backpex.translate("Delete") + + @impl Backpex.ItemAction + def confirm_label(_assigns), do: Backpex.translate("Delete") + + @impl Backpex.ItemAction + def cancel_label(_assigns), do: Backpex.translate("Cancel") + + @impl Backpex.ItemAction + def handle(socket, items, params) do + datetime = DateTime.truncate(DateTime.utc_now(), :second) + + socket = + try do + {:ok, _items} = + Backpex.Resource.update_all( + socket.assigns, + items, + [set: [deleted_at: datetime, reason: Map.get(params, "reason")]], + "deleted" + ) + + socket + |> clear_flash() + |> put_flash(:info, "Item(s) successfully deleted.") + rescue + socket + |> clear_flash() + |> put_flash(:error, error) + end + + {:noreply, socket} + end +end +``` + +In the above example, we define an item action to soft delete users. The item action will also ask the user for a reason before the user can be deleted. The user needs to fill out the reason field before the item action can be performed. The reason field is defined in the `fields/0` function. The `changeset/2` function is used to validate the user input. + +The `handle/3` function is called when the item action is triggered. The handle function receives the socket, the items that should be affected by the action, and the parameters that were submitted by the user. + +By default an item action is triggered immediately when the user clicks on the corresponding icon in the resource table or in the show view, but an item actions also supports a confirmation dialog. To enable the confirmation dialog you need to implement the `confirm_label/1` function and return a string that will be displayed in the confirmation dialog. The confirmation dialog will be displayed when the user clicks on the icon in the resource table. \ No newline at end of file diff --git a/guides/actions/resource-actions.md b/guides/actions/resource-actions.md new file mode 100644 index 00000000..ddf0891d --- /dev/null +++ b/guides/actions/resource-actions.md @@ -0,0 +1,90 @@ +# Resource Actions + +Resource actions are a way to define custom actions that can be performed on a whole resource. + +A resource action could be something like exporting a resource to a CSV file, or sending an email to all users in a resource. + +## Configuration + +You define resource actions by implementing the [`resource_actions/0`](Backpex.LiveResource.html#c:resource_actions/0) callback in your resource configuration module. + +Let's say you have a resource called `User` and you want to add a resource action to invite users to your application. + +First, you need to add the resource action to your resource configuration module. + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def resource_actions() do +[ + invite: %{ + module: MyWebApp.Admin.ResourceActions.Invite, + } +] +end +``` + +Each resource action is a map with at least the module key. The module key should point to the module that implements the resource action. The key in the keyword list is the unique `id` of the resource action. + +## Implementing a Resource Action + +A resource action is a module that uses the `Backpex.ResourceAction` module. + +```elixir +defmodule MyAppWeb.Admin.Actions.Invite do + use Backpex.ResourceAction + + import Ecto.Changeset + + @impl Backpex.ResourceAction + def label, do: "Invite" + + @impl Backpex.ResourceAction + def title, do: "Invite user" + + # you can reuse Backpex fields in the field definition + @impl Backpex.ResourceAction + def fields do + [ + email: %{ + module: Backpex.Fields.Text, + label: "Email", + type: :string + } + ] + end + + @impl Backpex.ResourceAction + def changeset(change, attrs) do + change + |> cast(attrs, [:email]) + |> validate_required([:email]) + |> validate_email(:email) + end + + @impl Backpex.ResourceAction + def handle(_socket, params) do + # Send mail + + # We suppose there was no error. + if true do + {:ok, "An invitation email to #{params[:email]} was sent successfully."} + else + {:error, "An error occurred while sending an invitation email to #{params[:email]}!"} + end + end +end +``` + +See `Backpex.ResourceAction` for a documentation of the callbacks. + +The [`handle/2`](Backpex.ResourceAction.html#c:handle/2) callback is called when the user submits the form to perform the action. In this example, we suppose there was no error sending the invitation email and return a success message. + +You can access the email entered by the user in the `params` argument. + +We validate the email address using the `validate_email/2` function provided by the `Ecto.Changeset` module. + +> #### Info {: .info} +> +> Each resource action has its own route. The route is defined by the `id` of the resource action. If you use the [`live_resource/3`](Backpex.Router.html#live_resources/3) macro, the route is automatically added to the live resource. \ No newline at end of file diff --git a/guides/authorization/field-authorization.md b/guides/authorization/field-authorization.md new file mode 100644 index 00000000..7ae0277d --- /dev/null +++ b/guides/authorization/field-authorization.md @@ -0,0 +1,29 @@ +# Field Authorization + +You can define authorization rules for your fields. + +## Configuration + +To define authorization rules for a field, you may use the `can?/1` callback for a field configuration. It takes the assigns and has to return a boolean value. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + inserted_at: %{ + module: Backpex.Fields.DateTime, + label: "Created At", + can?: fn + %{live_action: :show} = _assigns -> + true + + _assigns -> + false + end + } +] +end +``` + +The above example will show the `inserted_at` field only in the show view. diff --git a/guides/authorization/live-resource-authorization.md b/guides/authorization/live-resource-authorization.md new file mode 100644 index 00000000..a496d7ff --- /dev/null +++ b/guides/authorization/live-resource-authorization.md @@ -0,0 +1,53 @@ +# LiveResource Authorization + +You are able to define authorization rules for your resources. The authorization rules are defined in the resource configuration file and are used to control access to certain actions. + +## Configuration + +To define authorization rules for a resource, you need to implement the [`can/3`](Backpex.LiveResource.html#c:can?/3) callback in the resource configuration file. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def can?(assigns, :show, item), do: false +def can?(assigns, action, item), do: true +``` + +The example above will deny access to the `show` action and allow access to all other actions. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def can?(assigns, :show, item) do + user = assigns.current_user + + item.user_id == user.id +end‚ + +def can?(assigns, action, item), do: true +``` + +The example above will deny access to the `show` action if the `user_id` of the item does not match the `id` of the current user. + +You can also use [`can/3`](Backpex.LiveResource.html#c:can?/3) to restrict access to item or resource actions. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def can?(_assigns, :my_item_action, item), do: item.role == :admin +def can?(assigns, action, item), do: true +``` + +The example above will deny access to the `my_item_action` action if the `role` of the item is not `:admin`. + +## Parameters + +The `can?` callback receives the following parameters: + +- `assigns` - the assigns of the LiveView +- `action` - the action that is being authorized (available actions are: `:index` , `:new`, `:show`, `:edit`, `:delete`, `:your_item_action_key`, `:your_resource_action_key`) +- `item` - the item that is being authorized + +## Return value + +The `can?` callback must return a boolean value. If the return value is `true`, the action is allowed. If the return value is `false`, the action is denied. \ No newline at end of file diff --git a/guides/fields/alignment.md b/guides/fields/alignment.md new file mode 100644 index 00000000..7a46b466 --- /dev/null +++ b/guides/fields/alignment.md @@ -0,0 +1,46 @@ +# Alignment + +It is possible to align the fields of a resource in the index view and the labels of the fields in the edit view. + +## Field Alignment (Index View) + +You can align the fields of a resource in the index view by setting the `align` option in the field configuration. + +The following alignments are supported: `:left`, `:center` and `:right` + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def fields do +[ + %{ + ..., + align: :center + } +] +end +``` + +The example above will align the field to the center in the index view. + +## Label Alignment (Edit View) + +You can align the labels of the fields in the edit view by setting the `label_align` option in the field configuration. + +The following label orientations are supported: `:top`, `:center` and `:bottom`. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + %{ + ..., + align_label: :top + } +] +end +``` + +The example above will align the label to the top in the edit view. \ No newline at end of file diff --git a/guides/fields/computed-fields.md b/guides/fields/computed-fields.md new file mode 100644 index 00000000..d3c3d628 --- /dev/null +++ b/guides/fields/computed-fields.md @@ -0,0 +1,86 @@ +# Computed Fields + +In some cases you want to compute new fields based on existing fields. Backpex adds a way to support this. + +## Configuration + +There is a `select` option you may add to a field. This option has to return a `dynamic`. This query will then be executed to select fields when listing your resources. In addition this query will also be used to order / search this field. + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def fields do +[ + total: %{ + module: Backpex.Fields.Integer, + label: "Total", + select: dynamic([post: p], fragment("likes + dislikes")), + } +] +end +``` + +The example above will compute the value of the total field based on the `likes` and `dislikes` fields. + +## Example + +Imagine there is a user table with `first_name` and `last_name`. Now, on your index view you want to add a column to display the `full_name`. You could create a generated column in you database, but there are several reasons for not adding generated columns for all computed fields you want to display in your application. + +You can display the `full_name` of your users by adding the following field to the resource configuration file. + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def fields do +[ + full_name: %{ + module: Backpex.Fields.Text, + label: "Full Name", + searchable: true, + except: [:edit], + select: dynamic([user: u], fragment("concat(?, ' ', ?)", u.first_name, u.last_name)) + } +] +end +``` + +We are using a database fragment to build the `full_name` based on the `first_name` and `last_name` of an user. Backpex will select this field when listing resources automatically. Ordering and searching works the same like on all other fields, because Backpex uses the query you provided in the `dynamic` in order / search queries, too. + +We recommend to display this field on `index` and `show` view only. + +> #### Important {: .info} +> +> Note: You are required to add a virtual field `full_name` to your user schema. Otherwise, Backpex is not able to select this field. + +## Computed Fields with Associations + +Computed fields also work with associations. + +For example, you are able to add a `select` query to a `Backpex.Field.BelongsTo` field. + +Imagine you want to display a list of posts with the corresponding authors (users). The user column should be a `full_name` computed by the `first_name` and `last_name`: + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def fields do +[ + user: %{ + module: Backpex.Fields.BelongsTo, + label: "Full Name", + display_field: :full_name, + select: dynamic([user: u], fragment("concat(?, ' ', ?)", u.first_name, u.last_name)), + options_query: fn query, _assigns -> + query |> select_merge([user], %{full_name: fragment("concat(?, ' ', ?)", user.first_name, user.last_name)}) + end + } +] +end +``` + +We recommend to add a `select_merge` to the `options_query` where you select the same field. Otherwise, displaying the same values in the select form on edit page will not work. + +Do not forget to add the virtual field `full_name` to your user schema in this example, too. diff --git a/guides/fields/custom-alias.md b/guides/fields/custom-alias.md new file mode 100644 index 00000000..f9e4d28b --- /dev/null +++ b/guides/fields/custom-alias.md @@ -0,0 +1,26 @@ +# Custom Alias + +Backpex automatically generates aliases for queries in your fields. However, if you try to add two `Backpex.Field.BelongsTo` fields of the same association, you will encounter an error indicating that the alias is already in use by another field. To resolve this issue, Backpex allows the assignment of custom aliases to fields, eliminating naming conflicts in queries. + +## Configuration + +To use a custom alias, define the `custom_alias` key in your field configuration. The value of the `custom_alias` key must be a unique atom that is not already in use by another field. + + +```elixir +@impl Backpex.LiveResource +def fields do +[ + second_category: %{ + module: Backpex.Fields.BelongsTo, + label: "Second Category", + display_field: :name, + searchable: true, + custom_alias: :second_category, + select: dynamic([second_category: sc], sc.name) + }, +] +end +``` + +The example above will assign the alias `:second_category` to the `second_category` field. This alias can now be used in queries without causing conflicts with other fields. \ No newline at end of file diff --git a/guides/fields/custom-fields.md b/guides/fields/custom-fields.md new file mode 100644 index 00000000..435dcf80 --- /dev/null +++ b/guides/fields/custom-fields.md @@ -0,0 +1,45 @@ +# Custom Fields + +Backpex ships with a set of default fields that can be used to create content types. See [Built-in Field Types](what-is-a-field.md#built-in-field-types) for a complete list of the default fields. In addition to the default fields, you can create custom fields for more advanced use cases. + +When creating your own custom field, you can use the `field` macro from the `BackpexWeb` module. It automatically implements the `Backpex.Field` behavior and defines some aliases and imports. + +> #### Information {: .info} +> +> A field has to be a [LiveComponent](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveComponent.html). + +## Creating a Custom Field + +The simplest version of a custom field would look like this: + +```elixir +use BackpexWeb, :field + +@impl Backpex.Field +def render_value(assigns) do +~H""" +

+ <%= HTML.pretty_value(@value) %> +

+""" +end + +@impl Backpex.Field +def render_form(assigns) do +~H""" +
+ + <:label> + + + + +
+""" +end +``` + +The `render_value/1` function returns markup that is used to display a value on `index` and `show` views. +The `render_form/1` function returns markup that is used to render a form on `edit` and `new` views. + +See `Backpex.Field` for more information on the available callback functions. For example, you can implement `render_index_form/1` to make the field editable in the index view. diff --git a/guides/fields/debounce-and-throttle.md b/guides/fields/debounce-and-throttle.md new file mode 100644 index 00000000..552bf711 --- /dev/null +++ b/guides/fields/debounce-and-throttle.md @@ -0,0 +1,94 @@ +# Debounce and Throttle + +You can debounce and throttle the input of a field in the edit view. This is useful when you want to reduce the number of requests sent to the server. + +## Configuration + +To enable debounce or throttle for a field, you need to set the `debounce` or `throttle` option in the field configuration. + +- `debounce`: Has to return either an integer timeout value (in milliseconds), or "blur". When an integer is provided, emitting the event is delayed by the specified milliseconds. When "blur" is provided, emitting the event is delayed until the field is blurred by the user. +- `throttle`: Has to return an integer timeout value (in milliseconds). The event is emitted at most once every specified milliseconds. + +See Phoenix LiveView documentation for more information on [debouncing and throttling](https://hexdocs.pm/phoenix_live_view/bindings.html#rate-limiting-events-with-debounce-and-throttle). + +The options can be set to a function that receives the assigns and returns the debounce or throttle value or a static value. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + username: %{ + module: Backpex.Fields.Text, + label: "Username", + debounce: 500 + } +] +end +``` + +The example above will debounce the input of the `username` field by 500 milliseconds. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + username: %{ + module: Backpex.Fields.Text, + label: "Username", + debounce: fn _assigns -> 500 end + } +] +end +``` + +The example above will debounce the input of the `username` field by 500 milliseconds. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + username: %{ + module: Backpex.Fields.Text, + label: "Username", + debounce: "blur" + } +] +end +``` + +The example above will debounce the input of the `username` field until the field is blurred by the user. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + username: %{ + module: Backpex.Fields.Text, + label: "Username", + throttle: 500 + } +] +end +``` + +The example above will throttle the input of the `username` field by 500 milliseconds. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + username: %{ + module: Backpex.Fields.Text, + label: "Username", + throttle: fn _assigns -> 500 end + } +] +end +``` + +The example above will throttle the input of the `username` field by 500 milliseconds. \ No newline at end of file diff --git a/guides/fields/defaults.md b/guides/fields/defaults.md new file mode 100644 index 00000000..b084ebce --- /dev/null +++ b/guides/fields/defaults.md @@ -0,0 +1,21 @@ +# Defaults + +You can assign default values to fields in your resource configuration file. This is useful when you want to provide a default value for a field that is not required. + +## Configuration + +To define a default value for a field, you need to set the `default` option in the field configuration. The `default` option has to return a function that receives the assigns and returns the default value. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + username: %{ + default: fn _assigns -> "Default Username" end + } +] +end +``` + +The example above will assign the default value `"Default Username"` to the `username` field. diff --git a/guides/fields/error-customization.md b/guides/fields/error-customization.md new file mode 100644 index 00000000..dc60c04d --- /dev/null +++ b/guides/fields/error-customization.md @@ -0,0 +1,28 @@ +# Error Customization + +You can customize the error messages for each field in your resource configuration file. + +## Configuration + +To customize the error messages for a field, you need to define a `translate_error/1` function in the field configuration. The function receives the error tuple and must return a tuple with the message and metadata. + +```elixir +@impl Backpex.LiveResource +def fields do +[ + number: %{ + module: Backpex.Fields.Number, + label: "Number", + translate_error: fn + {_msg, [type: :integer, validation: :cast] = metadata} = _error -> + {"has to be a number", metadata} + + error -> + error + end + } +] +end +``` + +The example above will return the message `"has to be a number"` when the input is not a number. diff --git a/guides/fields/index-edit.md b/guides/fields/index-edit.md new file mode 100644 index 00000000..d771d62a --- /dev/null +++ b/guides/fields/index-edit.md @@ -0,0 +1,35 @@ +# Index Edit + +A small number of fields support index editable. These fields can be edited inline on the index view. + +## Configuration + +To enable index editable for a field, you need to set the `index_editable` option to `true` in the field configuration. + +```elixir +# in your resource configuration file +def fields do +[ + name: %{ + module: Backpex.Fields.Text, + label: "Name", + index_editable: true + } +] +end +``` + +The example above will enable index editable for the `name` text field. + +## Supported fields + +- `Backpex.Fields.BelongsTo` +- `Backpex.Fields.Date` +- `Backpex.Fields.DateTime` +- `Backpex.Fields.Number` +- `Backpex.Fields.Select` +- `Backpex.Fields.Text` + +## Custom index editable implementation + +You can add index editable support to your custom fields by defining the [render_index_form/1](Backpex.Field.html#c:render_index_form/1) function and enabling index editable for your field. \ No newline at end of file diff --git a/guides/fields/placeholder.md b/guides/fields/placeholder.md new file mode 100644 index 00000000..bb384875 --- /dev/null +++ b/guides/fields/placeholder.md @@ -0,0 +1,27 @@ +# Placeholder + +You can configure a placeholder for form fields. The placeholder will be displayed in the input field when the field is empty. + +> #### Important {: .info} +> +> Note that the option only works for input fields that are **not** type `textarea`, `select`, `toggle` or `checkbox`. +> +## Configuration + +To set a placeholder for a field, you need to set the `placeholder` option in the field configuration. The `placeholder` either has to be a string or a function that receives the assigns and returns the placeholder string. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + username: %{ + module: Backpex.Fields.Text, + label: "Username", + placeholder: "Enter your username" + } +] +end +``` + +The example above will set the placeholder `"Enter your username"` for the `username` field. diff --git a/guides/fields/readonly.md b/guides/fields/readonly.md new file mode 100644 index 00000000..aeb03a9b --- /dev/null +++ b/guides/fields/readonly.md @@ -0,0 +1,77 @@ +# Readonly + +Fields can be configured to be readonly. In edit view, these fields are rendered with the additional HTML attributes `readonly` and `disabled`, ensuring that the user cannot interact with the field or change its value. + +In index view, if readonly and index editable is set to `true`, forms will be rendered with the `readonly` HTML attribute. + +## Supported fields + +On index view, read-only is supported for all fields with the index editable option (see [Index Edit](index-edit.md)). + +On edit view, read-only is supported for: +- `Backpex.Fields.Date` +- `Backpex.Fields.DateTime` +- `Backpex.Fields.Number` +- `Backpex.Fields.Text` +- `Backpex.Fields.Textarea` + +## Configuration + +To enable read-only for a field, you need to set the `readonly` option to `true` in the field configuration. This key must contain either a boolean value or a function that returns a boolean value. + +```elixir +# in your resource configuration file +def fields do +[ + rating: %{ + module: Backpex.Fields.Text, + label: "Rating", + readonly: fn assigns -> + assigns.current_user.role in [:employee] + end + } +] +end +``` + +```elixir +# in your resource configuration file +def fields do +[ + rating: %{ + module: Backpex.Fields.Text, + label: "Rating", + readonly: true + } +] +end +``` + +## Readonly for custom fields + +You can also add readonly functionality to a custom field. To do this, you need to define a [`render_form_readonly/1`](Backpex.Field.html#c:render_form_readonly/1) function. This function must return markup to be used when readonly is enabled. + +```elixir +@impl Backpex.Field +def render_form_readonly(assigns) do +~H""" +
+ + <:label> + + + + +
+""" +end +``` + +When defining a custom field with index editable support, you need to handle the readonly state in the index editable markup. There is a `readonly` value in the assigns, which will be `true` or `false`. diff --git a/guides/fields/visibility.md b/guides/fields/visibility.md new file mode 100644 index 00000000..a870da1f --- /dev/null +++ b/guides/fields/visibility.md @@ -0,0 +1,136 @@ +# Visibility + +You can change the visibility of fields in certain views. + +## Visibility with `only` and `except` + +You can use the `only` and `except` options to define the views where a field should be visible. The `only` option will show the field only in the specified views, while the `except` option will show the field in all views except the specified ones. The options have to be a list of view names. + +The following values are supported: `:new`, `:edit`, `:show`, `:index` and `:resource_action`. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + likes: %{ + module: Backpex.Fields.Number, + label: "Likes", + only: [:show, :edit] + } +] +end +``` + +The example above will show the `likes` field only in the show and edit views. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + likes: %{ + module: Backpex.Fields.Number, + label: "Likes", + except: [:new] + } +] +end +``` + +The example above will show the `likes` field in all views except the new view. + +## Visibility with `visible` + +> #### Important {: .info} +> +> Note that the option `visible` is only available for the show and edit views. + +To change the visibility of a field, you can also set the `visible` option in the field configuration. The `visible` option has to return a function that receives the assigns and returns a boolean value. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + likes: %{ + module: Backpex.Fields.Number, + label: "Likes", + visible: fn assigns -> + assigns.current_user.role in [:admin] + end + } +] +end +``` + +The example above will show the `likes` field only to users with the `admin` role. + + +> #### Warning {: .warning} +> +> Note that hidden fields are not exempt from validation by Backpex itself and the visible function is not executed on `:index`. + +## Visibility with `can?` + +In addition to the `visible` option, we provide a `can?` option that you can use to determine the visibility of a field. + +It can also be used on `:index`. It takes the `assigns` as a parameter and has to return a boolean value. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + inserted_at: %{ + module: Backpex.Fields.DateTime, + label: "Created At", + can?: fn + %{live_action: :show} = _assigns -> + true + + _assigns -> + false + end + } +] +end +``` + +Also see the [field authorization](/guides/authorization/field-authorization.md) guide. + +## Advanced Example + +Imagine you want to implement a checkbox in order to toggle an input field (post likes). The input field should be visible when it has a certain value (post likes > 0). + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + # show_likes is a virtual field in the post schema + show_likes: %{ + module: Backpex.Fields.Boolean, + label: "Show likes", + # initialize the button based on the likes value + select: dynamic([post: p], fragment("? > 0", p.likes)), + }, + likes: %{ + module: Backpex.Fields.Number, + label: "Likes", + # display the field based on the `show_likes` value + # the value can be part of the changeset or item (when edit view is opened initially). + visible: fn + %{live_action: :new} = assigns -> + Map.get(assigns.changeset.changes, :show_likes) + + %{live_action: :edit} = assigns -> + Map.get(assigns.changeset.changes, :show_likes, Map.get(assigns.item, :show_likes, false)) + + _assigns -> + true + end + } +] +end +``` diff --git a/guides/fields/what-is-a-field.md b/guides/fields/what-is-a-field.md new file mode 100644 index 00000000..6bc9a95c --- /dev/null +++ b/guides/fields/what-is-a-field.md @@ -0,0 +1,76 @@ +# What is a Field? + +Backpex fields are the building blocks of a resource. They define the data that will be displayed and manipulated in the resource views. Fields can be of different types, such as text, number, date, and select. Each field type has its own configuration options and behavior. Typically, you want to configure a field for each type of data you want to display in your resource. + +Backpex ships with a set of built-in field types, but you can also create custom fields to fit your specific needs. + +## Built-in Field Types + +Backpex provides the following built-in field types: + +- `Backpex.Fields.BelongsTo` +- `Backpex.Fields.Boolean` +- `Backpex.Fields.Currency` +- `Backpex.Fields.DateTime` +- `Backpex.Fields.Date` +- `Backpex.Fields.HasManyThrough` +- `Backpex.Fields.HasMany` +- `Backpex.Fields.InlineCRUD` +- `Backpex.Fields.ManyToMany` +- `Backpex.Fields.MultiSelect` +- `Backpex.Fields.Number` +- `Backpex.Fields.Select` +- `Backpex.Fields.Text` +- `Backpex.Fields.Textarea` +- `Backpex.Fields.Upload` +- `Backpex.Fields.URL` + +You can click on each field type to see its documentation and configuration options. + +## Configuration + +To define fields for a resource, you need to implement the [`fields/0`](Backpex.LiveResource.html#c:fields/0) callback in your resource module. This function must return a list of field configurations. + +```elixir +@impl Backpex.LiveResource +def fields do + [ + username: %{ + module: Backpex.Fields.Text, + label: "Username" + }, + email: %{ + module: Backpex.Fields.Email, + label: "Email" + } + ] +end +``` + +The example above will define two fields: `username` and `email`. Both fields use the built-in field types `Backpex.Fields.Text` and `Backpex.Fields.Email`, respectively. + +## Field Configuration + +Each field configuration must contain the following keys: + +- `module`: The module that implements the field behavior. +- `label`: The label that will be displayed for the field. + +In addition to these keys, you can configure each field with additional options specific to the field type. For example, a text field can have a `placeholder` option to set a placeholder text for the input field. + +```elixir +@impl Backpex.LiveResource +def fields do + [ + username: %{ + module: Backpex.Fields.Text, + label: "Username", + placeholder: "Enter your username" + } + ] +end +``` + +The example above will set the placeholder `"Enter your username"` for the `username` field. + +The following sections will cover general field options and how to create custom fields. diff --git a/guides/filter/custom-filter.md b/guides/filter/custom-filter.md new file mode 100644 index 00000000..815ff27d --- /dev/null +++ b/guides/filter/custom-filter.md @@ -0,0 +1,67 @@ +# Custom Filter + +Backpex ships with a set of default filters that can be used to filter the data. In addition to the default filters, you can create custom filters for more advanced use cases. + +## Creating a Custom Filter + +You can create a custom filter by using the `filter` macro from the `BackpexWeb` module.. It automatically implements the `Backpex.Filter` behavior and defines some aliases and imports. + +When creating a custom filter, you need to implement the following callbacks: `query/3`, `render/1` and `render_form/1`. The `query/3` function is used to filter the data based on the filter values. It receives the query, the attribute and the values of the filter and should return the filtered query. The `render/1` function returns the markup that is used to display the filter on the index view. The `render_form/1` function returns the markup that is used to render the filter form on the index view. + +Here is an example of a custom select filter: + +```elixir +defmodule MyApp.Filters.CustomSelectFilter do + use BackpexWeb, :filter + + @impl Backpex.Filter + def label, do: "Event status" + + @impl Backpex.Filter + def render(assigns) do + assigns = assign(assigns, :label, option_value_to_label(options(), assigns.value)) + + ~H""" + <%= @label %> + """ + end + + @impl Backpex.Filter + def render_form(assigns) do + ~H""" + <.form_field + type="select" + selected={selected(@value)} + options={my_options()} + form={@form} + field={@field} + label="" + /> + """ + end + + @impl Backpex.Filter + def query(query, attribute, value) do + where(query, [x], field(x, ^attribute) == ^value) + end + + defp option_value_to_label(options, value) do + Enum.find_value(options, fn {option_label, option_value} -> + if option_value == value, do: option_label + end) + end + + defp my_options, do: [ + {"Select an option...", nil}, + {"Open", :open}, + {"Close", :close}, + ] + + defp selected(""), do: nil + defp selected(value), do: value +end +``` + +In this example, we define a custom select filter that filters the data based on the event status. The `query/3` function filters the data based on the selected value. + +See `Backpex.Filter` for available callback functions. diff --git a/guides/filter/filter-presets.md b/guides/filter/filter-presets.md new file mode 100644 index 00000000..ea089f56 --- /dev/null +++ b/guides/filter/filter-presets.md @@ -0,0 +1,44 @@ +# Filter Presets + +Backpex allows you to define filter presets for your filters. Filter presets are used to define a set of filter configurations that can easily be applied to the data being displayed in the index view. Filter Presets consist of a name and a list of values that are used to filter the data. For example, you can define a filter preset for a date filter that filters the data based on the current month. Then the user can easily apply this filter by selecting the preset from the filter dropdown. + +## Defining a Filter Preset + +To define presets for your filters, you need to add a list of maps under the key of `:presets` to your filter in your LiveResource. + +Each of those maps has two keys: +1. `:label` – the name of the preset shown to the user +2. `:values` – a function with arity 0 that returns the values corresponding to your used filter + +See the example below for some preset examples. We add a preset for a date filter that filters the data based on the last 7 days and a preset for a select filter that filters the data based on the published status of an event. + +```elixir +@impl Backpex.LiveResource +def filters, do: [ + begins_at: %{ + module: MyAppWeb.Filters.DateRange, + label: "Begins At", + presets: [ + %{ + label: "Last 7 Days", + values: fn -> %{ + "start" => Date.add(Date.utc_today(), -7), + "end" => Date.utc_today() + } end + } + }, + published: %{ + module: MyAppWeb.Filters.EventPublished, + presets: [ + %{ + label: "Both", + values: fn -> [:published, :not_published] end + }, + %{ + label: "Only published", + values: fn -> [:published] end + } + ] + } +] +``` \ No newline at end of file diff --git a/guides/filter/how-to-add-a-filter.md b/guides/filter/how-to-add-a-filter.md new file mode 100644 index 00000000..eb3d1a79 --- /dev/null +++ b/guides/filter/how-to-add-a-filter.md @@ -0,0 +1,74 @@ +# How to add a Filter? + +Adding a filter to your *LiveResource* is a two step process: + +## Defining a Filter module + +First, you need to define a filter module that implements one of the behaviors from the `Backpex.Filters` namespace., This may be one of the [built-in filters](what-is-a-filter.md#built-in-filters) or a [custom filter](custom-filter.md). + +We suggest to use a `MyAppWeb.Filters.` convention. + +If you want to add one of the built-in filters, you can click on the filter type in the list of [Built-in Filters](what-is-a-filter.md#built-in-filters) to see how to define a filter module for that filter type. + +For example, the following example shows how to define a filter module for a select filter that filters posts based on a category: + +```elixir +defmodule MyAppWeb.Filters.PostCategorySelect do + use Backpex.Filters.Select + + alias MyApp.Category + alias MyApp.Post + alias MyApp.Repo + + @impl Backpex.Filter + def label, do: "Category" + + @impl Backpex.Filters.Select + def prompt, do: "Select category ..." + + @impl Backpex.Filters.Select + def options do + query = + from p in Post, + join: c in Category, + on: p.category_id == c.id, + distinct: c.name, + select: {c.name, c.id} + + Repo.all(query) + end +end +``` + +## Adding the Filter to your LiveResource + +After you have defined the filter module, you need to add the filter to your *LiveResource*. + +To do this, you need to define the filter in the [filters/0](Backpex.LiveResource.html#c:filters/0) callback in your *LiveResource* module. + +Here is an example of how to add a filter to your *LiveResource*: + +```elixir +@impl Backpex.LiveResource +def filters, do: [ + category_id: %{ + module: MyAppWeb.Filters.PostCategorySelect, + } +] +``` + +In this example, we add a filter with the name `category_id` to the *LiveResource*. The filter uses the `MyAppWeb.Filters.PostCategorySelect` module we defined earlier. + +## Overwriting the Filter Label + +You can also overwrite the filter label defined in the filter label by adding a `label` key to the filter map: + +```elixir +@impl Backpex.LiveResource +def filters, do: [ + category_id: %{ + module: MyAppWeb.Filters.PostCategorySelect, + label: "Category" + } +] +``` diff --git a/guides/filter/visibility-and-authorization.md b/guides/filter/visibility-and-authorization.md new file mode 100644 index 00000000..6e6f4453 --- /dev/null +++ b/guides/filter/visibility-and-authorization.md @@ -0,0 +1,21 @@ +# Visibility and Authorization + +You can control whether a filter is visible or not by implementing the [can?/1](Backpex.Filter.html#c:can?/1) callback in your filter module. + +## Configuration + +The [can?/1](Backpex.Filter.html#c:can?/1) callback receives the assigns and has to return a boolean value. If the callback returns `true`, the filter will be visible. If it returns `false`, the filter will be hidden. If you don't implement the `can?/1` callback, the filter will be visible by default. + +Here is an example of how to hide a filter based on the user's role: + +```elixir +defmodule MyAppWeb.Filters.MyFilter do + use BackpexWeb, :filter + + @impl Backpex.Filter + def can?(assigns), do: assigns.current_user.role == :admin +end +``` + +In this example, the `MyFilter` filter will only be visible if the user's role is `admin`. + diff --git a/guides/filter/what-is-a-filter.md b/guides/filter/what-is-a-filter.md new file mode 100644 index 00000000..bdcec732 --- /dev/null +++ b/guides/filter/what-is-a-filter.md @@ -0,0 +1,20 @@ +# What is a Filter? + +Filters are used to filter the data that is being displayed in the (index) view. They are used to narrow down the data that is being displayed based on certain criteria. + +Backpex allows you to define filters for your *LiveResources*. Backpex handles the filtering of the data for you as well as the UI for the filters. You just need to define the filters and Backpex will take care of the rest. + +Backpex ships with a set of default filters that can be used to filter the data. In addition to the default filters, you can create custom filters for more advanced use cases. + +## Built-in Filters + +Backpex provides the following built-in filters: + +- `Backpex.Filters.Boolean` +- `Backpex.Filters.Range` +- `Backpex.Filters.Select` +- `Backpex.Filters.MultiSelect` + +You can click on each filter type to see its documentation and configuration options. + +We will go through how to define filters for a *LiveResource* in [the next section](how-to-add-a-filter.md). diff --git a/guides/get_started/installation.md b/guides/get_started/installation.md new file mode 100644 index 00000000..47e85a2f --- /dev/null +++ b/guides/get_started/installation.md @@ -0,0 +1,262 @@ +# Installation + +The following guide will help you to install Backpex in your Phoenix application. We will guide you through the installation process and show you how to create a simple resource. + +## Add to list of dependencies + +In your `mix.exs`: + +```elixir +defp deps do + [ + ... + {:backpex, "~> 0.3.0"} + ] +end +``` + +See the [hex.pm page](https://hex.pm/packages/backpex) for the latest version. + +## Add files to Tailwind content + +Backpex uses Tailwind CSS and daisyUI. Make sure to add the Backpex files to your tailwind content in order to include the Backpex styles. + +In your `tailwind.config.js`: + +```js +.., +content: [ + ..., + // add this line + 'deps/backpex/**/*.*ex' +] +``` + +> #### Info {: .info} +> +> The path to the Backpex files may vary depending on your project setup. + +## Setup formatter + +Backpex ships with a formatter configuration. To use it, add Backpex to the list of dependencies in your `.formatter.exs`. + +```elixir +# my_app/.formatter.exs +[ + import_deps: [:backpex] +] +``` + +## Create an example resource + +To make it more practical, we are going to create a simple resource that we will use in all our examples later in the installation guide. You can skip this step if you want to use your own resource or just follow the guide. + +The example resource will be a `Post` resource with the following fields: + +- `title` (string) +- `views` (integer) + +Run the following commands: + +```bash +mix phx.gen.schema Blog.Post blog_posts title:string views:integer +mix ecto.migrate +``` + +These commands will generate a `Post` schema and a migration file. The migration file will create a `blog_posts` table in your database. + +You are now prepared to set up the Backpex layout and a LiveResource for the `Post` resource. + +## Create layout + +Backpex does not ship with a predefined layout by default to give you the freedom to create your own layout. Instead, it provides components that you can use to build your own layout. You can find all Backpex components in the `lib/backpex/components` directory. Layout components are placed in the `lib/backpex/components/layout` directory. To start quickly, Backpex provides an `Backpex.HTML.Layout.app_shell/1` component. You can use this component to add an app shell layout to your application easily. + +See the following example that uses the `Backpex.HTML.Layout.app_shell/1` component and some other Backpex Layout components to create a simple layout: + +```elixir + + <:topbar> + + + + <:label> + + +
  • + <.link navigate={~p"/"} class="flex justify-between text-red-600 hover:bg-gray-100"> +

    Logout

    + <.icon name="hero-arrow-right-on-rectangle" class="h-5 w-5" /> + +
    • +     + + <:sidebar> + + <.icon name="hero-book-open" class="h-5 w-5" /> Posts + + + + <%= @inner_content %> +     +``` + +Make sure to add the `Backpex.HTML.Layout.flash_messages` component to display flash messages in your layout and do not forget to add the `@inner_content` variable to render the content of the LiveView. + +Place the layout file in your `lib/myapp_web/templates/layout` directory. You can name it like you want, but we recommend to use `admin.html.heex`. You can also use this layout as the only layout in your application if your application consists of only an admin interface. + +We use the `icon/1` component to render icons in the layout. This component is part of the `core_components` module that ships with new Phoenix projects. See [`core_components.ex`](https://github.com/phoenixframework/phoenix/blob/main/priv/templates/phx.gen.live/core_components.ex). Feel free to use your own icon component or library. + +> #### Information {: .info} +> +> The `Backpex.HTML.Layout.app_shell/1` component accepts a boolean `fluid` to determine if a `LiveResource` should be rendered full width. There is a `fluid?` option you can configure in a `LiveResource`. See the [Fluid Layout documentation](live_resource/fluid-layout.md) for more information. + +## Configure LiveResource + +To create a LiveResource for the `Post` resource, you need to create LiveResource module. + +```elixir +defmodule MyAppWeb.Live.PostLive do + use Backpex.LiveResource, + layout: {MyAppWeb.Layouts, :admin}, + schema: MyApp.Blog.Post, + repo: MyApp.Repo, + update_changeset: &MyApp.Blog.Post.update_changeset/3, + create_changeset: &MyApp.Blog.Post.create_changeset/3, + pubsub: MyApp.PubSub, + topic: "posts", + event_prefix: "post_", +end +``` + +`Backpex.LiveResource` is the module that will generate the corresponding LiveViews for the resource you configured. We provide a macro you have to use to configure the LiveResource. You are required to set some general options to tell Backpex where to find the resource and what changesets should be used. The above example shows the configuration for a `Post` resource. + +All options you can see in the above example are required: + +- The `layout` option tells Backpex which layout to use for the LiveResource. In this case, we use the `:admin`(`admin.html.heex`) layout created in the previous step. +- The `schema` option tells Backpex which schema to use for the resource. +- The `repo` option tells Backpex which repo to use for the resource. +- The `update_changeset` and `create_changeset` options tell Backpex which changesets to use for updating and creating the resource. +- The `pubsub` option tells Backpex which pubsub to use for the resource (see the [Listen to PubSub Events](live_resource/listen-to-pubsub-events.md) guide for more information). +- The `topic` option tells Backpex which topic to use for the resource when broadcasting events. +- The `event_prefix` option tells Backpex which event prefix to use for the resource when broadcasting events. + +In addition to the required options, you pass to the `Backpex.LiveResource` macro, you are required to implement the following callback functions in the module: + +- [`singular_name/0`](Backpex.LiveResource.html#c:singular_name/0) - This function should return the singular name of the resource. +- [`plural_name/0`](Backpex.LiveResource.html#c:plural_name/0) - This function should return the plural name of the resource. +- [`fields/0`](Backpex.LiveResource.html#c:fields/0) - This function should return a list of fields to display in the LiveResource. + +After implementing the required callback functions, our `PostLive` module looks like this: + +```elixir +defmodule MyAppWeb.Live.PostLive do + use Backpex.LiveResource, + layout: {MyAppWeb.Layouts, :admin}, + schema: MyApp.Blog.Post, + repo: MyApp.Repo, + update_changeset: &MyApp.Blog.Post.update_changeset/3, + create_changeset: &MyApp.Blog.Post.create_changeset/3, + pubsub: MyApp.PubSub, + topic: "posts", + event_prefix: "post_", + + @impl Backpex.LiveResource + def singular_name, do: "Post" + + @impl Backpex.LiveResource + def plural_name, do: "Posts" + + @impl Backpex.LiveResource + def fields do + [ + title: %{ + module: Backpex.Fields.Text, + label: "Title" + }, + views: %{ + module: Backpex.Fields.Number, + label: "First Name" + } + ] +end +``` + +The `fields/0` function returns a list of fields to display in the LiveResource. See [What is a Field?](fields/what-is-a-field.md) for more information. + +> #### Information {: .info} +> +> We recommend placing the *LiveResource* in the `lib/myapp_web/live` directory. You can name the module like you want, but in this case, we recommend using `post_live.ex`. + +## Configure Routing + +To make the LiveResource accessible in your application, you first need to configure your router (`router.ex`). + +### Add Backpex Routes + +Backpex needs to add a `backpex_cookies` route to your router. This route is used to set the cookies needed for the Backpex LiveResource. + +Backpex provides a macro you can use to add the required routes to your router. Make sure to import `Backpex.Router` at the top of your router file or prefix the function calls.# + +You have to do this step only once in your router file, so if you already added the [`backpex_routes/0`](Backpex.Router.html#backpex_routes/0) macro, you can skip this step. + +```elixir +# router.ex + +import Backpex.Router + +scope "/admin", DemoWeb do + pipe_through :browser + + # add this line + backpex_routes() +end +``` + +It does not matter where you place the [`backpex_routes/0`](Backpex.Router.html#backpex_routes/0) macro in your router file. You can insert it in every scope you want to, but we recommend placing it in the scope you want to use backpex in, e.g. `/admin`. + +## Add Init Assigns and LiveSession + +Backpex provides a `Backpex.InitAssigns` module. This will attach the `current_url` to the LiveView. Backpex needs it to highlight the current sidebar item in the layout. You can also use your own init assigns module if you want to attach more assigns to the LiveView, but make sure to add the `current_url` to the assigns. + +We use a live session to add the init assigns to all LiveViews in the `/admin` scope. + +```elixir +# router.ex + +import Backpex.Router + +scope "/admin", DemoWeb do + pipe_through :browser + + backpex_routes() + + # add this line + live_session :default, on_mount: Backpex.InitAssigns do + end +end +``` + +### Add LiveResource routes + +To make the LiveResource accessible in your application, you need to add routes for it. Backpex makes it easy to add the required routes to your router by providing the [`live_resources/3`](Backpex.Router.html#live_resources/3) macro. + +```elixir +# router.ex + +import Backpex.Router + +scope "/admin", DemoWeb do + pipe_through :browser + + backpex_routes() + + live_session :default, on_mount: Backpex.InitAssigns do + # add this line + live_resources "/posts", PostLive + end +end +``` + +This macro will add the required routes for the `PostLive` module. You can now access the `PostLive` LiveResource at `/admin/posts`. diff --git a/guides/get_started/prerequisites.md b/guides/get_started/prerequisites.md new file mode 100644 index 00000000..6aa619c4 --- /dev/null +++ b/guides/get_started/prerequisites.md @@ -0,0 +1,29 @@ +# Prerequisites + +Backpex integrates seamlessly with your existing Phoenix LiveView application, but there are a few prerequisites you need to meet before you can start using it. + +## Phoenix LiveView + +Backpex is built on top of Phoenix LiveView, so you need to have Phoenix LiveView installed in your application. If you generate a new Phoenix application using the latest version of the `mix phx.new` generator, Phoenix LiveView is included by default. + +## Tailwind CSS + +Backpex uses Tailwind CSS for styling. Make sure you have Tailwind CSS installed in your application. You can install Tailwind CSS by following the [official installation guide](https://tailwindcss.com/docs/installation). If you generate a new Phoenix application using the latest version of the `mix phx.new` generator, Tailwind CSS is included by default. + +## daisyUI + +Backpex is styled using daisyUI. Make sure you have daisyUI installed in your application. You can install daisyUI by following the [official installation guide](https://daisyui.com/docs/install/). + +> #### Warning {: .warning} +> +> Backpex currently only supports daisyUI light mode. Help us to support dark mode by contributing to the project. + +## Ecto + +Backpex currently depends on Ecto as the database layer. Make sure you have a running Ecto repository in your application. + +> #### Warning {: .warning} +> +> Backpex currently only supports UUID (binary_id) primary keys. Help us to support other primary key types by contributing to the project. + +If you meet all these prerequisites, you are ready to install and configure Backpex in your Phoenix application. See our [installation guide](guides/get_started/installation.md) for more information on how to install and configure Backpex. \ No newline at end of file diff --git a/guides/introduction/installation.md b/guides/introduction/installation.md deleted file mode 100644 index efe6dbb3..00000000 --- a/guides/introduction/installation.md +++ /dev/null @@ -1,92 +0,0 @@ -# Installation - -## Prerequisites - -Make sure you have a running phoenix application with [Tailwind CSS](https://tailwindcss.com/) and [daisyUI](https://daisyui.com/docs/install/) installed. - -> #### Important {: .info} -> -> Backpex currently only supports daisyUI light mode. - -Backpex currently depends on [Ecto](https://hexdocs.pm/ecto/Ecto.html). Therefore there has to be a running -ecto repository. - -## Add Backpex to list of dependencies - -In your `mix.exs`: - -```elixir -defp deps do - [ - ... - {:backpex, path: "backpex_path"} - ] -end -``` - -## Add Backpex files to tailwind content - -In your `tailwind.config.js`: - -```js -content: ['./path_to_deps/backpex/**/*.*ex'] -``` - -## Setup formatter - -We recommend to add Backpex to the list of dependencies in your `.formatter.exs`. - -```elixir -# my_app/.formatter.exs -[ - import_deps: [:backpex] -] -``` - -## Create layout - -Backpex does not ship a predefined layout by default. Instead it exposes components you -may use to build your own layout. You could also partly use Backpex components. For example -you are able to define your own sidebar navigation in our app shell component. - -Place the layout file in your `lib/myapp_web/templates/layout` directory. - -You can find all Backpex components in the `lib/backpex/components` directory. - -If you do not want to put effort into creating your own layout, feel free to use this layout (`admin.html.heex`) as a starting point: - -> The `Backpex.HTML.Layout.app_shell` component accepts a boolean `fluid` to determine if a `LiveResource` should be rendered full width. Our default is the definition of the `fluid?` option in a `LiveResource`, but feel free to change this behavior in your layout. - -```elixir - - <:topbar> - - - <:label> - - -
    - <.link navigate="/" class="my-1 flex justify-between px-4 py-2 text-sm text-red-600 hover:bg-gray-100"> -

    Logout

    - - -
    -     - - <:sidebar> - - Your Resource - - - <:label>Your Sidebar Section - - Your nested Resource - - - - - <%= @inner_content %> -     -``` - -You can now create and configure the corresponding resources. diff --git a/guides/live_resource/additional-classes-for-index-table-rows.md b/guides/live_resource/additional-classes-for-index-table-rows.md new file mode 100644 index 00000000..128a59dd --- /dev/null +++ b/guides/live_resource/additional-classes-for-index-table-rows.md @@ -0,0 +1,20 @@ +# Additional classes for index table rows + +You can add additional classes to table rows on the index view. This allows you, for example, to color the rows. + +## Configuration + +To add additional classes to table rows on the index view, you need to implement the [index_row_class/4](Backpex.LiveResource.html#c:index_row_class/4) callback in your resource configuration file. + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def index_row_class(assigns, item, selected, index), do: "bg-yellow-100" +``` + +The example above will add the `bg-yellow-100` class to all table rows on the index view. + +> #### Info {: .warning} +> +> Note that we call the function twice. Once for the row on the `tr` element and a second time for the item action overlay, because in most cases the overlay should have the same style applied. diff --git a/guides/live_resource/fluid-layout.md b/guides/live_resource/fluid-layout.md new file mode 100644 index 00000000..a54c7670 --- /dev/null +++ b/guides/live_resource/fluid-layout.md @@ -0,0 +1,18 @@ +# Fluid Layout + +Backpex provides a way to create a fluid layout. A fluid layout is a layout that fills the entire width of the screen. This layout is useful for applications that need to display a lot of content on the screen. + +> #### Information {: .info} +> +> The `fluid?` options requires you to pass the `fluid?` assign to the `Backpex.HTML.Layout.app_shell/1` component in your layout file. See the [Create layout](get_started/installation.md#create-layout) documentation for more information. + +## Configure LiveResource + +To create a fluid layout, you need to set the `fluid?` option in a `LiveResource` to `true`. + +```elixir +# in your LiveResource module +defmodule MyAppWeb.Live.UserLive do + use Backpex.LiveResource, fluid?: true +end +``` \ No newline at end of file diff --git a/guides/live_resource/hooks.md b/guides/live_resource/hooks.md new file mode 100644 index 00000000..dbb8525f --- /dev/null +++ b/guides/live_resource/hooks.md @@ -0,0 +1,23 @@ +# Hooks + +You may define hooks that are called before their respective action. Those hooks are `on_item_created`, `on_item_updated` and `on_item_deleted`. + +> #### Info {: .info} +> +> Note that the hooks are called after the changes have been persisted to the database. + +## Configuration + +To add a hook to a resource, you need to implement the [on_item_created/2](Backpex.LiveResource.html#c:on_item_created/2), [on_item_updated/2](Backpex.LiveResource.html#c:on_item_updated/2) or [on_item_deleted/2](Backpex.LiveResource.html#c:on_item_deleted/2) callback in your resource configuration file. + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def on_item_created(socket, item) do + # do something + socket +end +``` + +The example above will call the `on_item_created` hook after an item has been created. diff --git a/guides/live_resource/item-query.md b/guides/live_resource/item-query.md new file mode 100644 index 00000000..d729ff14 --- /dev/null +++ b/guides/live_resource/item-query.md @@ -0,0 +1,24 @@ +# Item Query + +It is possible to manipulate the query when fetching resources for `index`, `show` and `edit` view. + +In all queries we define a `from` query with a named binding to fetch all existing resources on `index` view or a specific resource on `show` / `edit` view. +After that, we call the `item_query` function. By default it returns the incoming query. + +The `item_query` function makes it easy to add custom query expressions. + +## Configuration + +To add a custom query to a resource, you need to implement the [item_query/3](Backpex.LiveResource.html#c:item_query/3) callback in your resource configuration file: + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def item_query(query, :index, _assigns) do +query +|> where([post], post.published) +end +``` + +The example above will filter all posts by a published boolean on `index` view. We also made use of the named binding. It's always the name of the provided schema in `snake_case`. It is recommended to build your `item_query` on top of the incoming query. Otherwise you will likely get binding errors. \ No newline at end of file diff --git a/guides/live_resource/listen-to-pubsub-events.md b/guides/live_resource/listen-to-pubsub-events.md new file mode 100644 index 00000000..3fe91184 --- /dev/null +++ b/guides/live_resource/listen-to-pubsub-events.md @@ -0,0 +1,41 @@ +# Listen to PubSub Events + +As mentioned in the [installation guide](get_started/installation.md) you need to configure PubSub for your *LiveResources*. Backpex will use the configuration to publish `deleted`, `updated` and `created` events. Backpex will listen to these events and update the UI accordingly. Sometimes you may want to listen to these events and perform some custom actions. For example you want to show a toast to all users currently on the resource that a post has been created. + +### Configuration + +You can listen for Backpex PubSub events by implementing the Phoenix.LiveView [`handle_info/2`](Phoenix.LiveView.html#c:handle_info/2) callback in your *LiveResource* module. + +We assume you configured PubSub for your Posts *LiveResource* like this: + +```elixir +use Backpex.LiveResource, + ..., + pubsub: Demo.PubSub + topic: "posts", + event_prefix: "post_" +``` + +You could implement the following `handle_info/2` callbacks in your *LiveResource*: + +```elixir +# in your resource configuration file + +@impl Phoenix.LiveView +def handle_info({"post_created", item}, socket) do + # make something in response to the event + {:noreply, socket} +end + +@impl Phoenix.LiveView +def handle_info({"post_updated", item}, socket) do + # make something in response to the event + {:noreply, socket} +end + +@impl Phoenix.LiveView +def handle_info({"post_deleted", item}, socket) do + # make something in response to the event + {:noreply, socket} +end +``` diff --git a/guides/live_resource/navigation.md b/guides/live_resource/navigation.md new file mode 100644 index 00000000..9e6b0dd1 --- /dev/null +++ b/guides/live_resource/navigation.md @@ -0,0 +1,19 @@ +# Navigation + + +By default Backpex redirects to the index page after creating or updating an item. You can customize this behavior. + +## Configuration + +To define a custom navigation path, you need to implement the [return_to/4](Backpex.LiveResource.html#c:return_to/4) callback in your resource configuration file: + +```elixir +# in your resource configuration file + +@impl Backpex.LiveResource +def return_to(socket, assigns, live_action, item) do + ~p"/home" +end +``` + +The example above will redirect to the `/home` path after saving an item. diff --git a/guides/live_resource/ordering.md b/guides/live_resource/ordering.md new file mode 100644 index 00000000..df31b368 --- /dev/null +++ b/guides/live_resource/ordering.md @@ -0,0 +1,17 @@ +# Ordering + +You can configure the ordering of the resource index page. By default, the resources are ordered by the `id` field in ascending order. + +## Configuration + +To configure the ordering of the resource index page, you need to provide an `init_order` option in the resource configuration file: + +```elixir +# in your resource configuration file + +use Backpex.LiveResource, + ..., + init_order: %{by: :inserted_at, direction: :desc} +``` + +The example above will order the resources by the `inserted_at` field in descending order. diff --git a/guides/live_resource/panels.md b/guides/live_resource/panels.md new file mode 100644 index 00000000..d0d16d35 --- /dev/null +++ b/guides/live_resource/panels.md @@ -0,0 +1,43 @@ +# Panels + +You can define panels to group certain fields together. Panels are displayed in the provided order. + +## Configuration + +To add panels to a resource, you need to implement the [panels/0](Backpex.LiveResource.html#c:panels/0) callback in your resource configuration file. It has to return a keyword list with an identifier and label for each panel. + +```elixir + +# in your resource configuration file +@impl Backpex.LiveResource +def panels do + [ + contact: "Contact" + ] +end +``` + +The example above will define a panel with the identifier `contact` and the label `Contact`. + +## Usage + +You can move fields into panels with the `panel` field configuration that has to return the identifier of the corresponding panel. Fields without a panel are displayed in the `:default` panel. The `:default` panel has no label. + +```elixir +# in your fields list +@impl Backpex.LiveResource +def fields do + [ + %{ + ..., + panel: :contact + } + ] +end +``` + +The example above will move the field into the `contact` panel. + +> #### Info {: .info} +> +> Note that a panel is not displayed when there are no fields in it. diff --git a/guides/live_resource/templates.md b/guides/live_resource/templates.md new file mode 100644 index 00000000..7295a8f1 --- /dev/null +++ b/guides/live_resource/templates.md @@ -0,0 +1,17 @@ +# Templates + +You can customize certain template parts of Backpex. While you can only use our app shell layout, you can also define functions to provide additional templates to be rendered on the resource LiveView or completely overwrite certain parts like the header or main content. + +See [render_resource_slot/3](Backpex.LiveResource.html#c:render_resource_slot/3) for supported positions. + +## Configuration + +To add a custom template to a resource, you need to implement the [render_resource_slot/3](Backpex.LiveResource.html#c:render_resource_slot/3) callback in your resource configuration file. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def render_resource_slot(assigns, :index, :before_main), do: ~H"Hello World!" +``` + +The example above will render the string "Hello World!" before the main content of the index view. diff --git a/guides/live_resource/what-is-a-live-resource.md b/guides/live_resource/what-is-a-live-resource.md new file mode 100644 index 00000000..eb97ef0c --- /dev/null +++ b/guides/live_resource/what-is-a-live-resource.md @@ -0,0 +1,5 @@ +# What is a LiveResource? + +When refer to a *LiveResource* in Backpex, we are talking about a module that contains the configuration for a resource. This module is responsible for defining the resource's schema, the actions that can be performed on it, and the fields that will be rendered. + +In the documentation, we also talk about the resource configuration file. With this, we refer to the module that implements the `Backpex.LiveResource` behavior. This is a Backpex *LiveResource* module. diff --git a/guides/searching/basic-search.md b/guides/searching/basic-search.md new file mode 100644 index 00000000..dcf4c8ab --- /dev/null +++ b/guides/searching/basic-search.md @@ -0,0 +1,38 @@ +# Search + +Backpex provides a simple search feature that allows you to search for records in your resources. You can search for records based on the values of the fields in your resources. + +> #### Info {: .info} +> +> Note that fields are searched using a case-insensitive `ilike` query. + +## Configuration + +To enable searching, you need to flag the fields you want to search on as `searchable`. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def fields do +[ + %{ + ..., + searchable: true + } +] +end +``` + +A search input will appear automatically on the resource index view. + +## Custom Placeholder + +You can provide a custom placeholder for the search input by implementing the `search_placeholder/0` callback in your resource configuration file. + +```elixir +# in your resource configuration file +@impl Backpex.LiveResource +def search_placeholder, do: "This will be shown in the search input." +``` + +In addition to basic searching, Backpex allows you to perform full-text searches on resources (see [Full-Text Search Guide](full-text-search.md)). \ No newline at end of file diff --git a/guides/advanced/full_text_search.md b/guides/searching/full-text-search.md similarity index 67% rename from guides/advanced/full_text_search.md rename to guides/searching/full-text-search.md index a85e8523..6bcd8b2d 100644 --- a/guides/advanced/full_text_search.md +++ b/guides/searching/full-text-search.md @@ -1,6 +1,6 @@ # Full-Text Search -Backpex allows you to perform full-text searches on resources. It uses the built-in PostgreSQL full-text search functionality. +Backpex allows you to perform full-text searches on resources. It uses the built-in [PostgreSQL full-text search functionality](https://www.postgresql.org/docs/current/textsearch.html). ## Create a Generated Column @@ -20,18 +20,13 @@ ALTER TABLE film_reviews """) ``` -You can also concat multiple tsvectors in the generated column. This is useful if the table contains data in -different languages. We recommend that you specify the language when using the `to_tsvector` function. Otherwise -the default language will be used. +You can also concat multiple tsvectors in the generated column. This is useful if the table contains data in different languages. We recommend that you specify the language when using the `to_tsvector` function. Otherwise the default language will be used. ## Create an Index -To increase the speed of full-text searches, especially for resources with large amounts of data, you should create -an index on the generated column created in the previous step. +To increase the speed of full-text searches, especially for resources with large amounts of data, you should create an index on the generated column created in the previous step. -We strongly recommend that you use a GIN index, as it makes full-text searches really fast. -The disadvantage is that a GIN index takes up a lot of disk space, so if you are limited in disk space, -feel free to use a GiST index instead. +We strongly recommend that you use a GIN index, as it makes full-text searches really fast. The disadvantage is that a GIN index takes up a lot of disk space, so if you are limited in disk space, feel free to use a GiST index instead. ```elixir # in the database up migration @@ -40,10 +35,6 @@ execute(""" CREATE INDEX film_reviews_search_idx ON film_reviews USING GIN(generated_tsvector); """) ``` - -> #### Important {: .info} -> -> Note that you must explicitly define up and down migrations. Otherwise, the index cannot be dropped. ```elixir # in the database down migration @@ -55,8 +46,11 @@ DROP INDEX film_reviews_search_idx; drop table(:film_reviews) ``` -To enable full-text search, you need to specify the name of the generated column in the live resource of the -corresponding resource. +> #### Important {: .info} +> +> Note that you must explicitly define up and down migrations. Otherwise, the index cannot be dropped. + +To enable full-text search, you need to specify the name of the generated column in the live resource of the corresponding resource: ```elixir # in the live resource @@ -64,3 +58,5 @@ corresponding resource. use Backpex.LiveResource, full_text_search: :generated_tsvector ``` + +You can now perform full-text searches on the resource index view. \ No newline at end of file diff --git a/guides/introduction/translations.md b/guides/translations/translations.md similarity index 79% rename from guides/introduction/translations.md rename to guides/translations/translations.md index 19f6cca4..bef9d05c 100644 --- a/guides/introduction/translations.md +++ b/guides/translations/translations.md @@ -1,6 +1,10 @@ # Translations -You may configure translator functions in your application config: +You are able to translate all strings used by Backpex. This includes general strings like "New", "Edit", "Delete", etc., as well as error messages. + +## Configuration + +In order to translate strings, you need to configure two translator functions in your application config: ```elixir config :backpex, :translator_function, {MyAppWeb.Helpers, :translate_backpex} @@ -8,16 +12,13 @@ config :backpex, :translator_function, {MyAppWeb.Helpers, :translate_backpex} config :backpex, :error_translator_function, {MyAppWeb.ErrorHelpers, :translate_error} ``` -The first one is being used to translate general strings. The second one is being used to translate -(changeset) errors. +The first one is being used to translate general strings. The second one is being used to translate (changeset) errors. ## Using Gettext -If you want to use Gettext, the translator functions should look like this: +We recommend using Gettext for translations. If you want to use it, the translator functions should look like this: ```elixir -# MyAppWeb.Helpers - def translate_backpex({msg, opts}) do if count = opts[:count] do Gettext.dngettext(MyAppWeb.Gettext, "backpex", msg, msg, count, opts) @@ -26,8 +27,6 @@ def translate_backpex({msg, opts}) do end end -# MyAppWeb.ErrorHelpers - def translate_error({msg, opts}) do if count = opts[:count] do Gettext.dngettext(DemoWeb.Gettext, "errors", msg, msg, count, opts) @@ -37,9 +36,11 @@ def translate_error({msg, opts}) do end ``` -Store this example template as `priv/gettext/backpex.pot`. It contains all translations used by Backpex. +You can place the functions in a module of your choice. In this example, we use `MyAppWeb.Helpers` and `MyAppWeb.ErrorHelpers`. Don't forget to use the correct module in your config as well. -``` +In addition, you need to create a Gettext template file in your application. You may use the following template. It contains all translations used by Backpex. + +```po ## This file is a PO Template file. msgid "" msgstr "" diff --git a/lib/backpex/field.ex b/lib/backpex/field.ex index b28cce5c..e2d317f4 100644 --- a/lib/backpex/field.ex +++ b/lib/backpex/field.ex @@ -3,45 +3,7 @@ defmodule Backpex.Field do @moduledoc ~S''' Behaviour implemented by all fields. - A field defines how a column is rendered on index, show and edit views. In the resource configuration file you can configure - a list of fields. You may create your own field by implementing this behaviour. A field has to be a [LiveComponent](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveComponent.html). - - When creating your own field, you can use the `field` macro from the `BackpexWeb` module. It automatically implements the `Backpex.Field` behaviour - and defines some aliases and imports. - - The simplest version of a custom field would look like this: - - use BackpexWeb, :field - - @impl Backpex.Field - def render_value(assigns) do - ~H""" -

    - <%= HTML.pretty_value(@value) %> -

    - """ - end - - @impl Backpex.Field - def render_form(assigns) do - ~H""" -
    - - <:label> - - - - -
    - """ - end - - The `render_value/1` function returns markup that is used to display a value on `index` and `show` views. - The `render_form/1` function returns markup that is used to render a form on `edit` and `new` views. - - The list of fields in the resource configuration has to be a keyword list. The key has to be the name of the column. - The value has to be a list of options represented as a map. At least you are required to provide the module of the field and a label as options. - For extra information and options you may have to look into the corresponding field documentation. + A field defines how a column is rendered on index, show and edit views. In the resource configuration file you can configure a list of fields. You may create your own field by implementing this behaviour. A field has to be a [LiveComponent](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveComponent.html). ### Example @@ -53,143 +15,6 @@ defmodule Backpex.Field do } ] end - - ## Read-only fields - - Fields can be configured to be read-only. In edit view, these fields are rendered with the additional HTML attributes `readonly` and `disabled`, - ensuring that the user cannot interact with the field or change its value. - - In index view, if read-only and index editable are set to `true`, forms will be rendered with the `readonly` HTML attribute. - - Currently read-only configuration is possible for `Backpex.Fields.Text` and `Backpex.Fields.Textarea` on edit view. - - On the index view, read-only is supported for all fields with the index editable option. - - You can also add read-only functionality to a custom field. To do this, you need to define a `render_form_readonly/1` function. - This function must return markup to be used when read-only is enabled. - - @impl Backpex.Field - def render_form_readonly(assigns) do - ~H""" -
    - - <:label> - - - - -
    - """ - end - - When defining a custom field with index editable support, you need to handle the read-only state in the index editable markup. - We pass a `readonly` value to index fields, which will be `true` or `false` depending on the read-only option of the field and the `can?/3` function. - - Fields can be set to read-only in the configuration map of the field by adding the `readonly` option. This key must - contain either a boolean value or a function that returns a boolean value. - - The function takes `assigns` as a parameter. This allows the field to be set as read-only programmatically, as the - following example illustrates: - - rating: %{ - module: Backpex.Fields.Text, - label: "Rating", - readonly: fn assigns -> - assigns.current_user.role in [:employee] - end - } - - ## Custom Alias Configuration - - Backpex automatically generates aliases for queries in your fields. However, if you try to add two `BelongsTo` fields of the same association, you will encounter an error indicating that the alias is already in use by another field. To resolve this issue, Backpex allows the assignment of custom aliases to fields, eliminating naming conflicts in queries. - - To use a custom alias, especially with a `:select` query, define it within your field configuration. This allows you to reference associated data via the custom alias. - - Example usage of a custom alias together with a `:select`: - - second_category: %{ - module: Backpex.Fields.BelongsTo, - label: "Second Category", - display_field: :name, - searchable: true, - custom_alias: :second_category, - select: dynamic([second_category: sc], sc.name) - }, - - ## Computed Fields - - Sometimes you want to compute new fields based on existing fields. - - Imagine there is a user table with `first_name` and `last_name`. Now, on your index view you want to add a column to display - the `full_name`. You could create a generated column in you database, but there are several reasons for not adding generated - columns for all computed fields you want to display in your application. - - Backpex adds a way to support this. - - There is a `select` option you may add to a field. This option has to return a `dynamic`. This query will then be executed to - select fields when listing your resources. In addition this query will also be used to order / search this field. - - Therefore you can display the `full_name` of your users by adding the following field to the resource configuration file. - - full_name: %{ - module: Backpex.Fields.Text, - label: "Full Name", - searchable: true, - except: [:edit], - select: dynamic([user: u], fragment("concat(?, ' ', ?)", u.first_name, u.last_name)) - } - - We are using a database fragment to build the `full_name` based on the `first_name` and `last_name` of an user. Backpex will select this field when listing resources automatically. - Ordering and searching works the same like on all other fields, because Backpex uses the query you provided in the `dynamic` in order / search queries, too. - - We recommend to display this field on `index` and `show` view only. - - > Note: You are required to add a virtual field `full_name` to your user schema. Otherwise, Backpex is not able to select this field. - - Computed fields also work in associations. - - For example, you are able to add a `select` query to a `BelongsTo` field. - - Imagine you want to display a list of posts with the corresponding authors (users). The user column should be a `full_name` computed by the `first_name` and `last_name`: - - user: %{ - module: Backpex.Fields.BelongsTo, - label: "Full Name", - display_field: :full_name, - select: dynamic([user: u], fragment("concat(?, ' ', ?)", u.first_name, u.last_name)), - options_query: fn query, _assigns -> - query |> select_merge([user], %{full_name: fragment("concat(?, ' ', ?)", user.first_name, user.last_name)}) - end - } - - We recommend to add a `select_merge` to the `options_query` where you select the same field. Otherwise, displaying the same values in the select form on edit page will not work. - - Do not forget to add the virtual field `full_name` to your user schema in this example, too. - - ## Error Customisation - - Each field can define a `translate_error/1` function to use custom error messages. The function is called for each error and must return a tuple with a message and metadata. - - For example, if you want to indicate that an integer input must be a number: - - number: %{ - module: Backpex.Fields.Number, - label: "Number", - translate_error: fn - {_msg, [type: :integer, validation: :cast] = metadata} = _error -> - {"has to be a number", metadata} - - error -> - error - end - } ''' import Phoenix.Component, only: [assign: 3] diff --git a/lib/backpex/fields/upload.ex b/lib/backpex/fields/upload.ex index b4b4c723..e175c7ed 100644 --- a/lib/backpex/fields/upload.ex +++ b/lib/backpex/fields/upload.ex @@ -256,7 +256,7 @@ defmodule Backpex.Fields.Upload do def change do alter table(:products) do - dd(:images, {:array, :string}) + add(:images, {:array, :string}) end end end diff --git a/lib/backpex/filters/boolean.ex b/lib/backpex/filters/boolean.ex index d1fa6ac5..bc7a3dfa 100644 --- a/lib/backpex/filters/boolean.ex +++ b/lib/backpex/filters/boolean.ex @@ -1,13 +1,15 @@ defmodule Backpex.Filters.Boolean do @moduledoc """ - The Boolean Filter renders one checkbox per given option, hence multiple options can apply at the same time. + The boolean filter renders one checkbox per given option, hence multiple options can apply at the same time. Instead of implementing a `query` callback, you need to define predicates for each option leveraging [`Ecto.Query.dynamic/2`](https://hexdocs.pm/ecto/Ecto.Query.html#dynamic/2). - > Please note that only query elements will work as a predicate that also work in an [`Ecto.Query.where/3`](https://hexdocs.pm/ecto/Ecto.Query.html#where/3). + > #### Warning {: .warning} + > + > Note that only query elements will work as a predicate that also work in an [`Ecto.Query.where/3`](https://hexdocs.pm/ecto/Ecto.Query.html#where/3). If none is selected, the filter does not change the query. If multiple options are selected they are logically reduced via `orWhere`. - A really basic example is the following filter for a boolean column `:published`: + See the following example for an implementation of a boolean filter for a published field. defmodule MyAppWeb.Filters.EventPublished do use Backpex.Filters.Boolean diff --git a/lib/backpex/filters/filter.ex b/lib/backpex/filters/filter.ex index fc9f5b33..03517865 100644 --- a/lib/backpex/filters/filter.ex +++ b/lib/backpex/filters/filter.ex @@ -1,128 +1,8 @@ defmodule Backpex.Filter do - @moduledoc ~S''' + @moduledoc """ The base behaviour for all filters. Injects also basic layout, form and delete button for a filters rendering. + """ - Enabling filters on a resources index view is a two step process: - - 1. Add modules implementing one of the behaviors from the `Backpex.Filters` namespace to your project. - - We suggest to use a `MyAppWeb.Filters.` convention. - - We implemented the `__using__` macro for the filters, injecting code like imports (e.g. `Ecto.Query`) and functions (e.g. `render/1`) into your module. - 2. Implement the `filters/0` callback on your resource. - - The latter just returns a keyword list with the field names as keys and the filter module as values. - - # in your resource configuration file - @impl Backpex.LiveResource - def filters, do: [ - status: %{ - module: MyAppWeb.Filters.EventStatusSelect - }, - begins_at: %{ - module: MyAppWeb.Filters.DateRange - }, - published: %{ - module: MyAppWeb.Filters.EventPublished - } - ] - - ## Custom filters - - Instead of using the pre-defined filters you can also define custom filters by using `Backpex.Filter` and implementing at least `query/3`, `render/1` and `render_form/1`. - - For example purposes let's define a custom select filter: - - defmodule MyApp.Filters.CustomSelectFilter do - use BackpexWeb, :filter - - @impl Backpex.Filter - def label, do: "Event status" - - @impl Backpex.Filter - def render(assigns) do - assigns = assign(assigns, :label, option_value_to_label(options(), assigns.value)) - - ~H""" - <%= @label %> - """ - end - - @impl Backpex.Filter - def render_form(assigns) do - ~H""" - <.form_field - type="select" - selected={selected(@value)} - options={my_options()} - form={@form} - field={@field} - label="" - /> - """ - end - - @impl Backpex.Filter - def query(query, attribute, value) do - where(query, [x], field(x, ^attribute) == ^value) - end - - defp option_value_to_label(options, value) do - Enum.find_value(options, fn {option_label, option_value} -> - if option_value == value, do: option_label - end) - end - - defp my_options, do: [ - {"Select an option...", nil}, - {"Open", :open}, - {"Close", :close}, - ] - - defp selected(""), do: nil - defp selected(value), do: value - end - - ## Filter presets - - To define presets for your filters, you need to add a list of maps under the key of `:presets` to your filter in your LiveResource. - - Each of those maps has two keys: - 1. `:label` – simply the String shown to the user - 2. `:values` – a function with arity 0 that returns the values corresponding to your used filter - - > See the example below for `:values` return values for the default range and boolean filter - - - @impl Backpex.LiveResource - def filters, do: [ - begins_at: %{ - module: MyAppWeb.Filters.DateRange, - label: "Begins At", - presets: [ - %{ - label: "Last 7 Days", - values: fn -> %{ - "start" => Date.add(Date.utc_today(), -7), - "end" => Date.utc_today() - } - end - } - }, - published: %{ - module: MyAppWeb.Filters.EventPublished, - presets: [ - %{ - label: "Both", - values: fn -> [:published, :not_published] end - }, - %{ - label: "Only published", - values: fn -> [:published] end - } - ] - } - ] - - ''' @doc """ Defines whether the filter can be used or not. """ diff --git a/lib/backpex/filters/multi_select.ex b/lib/backpex/filters/multi_select.ex index 5bc2cf09..9727f4e5 100644 --- a/lib/backpex/filters/multi_select.ex +++ b/lib/backpex/filters/multi_select.ex @@ -1,7 +1,6 @@ defmodule Backpex.Filters.MultiSelect do @moduledoc """ - The multi select filter behaviour. Renders a multi select box for the implemented `options/0` callback. - `prompt/0` defines the label for the multi select box. + The multi select filter renders checkboxes for a given list of options, hence allowing the user to select multiple values. See the following example for an implementation of a multi select user filter. @@ -23,8 +22,7 @@ defmodule Backpex.Filters.MultiSelect do > #### `use Backpex.Filters.MultiSelect` {: .info} > - > When you `use Backpex.Filters.MultiSelect`, the `Backpex.Filters.MultiSelect` module will set `@behavior Backpex.Filters.Select`. - > In addition it will add a `render` and `render_form` function in order to display the corresponding filter. + > When you `use Backpex.Filters.MultiSelect`, the `Backpex.Filters.MultiSelect` module will set `@behavior Backpex.Filters.Select`. In addition it will add a `render` and `render_form` function in order to display the corresponding filter. """ use BackpexWeb, :filter diff --git a/lib/backpex/filters/range.ex b/lib/backpex/filters/range.ex index 168a8cc1..3479c5ee 100644 --- a/lib/backpex/filters/range.ex +++ b/lib/backpex/filters/range.ex @@ -1,8 +1,8 @@ defmodule Backpex.Filters.Range do @moduledoc """ - Range filters render two input fields of the same type. Backpex offers the `:date`, `:datetime` and the `number` type. + The range filter renders two input fields of the same type. Backpex offers the `:date`, `:datetime` and the `number` type. - A basic implementation of a date range filter would look like this: + See the following example for an implementation of a date range filter. defmodule MyAppWeb.Filters.DateRange do use Backpex.Filters.Range @@ -14,6 +14,8 @@ defmodule Backpex.Filters.Range do def label, do: "Date Range (begins at)" end + > #### Information {: .info} + > > Note that the query function is already implemented via `Backpex.Filters.Range`. > #### `use Backpex.Filters.Range` {: .info} diff --git a/lib/backpex/filters/select.ex b/lib/backpex/filters/select.ex index 234e3241..d0d7aa78 100644 --- a/lib/backpex/filters/select.ex +++ b/lib/backpex/filters/select.ex @@ -1,7 +1,6 @@ defmodule Backpex.Filters.Select do @moduledoc """ - The select filter behaviour. Renders a select box for the implemented `options/0` and `prompt/0` callbacks. - `prompt/0` defines the key for the `nil` value added as first option. + Tbe select filter renders a select box for the implemented `options/0` and `prompt/0` callbacks. The `prompt/0` callback defines the key for the `nil` value added as first option. See the following example for an implementation of an event status filter. diff --git a/lib/backpex/item_actions/item_action.ex b/lib/backpex/item_actions/item_action.ex index eaf8daf7..4254d061 100644 --- a/lib/backpex/item_actions/item_action.ex +++ b/lib/backpex/item_actions/item_action.ex @@ -1,117 +1,7 @@ defmodule Backpex.ItemAction do - @moduledoc ~S''' + @moduledoc """ Behaviour implemented by all item actions. - - An Item Action defines an action (such as deleting a user) that can be performed on one or more items. - Unlike resource actions, item actions are not automatically performed on all items in a resource. - First, items must be selected. - - There are multiple ways to perform an Item Action: - - use the checkboxes in the first column of the resource table to select 1-n items and trigger the action later on - - use an icon in the last column of the resource table to perform the Item Action for one item - - use the corresponding icon in the show view to perform the Item Action for the corresponding item - - If you use the first method, you must trigger the item action using the button above the resource action. If you use the second or third method, the item action is triggered immediately. - - Therefore, you need to provide a label and an icon in your code. The label is displayed above the resource table and the icon - is displayed for each element in the table and in the show view. This gives the user multiple ways to trigger your item action. - - Optionally, there can be a confirmation modal. You can enable this by specifying a text to be displayed in the modal via the `confirm` function. You can also specify a changeset and a list of fields. The fields are displayed in the confirm modal as well. - For example, a field could be a reason for deleting a user. - - In the list of fields, each field needs a type. This is because we cannot infer a type from a schema. - - To add an item action to your resource you can use the `item_actions` function. This must be a keyword list. - The keyword defines the name of the action. In addition, each keyword must define a map as a value. This map must at least - provide the module for the item action with the `module` key. The "default" Item Actions (Delete, Edit and Show) are passed as - parameters to the item_actions and may be appended to your item actions. - - Furthermore, you can specify which ways of triggering the item action are enabled with the `only` key. - - The only key must provide a list and accepts the following options - - `:row` - display an icon for each element in the table that can trigger the Item Action for the corresponding element - - `:index` - display a button at the top of the resource table, which triggers the Item Action for selected items - - `:show` - display an icon in the show view that triggers the Item Action for the corresponding item - - The following example shows how to define a soft delete item action and replace it with the default delete Item Action. - - ## Example - - defmodule DemoWeb.ItemAction.SoftDelete do - use BackpexWeb, :item_action - - alias Backpex.Resource - - @impl Backpex.ItemAction - def icon(assigns) do - ~H""" - - """ - end - - @impl Backpex.ItemAction - def fields do - [ - reason: %{ - module: Backpex.Fields.Textarea, - label: "Reason", - type: :string - } - ] - end - - @required_fields ~w[reason]a - - @impl Backpex.ItemAction - def changeset(change, attrs) do - change - |> cast(attrs, @required_fields) - |> validate_required(@required_fields) - end - - @impl Backpex.ItemAction - def label(_assigns), do: Backpex.translate("Delete") - - @impl Backpex.ItemAction - def confirm_label(_assigns), do: Backpex.translate("Delete") - - @impl Backpex.ItemAction - def cancel_label(_assigns), do: Backpex.translate("Cancel") - - @impl Backpex.ItemAction - def handle(socket, items, params) do - datetime = DateTime.truncate(DateTime.utc_now(), :second) - socket = - try do - {:ok, _items} = - Backpex.Resource.update_all( - socket.assigns, - items, - [set: [deleted_at: datetime, reason: Map.get(params, "reason")]], - "deleted" - ) - - socket - |> clear_flash() - |> put_flash(:info, "Item(s) successfully deleted.") - rescue - socket - |> clear_flash() - |> put_flash(:error, error) - end - - {:noreply, socket} - end - - # in your resource configuration file - - @impl Backpex.LiveResource - def item_actions([show, edit, _delete]) do - Enum.concat([show, edit], - soft_delete: %{module: DemoWeb.ItemAction.SoftDelete} - ) - end - ''' + """ @doc """ Action icon diff --git a/lib/backpex/live_resource.ex b/lib/backpex/live_resource.ex index 33ba6031..5ffdb391 100644 --- a/lib/backpex/live_resource.ex +++ b/lib/backpex/live_resource.ex @@ -3,556 +3,11 @@ defmodule Backpex.LiveResource do @moduledoc ~S''' - LiveResource makes it easy to manage existing resources in your application. - It provides extensive configuration options in order to meet everyone's needs. - In connection with `Backpex.Components` you can build an individual admin dashboard - on top of your application in minutes. - - - ## Example - - Before you start make sure Backpex is properly configured. - - `Backpex.LiveResource` is the module that will generate the corresponding LiveViews for the resource you configured. - You are required to set some general options to tell Backpex where to find the resource and what - changesets should be used. In addition you have to provide names and a list of fields. - - A minimal configuration looks something like this: - - defmodule MyAppWeb.UserLive do - use Backpex.LiveResource, - layout: {MyAppWeb.LayoutView, :admin}, - schema: MyApp.User, - repo: MyApp.Repo, - update_changeset: &MyApp.User.update_changeset/3, - create_changeset: &MyApp.User.create_changeset/3 - - @impl Backpex.LiveResource - def singular_name(), do: "User" - - @impl Backpex.LiveResource - def plural_name(), do: "Users" - - @impl Backpex.LiveResource - def fields do - [ - username: %{ - module: Backpex.Fields.Text, - label: "Username" - }, - first_name: %{ - module: Backpex.Fields.Text, - label: "First Name" - }, - last_name: %{ - module: Backpex.Fields.Text, - label: "Last Name" - }, - ] - end - - You are also required to configure your router in order to serve the generated LiveViews: - - defmodule MyAppWeb.Router - import Backpex.Router - - scope "/admin", MyAppWeb do - pipe_through :browser - - live_session :default, on_mount: Backpex.InitAssigns do - live_resources("/users", UserLive) - end - end - end + A LiveResource makes it easy to manage existing resources in your application. It provides extensive configuration options in order to meet everyone's needs. In connection with `Backpex.Components` you can build an individual admin dashboard on top of your application in minutes. > #### `use Backpex.LiveResource` {: .info} > > When you `use Backpex.LiveResource`, the `Backpex.LiveResource` module will set `@behavior Backpex.LiveResource`. Additionally it will create a LiveView based on the given configuration in order to create fully functional index, show, new and edit views for a resource. It will also insert fallback functions that can be overridden. - - ## Define a resource - - To explain configuration settings we created an event schema with a corresponding `EventLive` configuration file. - - defmodule MyAppWeb.EventLive do - alias MyApp.Event - - use Backpex.LiveResource, - layout: {MyAppWeb.LayoutView, :admin}, # Specify the layout you created in the step before - schema: Event, # Schema of the resource - repo: MyApp.Repo, # Ecto repository - update_changeset: &Event.update_changeset/3, # Changeset to be used for update queries - create_changeset: &Event.create_changeset/3, # Changeset to be used for create queries - pubsub: Demo.PubSub, # PubSub name of the project. - topic: "events", # The topic for PubSub - event_prefix: "event_", # The event prefix for Pubsub, to differentiate between events of different resources when subscribed to multiple resources - fluid?: true # Optional to define if your resource should be rendered full width. Depends on the your [layout configuration](installation.md) - - # Singular name to displayed on the resource page - @impl Backpex.LiveResource - def singular_name(), do: "Event" - - # Plural name to displayed on the resource page - @impl Backpex.LiveResource - def plural_name(), do: "Events" - - # Field configurations - # Here can configure which fields of the schema should be displayed on your dashboard. - # Backpex provides certain field modules that may be used for displaying the field on index and form views. - # You may define you own module or overwrite the render functions in this configuration (`render` for index views - # and `render_form` for form views). - @impl Backpex.LiveResource - def fields do - [ - # The title field of our event schema - title: %{ - module: Backpex.Fields.Text, - label: "Title" - }, - # The location field of our event schema. It should not be displayed on `:edit` view. - location: %{ - module: Backpex.Fields.Text, - label: "Location", - except: [:edit] - }, - # The location field of our event schema. We use the Backpex URL module in order to make the url clickable. - # This field is only displayed on `:index` view. - url: %{ - module: Backpex.Fields.URL, - label: "Url", - only: [:index] - }, - # The begins_at field of our event schema. We provide or own render function to display this field on index views. - # The value can be extracted from the assigns. - begins_at: %{ - module: Backpex.Fields.Date, - label: "Begins At", - render: fn assigns -> - ~H""" -
    - <%= @value %> -
    - """ - end - }, - # The ends_at field of our event schema. This field should not be sortable. - ends_at: %{ - module: Backpex.Fields.Date, - label: "Ends at" - }, - # The published field of our url schema. We use the boolean field to display a switch button on edit views. - published: %{ - module: Backpex.Fields.Boolean, - label: "Published", - sortable: false - } - ] - end - end - - ## Templates - - You are able to customize certain parts of Backpex. While you may use our app shell layout only you may also define functions to provide additional templates to be rendered on the resource LiveView or completely overwrite certain parts like the header or main content. - - See [render_resource_slot/3](Backpex.LiveResource.html#c:render_resource_slot/3) for supported positions. - - **Example:** - # in your resource configuration file - - # to add content above main on index view - def render_resource_slot(assigns, :index, :before_main), do: ~H"Hello World!" - - ## Item Query - - It is possible to manipulate the query when fetching resources for `index`, `show` and `edit` view by defining an `item_query` function. - - In all queries we define a `from` query with a named binding to fetch all existing resources on `index` view or a specific resource on `show` / `edit` view. - After that, we call the `item_query` function. By default this returns the incoming query. - - The `item_query` function makes it easy to add custom query expressions. - - For example, you could filter posts by a published boolean on `index` view. - - # in your resource configuration file - - @impl Backpex.LiveResource - def item_query(query, :index, _assigns) do - query - |> where([post], post.published) - end - - In this example we also made use of the named binding. It's always the name of the provided schema in `snake_case`. - It is recommended to build your `item_query` on top of the incoming query. Otherwise you will likely get binding errors. - - ## Authorize Actions - - Use `can?(_assigns, _action, _item)` function in you resource configuration to limit access to item actions - (Actions: `:index`, `:new`, `:show`, `:edit`, `:delete`, `:your_item_action_key`, `:your_resource_action_key`). - The function is not required and returns `true` by default. - The item is `nil` for any action that does not require an item to be performed (`:index`, `:new`, `:your_resource_action_key`). - - **Examples:** - # _item is nil for any action that does not require an item to be performed - def can?(_assigns, :new, _item), do: false - - def can?(_assigns, :my_item_action, item), do: item.role == :admin - - def can?(assigns, :my_resource_action, nil), do: assigns.current_user == :admin - - > Note that item actions are always displayed if they are defined. If you want to remove item actions completely, you must restrict access to them with `can?/3` and remove the action with the `item_actions/1` function. - - ## Resource Actions - - You may define actions for certain resources in order to integrate complex processes into Backpex. - - Action routes are automatically generated when using the `live_resources` macro. - - For example you could add an invite process to your user resource as shown in the following. - - ```elixir - defmodule MyAppWeb.Admin.Actions.Invite do - use Backpex.ResourceAction - - import Ecto.Changeset - - @impl Backpex.ResourceAction - def label, do: "Invite" - - @impl Backpex.ResourceAction - def title, do: "Invite user" - - # you can reuse Backpex fields in the field definition - @impl Backpex.ResourceAction - def fields do - [ - email: %{ - module: Backpex.Fields.Text, - label: "Email", - type: :string - } - ] - end - - @required_fields ~w[email]a - - @impl Backpex.ResourceAction - def changeset(change, attrs) do - change - |> cast(attrs, @required_fields) - |> validate_required(@required_fields) - |> validate_email(:email) - end - - # your action to be performed - @impl Backpex.ResourceAction - def handle(_socket, params) do - # Send mail - - # We suppose there was no error. - if true do - {:ok, "An email to #{params[:email]} was sent successfully."} - else - {:error, "An error occurred while sending an email to #{params[:email]}!"} - end - end - end - ``` - - ```elixir - # in your resource configuration file - - # each action consists out of an unique id and the corresponding action module - @impl Backpex.LiveResource - def resource_actions() do - [ - %{ - module: MyWebApp.Admin.ResourceActions.Invite, - id: :invite - } - ] - end - ``` - - ## Ordering - - You may provide an `init_order` option to specify how the initial index page is being ordered. - - # in your resource configuration file - - use Backpex.LiveResource, - ..., - init_order: %{by: :inserted_at, direction: :desc} - - # Routing - - ## Routing - - You are required to configure your router in order to point to the resources created in before steps. - Make sure to use the `Backpex.InitAssigns` hook to ensure all Backpex assigns are applied to the LiveViews. - - You have to use the `Backpex.Router.live_resources/3` macro to generate routes for your resources. - - # MyAppWeb.Router - - import Backpex.Router - - scope "/admin", MyAppWeb do - pipe_through :browser - - live_session :default, on_mount: Backpex.InitAssigns do - live_resources("/events", EventLive) - end - - In addition you have to use the `Backpex.Router.backpex_routes` macro. It will add some more routes at base scope. You can place this anywhere in your router. - We will mainly use this routes to insert a `Backpex.CookieController`. We need it in order to save some user related settings (e.g. which columns on index view you selected to be active). - - # MyAppWeb.Router - - import Backpex.Router - - scope "/" do - pipe_through :browser - - backpex_routes() - end - - ## Searching - - You may flag fields as searchable. A search input will appear automatically on the resource index view. - - # in your resource configuration file - @impl Backpex.LiveResource - def fields do - [ - %{ - ..., - searchable: true - } - ] - end - - For a custom placeholder, you can use the `elixir search_placeholder/0` callback. - - # in your resource configuration file - @impl Backpex.LiveResource - def search_placeholder, do: "This will be shown in the search input." - - In addition to basic searching, Backpex allows you to perform full-text searches on resources (see [Full-Text Search Guide](full_text_search.md)). - - ## Hooks - - You may define hooks that are called after their respective action. Those hooks are `on_item_created`, `on_item_updated` and `on_item_deleted`. - These methods receive the socket and the corresponding item and are expected to return a socket. - - # in your resource configuration file - @impl Backpex.LiveResource - def on_item_created(socket, item) do - # send an email on user creation - socket - end - - ## PubSub - - PubSub settings are required in order to support live updates. - - # in your resource configuration file - use Backpex.LiveResource, - ..., - pubsub: Demo.PubSub, # PubSub name of the project. - topic: "events", # The topic for PubSub - event_prefix: "event_" # The event prefix for Pubsub, to differentiate between events of different resources when subscribed to multiple resources - - In addition you may react to `...deleted`, `...updated` and `...created` events via `handle_info` - - # in your resource configuration file - @impl Phoenix.LiveView - def handle_info({"event_created", item}, socket) do - # make something in response to the event, for example show a toast to all users currently on the resource that an event has been created. - {:noreply, socket} - end - - ## Navigation - - You may define a custom navigation path that is called after the item is saved. - The method receives the socket, the live action and the corresponding item and is expected to return a route path. - - # in your resource configuration file - @impl Backpex.LiveResource - def return_to(socket, assigns, _action, _item) do - # return to user index after saving - Routes.user_path(socket, :index) - end - - ## Panels - - You are able to define panels to group certain fields together. Panels are displayed in the provided order. - The `Backpex.LiveResource.panels/0` function has to return a keyword list with an identifier and label for each panel. - You can move fields into panels with the `panel` field configuration that has to return the identifier of the corresponding panel. Fields without a panel are displayed in the `:default` panel. The `:default` panel has no label. - - > Note that a panel is not displayed when there are no fields in it. - - # in your resource configuration file - @impl Backpex.LiveResource - def panels do - [ - contact: "Contact" - ] - end - - # in your fields list - @impl Backpex.LiveResource - def fields do - [ - %{ - ..., - panel: :contact - } - ] - end - - ## Default values - - It is possible to assign default values to fields. - - # in your resource configuration file - @impl Backpex.LiveResource - def fields do - [ - username: %{ - default: fn _assigns -> "Default Username" end - } - ] - end - - > Note that default values are set when creating new resources only. - - ## Alignment - - You may align fields on index view. By default fields are aligned to the left. - - We currently support the following alignments: `:left`, `:center` and `:right`. - - # in your resource configuration file - @impl Backpex.LiveResource - def fields do - [ - %{ - ..., - align: :center - } - ] - end - - In addition to field alignment, you can align the labels on form views (`index`, `edit`, `resource_action`) using the `align_label` field option. - - We currently support the following label orientations: `:top`, `:center` and `:bottom`. - - # in your resource configuration file - @impl Backpex.LiveResource - def fields do - [ - %{ - ..., - align_label: :top - } - ] - end - - ## Fields Visibility - - You are able to change visibility of fields based on certain conditions (`assigns`). - - Imagine you want to implement a checkbox in order to toggle an input field (post likes). Initially, the input field should be visible when it has a certain value (post likes > 0). - - # in your resource configuration file - @impl Backpex.LiveResource - def fields do - [ - # show_likes is a virtual field in the post schema - show_likes: %{ - module: Backpex.Fields.Boolean, - label: "Show likes", - # initialize the button based on the likes value - select: dynamic([post: p], fragment("? > 0", p.likes)), - }, - likes: %{ - module: Backpex.Fields.Number, - label: "Likes", - # display the field based on the `show_likes` value - # the value can be part of the changeset or item (when edit view is opened initially). - visible: fn - %{live_action: :new} = assigns -> - Map.get(assigns.changeset.changes, :show_likes) - - %{live_action: :edit} = assigns -> - Map.get(assigns.changeset.changes, :show_likes, Map.get(assigns.item, :show_likes, false)) - - _assigns -> - true - end - } - ] - end - - > Note that hidden fields are not exempt from validation by Backpex itself and the visible function is not executed on `:index`. - - In addition to `visible/1`, we provide a `can?1` function that you can use to determine the visibility of a field. - It can also be used on `:index` and takes the `assigns` as a parameter. - - # in your resource configuration file - inserted_at: %{ - module: Backpex.Fields.DateTime, - label: "Created At", - can?: fn - %{live_action: :show} = _assigns -> - true - - _assigns -> - false - end - } - - ## Tooltips - - We support tooltips via [daisyUI](https://daisyui.com/components/tooltip/). - - ## Index Editable - - A small number of fields support index editable. These fields can be edited inline on the index view. - - You must enable index editable for a field. - - # in your resource configuration file - def fields do - [ - name: %{ - module: Backpex.Fields.Text, - label: "Name", - index_editable: true - } - ] - end - - Currently supported by the following fields: - - `Backpex.Fields.BelongsTo` - - `Backpex.Fields.Date` - - `Backpex.Fields.DateTime` - - `Backpex.Fields.Number` - - `Backpex.Fields.Select` - - `Backpex.Fields.Text` - - > Note you can add index editable support to your custom fields by defining the `render_index_form/1` function and enabling index editable for your field. - - ## Additional classes for index table rows - - We provide the `Backpex.LiveResource.index_row_class` option to add additional classes to table rows - on the index view. This allows you, for example, to color the rows. - - # in your resource configuration file - @impl Backpex.LiveResource - def index_row_class(assigns, item, selected, index), do: "bg-yellow-100" - - > Note that we call the function twice. Once for the row on the `tr` element and a second time for the item action overlay, because in most cases the overlay should have the same style applied. - For this reason, Tailwind CSS modifiers such as `even` and `odd` will not always work as intended. Use the provided index instead. The index starts with 0 for the first item. ''' alias Backpex.Resource diff --git a/lib/backpex/resource_action.ex b/lib/backpex/resource_action.ex index 1449bc87..21aa9b87 100644 --- a/lib/backpex/resource_action.ex +++ b/lib/backpex/resource_action.ex @@ -2,49 +2,6 @@ defmodule Backpex.ResourceAction do @moduledoc ~S''' Behaviour implemented by all resource action modules. - ## Example - - defmodule MyAppWeb.Actions.Invite do - use Backpex.ResourceAction - - import Ecto.Changeset - - @impl Backpex.ResourceAction - def title, do: "Invite user" - - @impl Backpex.ResourceAction - def label, do: "Invite" - - @impl Backpex.ResourceAction - def fields do - [ - email: %{ - module: Backpex.Fields.Text, - label: "Email", - type: :string - } - ] - end - - @impl Backpex.ResourceAction - def changeset(change, attrs) do - change - |> cast(attrs, [:email]) - |> validate_required([:email])) - end - - @impl Backpex.ResourceAction - def handle(_socket, params) do - # Send mail - - # Success - {:ok, "An email to #{params[:email]} was sent successfully."} - - # Failure - {:error, "An error occurred while sending an email to #{params[:email]}!"} - end - end - > #### `use Backpex.ResourceAction` {: .info} > > When you `use Backpex.ResourceAction`, the `Backpex.ResourceAction` module will set `@behavior Backpex.ResourceAction`. diff --git a/mix.exs b/mix.exs index ac179fa5..fc99a776 100644 --- a/mix.exs +++ b/mix.exs @@ -68,7 +68,7 @@ defmodule Backpex.MixProject do defp docs() do [ - main: "Backpex.LiveResource", + main: "readme", logo: "priv/static/images/logo.svg", extras: extras(), extra_section: "GUIDES", @@ -84,9 +84,66 @@ defmodule Backpex.MixProject do defp extras do [ - "guides/introduction/installation.md", - "guides/introduction/translations.md", - "guides/advanced/full_text_search.md", + {"README.md", title: "Introduction"}, + + # About + "guides/about/what-is-backpex.md", + "guides/about/why-we-built-backpex.md", + "guides/about/contribute-to-backpex.md", + + # Get Started + "guides/get_started/prerequisites.md", + "guides/get_started/installation.md", + + # Live Resource + "guides/live_resource/what-is-a-live-resource.md", + "guides/live_resource/templates.md", + "guides/live_resource/item-query.md", + "guides/live_resource/ordering.md", + "guides/live_resource/hooks.md", + "guides/live_resource/navigation.md", + "guides/live_resource/panels.md", + "guides/live_resource/fluid-layout.md", + "guides/live_resource/listen-to-pubsub-events.md", + "guides/live_resource/additional-classes-for-index-table-rows.md", + + # Fields + "guides/fields/what-is-a-field.md", + "guides/fields/custom-fields.md", + "guides/fields/alignment.md", + "guides/fields/visibility.md", + "guides/fields/defaults.md", + "guides/fields/readonly.md", + "guides/fields/custom-alias.md", + "guides/fields/placeholder.md", + "guides/fields/debounce-and-throttle.md", + "guides/fields/index-edit.md", + "guides/fields/error-customization.md", + "guides/fields/computed-fields.md", + + # Filter + "guides/filter/what-is-a-filter.md", + "guides/filter/how-to-add-a-filter.md", + "guides/filter/filter-presets.md", + "guides/filter/custom-filter.md", + "guides/filter/visibility-and-authorization.md", + + # Actions + "guides/actions/item-actions.md", + "guides/actions/resource-actions.md", + + # Authorization + "guides/authorization/live-resource-authorization.md", + "guides/authorization/field-authorization.md", + + # Searching + "guides/searching/basic-search.md", + "guides/searching/full-text-search.md", + + # Translations + "guides/translations/translations.md", + + # Upgrade Guides "guides/upgrading/v0.3.md", "guides/upgrading/v0.2.md" ] @@ -94,8 +151,16 @@ defmodule Backpex.MixProject do defp groups_for_extras do [ - Introduction: ~r/guides\/introduction\/.?/, - Advanced: ~r/guides\/advanced\/.?/, + Introduction: ~r/README/, + About: ~r/guides\/about\/.?/, + "Get Started": ~r/guides\/get_started\/.?/, + "Live Resource": ~r/guides\/live_resource\/.?/, + Fields: ~r/guides\/fields\/.?/, + Filter: ~r/guides\/filter\/.?/, + Actions: ~r/guides\/actions\/.?/, + Authorization: ~r/guides\/authorization\/.?/, + Searching: ~r/guides\/searching\/.?/, + Translations: ~r/guides\/translations\/.?/, "Upgrade Guides": ~r{guides/upgrading/.*} ] end @@ -104,7 +169,7 @@ defmodule Backpex.MixProject do [ Components: ~r/Backpex\.HTML.?/, Fields: ~r/Backpex\.Field.?/, - "Item Actions": ~r/Backpex\.ItemAction.?/, + Actions: ~r/Backpex\.(ItemAction|ResourceAction).?/, Filters: ~r/Backpex\.Filter.?/, Metrics: ~r/Backpex\.Metric.?/ ]