+
+ <: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
index cd0d6a1a..a870da1f 100644
--- a/guides/fields/visibility.md
+++ b/guides/fields/visibility.md
@@ -1 +1,136 @@
-# Visibility
\ No newline at end of file
+# 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
index 301f10ea..6bc9a95c 100644
--- a/guides/fields/what-is-a-field.md
+++ b/guides/fields/what-is-a-field.md
@@ -1 +1,76 @@
-# What is a Field?
\ No newline at end of file
+# 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..4b1d2667
--- /dev/null
+++ b/guides/filter/custom-filter.md
@@ -0,0 +1 @@
+# Custom Filter
\ No newline at end of file
diff --git a/guides/filter/filter-presets.md b/guides/filter/filter-presets.md
new file mode 100644
index 00000000..a1760d8c
--- /dev/null
+++ b/guides/filter/filter-presets.md
@@ -0,0 +1 @@
+# Filter Presets
\ No newline at end of file
diff --git a/guides/get_started/installation.md b/guides/get_started/installation.md
index efe6dbb3..a4c9c63d 100644
--- a/guides/get_started/installation.md
+++ b/guides/get_started/installation.md
@@ -1,15 +1,6 @@
# 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.
+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 Backpex to list of dependencies
@@ -19,22 +10,32 @@ In your `mix.exs`:
defp deps do
[
...
- {:backpex, path: "backpex_path"}
+ {:backpex, "~> 0.2.0"}
]
end
```
## Add Backpex files to tailwind content
+Backpex uses Tailwind CSS and daisyUI. Make sure to add the Backpex files to your tailwind content to make sure the styles are applied.
+
In your `tailwind.config.js`:
```js
-content: ['./path_to_deps/backpex/**/*.*ex']
+..,
+content: [
+ ...,
+ 'deps/backpex/**/*.*ex'
+]
```
+> #### Info {: .info}
+>
+> The path to the Backpex files may vary depending on your project setup.
+
## Setup formatter
-We recommend to add Backpex to the list of dependencies in your `.formatter.exs`.
+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
@@ -90,3 +91,11 @@ If you do not want to put effort into creating your own layout, feel free to use
```
You can now create and configure the corresponding resources.
+
+## Create test resource
+
+## Setup routing
+
+## Configure LiveResource
+
+## Configure Routes
diff --git a/guides/get_started/prerequisites.md b/guides/get_started/prerequisites.md
index 486c3eb1..e2af32bd 100644
--- a/guides/get_started/prerequisites.md
+++ b/guides/get_started/prerequisites.md
@@ -14,7 +14,7 @@ Backpex uses Tailwind CSS for styling. Make sure you have Tailwind CSS installed
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/).
-> #### Important {: .info}
+> #### Warning {: .warning}
>
> Backpex currently only supports daisyUI light mode. Help us to support dark mode by contributing to the project.
diff --git a/guides/live_resource/what-is-a-live-resource.md b/guides/live_resource/what-is-a-live-resource.md
index 36ce6a37..eb97ef0c 100644
--- a/guides/live_resource/what-is-a-live-resource.md
+++ b/guides/live_resource/what-is-a-live-resource.md
@@ -1 +1,5 @@
-# What is a LiveResource?
\ No newline at end of file
+# 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/lib/backpex/field.ex b/lib/backpex/field.ex
index 76ff8ddf..944c3a5b 100644
--- a/lib/backpex/field.ex
+++ b/lib/backpex/field.ex
@@ -53,143 +53,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/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"""
- + <%= 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/filter/boolean-filter.md b/guides/filter/boolean-filter.md
deleted file mode 100644
index 02caf67c..00000000
--- a/guides/filter/boolean-filter.md
+++ /dev/null
@@ -1 +0,0 @@
-# Boolean Filter
\ No newline at end of file
diff --git a/guides/filter/custom-filter.md b/guides/filter/custom-filter.md
index 4b1d2667..815ff27d 100644
--- a/guides/filter/custom-filter.md
+++ b/guides/filter/custom-filter.md
@@ -1 +1,67 @@
-# Custom Filter
\ No newline at end of file
+# 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
index a1760d8c..ea089f56 100644
--- a/guides/filter/filter-presets.md
+++ b/guides/filter/filter-presets.md
@@ -1 +1,44 @@
-# Filter Presets
\ No newline at end of file
+# 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
index 660a52bb..eb3d1a79 100644
--- a/guides/filter/how-to-add-a-filter.md
+++ b/guides/filter/how-to-add-a-filter.md
@@ -1 +1,74 @@
-# How to add a Filter?
\ No newline at end of file
+# 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.- <%= 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
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.
- <.link navigate="/" class="my-1 flex justify-between px-4 py-2 text-sm text-red-600 hover:bg-gray-100">
+
+ <.link navigate={~p"/"} class="flex justify-between text-red-600 hover:bg-gray-100">
+
Logout
-
- <%= @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
-
- ## 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
-
- ## 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
-
- ## Tooltips
-
- We support tooltips via [daisyUI](https://daisyui.com/components/tooltip/).
'''
alias Backpex.Resource
diff --git a/mix.exs b/mix.exs
index 98151ce5..fc99a776 100644
--- a/mix.exs
+++ b/mix.exs
@@ -103,6 +103,8 @@ defmodule Backpex.MixProject do
"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
From 941bcad8358abfe8c2462ca4c023f5f7d31cc35f Mon Sep 17 00:00:00 2001
From: Florian Arens <60519307+Flo0807@users.noreply.github.com>
Date: Fri, 14 Jun 2024 15:55:30 +0200
Subject: [PATCH 15/28] Fix typo in upload docs
---
lib/backpex/fields/upload.ex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
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
From 22531e24e321b1e024fad1124672ba68f00e40fe Mon Sep 17 00:00:00 2001
From: Florian Arens <60519307+Flo0807@users.noreply.github.com>
Date: Fri, 14 Jun 2024 18:43:35 +0200
Subject: [PATCH 16/28] Fix form error hint is only shown after second submit
---
lib/backpex/live_components/form_component.ex | 19 +++++++++++++++----
1 file changed, 15 insertions(+), 4 deletions(-)
diff --git a/lib/backpex/live_components/form_component.ex b/lib/backpex/live_components/form_component.ex
index 5755a914..bb131695 100644
--- a/lib/backpex/live_components/form_component.ex
+++ b/lib/backpex/live_components/form_component.ex
@@ -18,6 +18,7 @@ defmodule Backpex.FormComponent do
socket
|> assign(assigns)
|> assign_new(:action_type, fn -> nil end)
+ |> assign_new(:show_form_errors, fn -> false end)
|> update_assigns()
|> assign_form()
@@ -26,14 +27,12 @@ defmodule Backpex.FormComponent do
defp update_assigns(%{assigns: %{action_type: :item}} = socket) do
socket
- |> assign_new(:show_form_errors, fn -> false end)
|> assign_fields()
|> assign_changeset()
end
defp update_assigns(%{assigns: assigns} = socket) do
socket
- |> assign(:show_form_errors, assigns.live_action == :edit)
|> apply_action(assigns.live_action)
|> maybe_assign_uploads()
end
@@ -104,7 +103,10 @@ defmodule Backpex.FormComponent do
send(self(), {:update_changeset, changeset})
- socket = assign(socket, :form, form)
+ socket =
+ socket
+ |> assign(:form, form)
+ |> assign(:show_form_errors, false)
{:noreply, socket}
end
@@ -125,12 +127,17 @@ defmodule Backpex.FormComponent do
send(self(), {:update_changeset, changeset})
- socket = assign(socket, :form, form)
+ socket =
+ socket
+ |> assign(:form, form)
+ |> assign(:show_form_errors, false)
{:noreply, socket}
end
def handle_event("validate", _params, socket) do
+ socket = assign(socket, :show_form_errors, false)
+
{:noreply, socket}
end
@@ -230,6 +237,7 @@ defmodule Backpex.FormComponent do
socket =
socket
+ |> assign(:show_form_errors, false)
|> clear_flash()
|> put_flash(:info, info_msg)
|> push_navigate(to: return_to)
@@ -281,6 +289,7 @@ defmodule Backpex.FormComponent do
socket =
socket
+ |> assign(:show_form_errors, false)
|> clear_flash()
|> put_flash(:info, info_msg)
|> push_navigate(to: return_to)
@@ -323,6 +332,7 @@ defmodule Backpex.FormComponent do
socket =
socket
+ |> assign(:show_form_errors, false)
|> put_flash_message(result)
|> push_redirect(to: return_to)
@@ -365,6 +375,7 @@ defmodule Backpex.FormComponent do
{message, socket} =
socket
+ |> assign(:show_form_errors, false)
|> assign(selected_items: [])
|> assign(select_all: false)
|> action_to_confirm.module.handle(selected_items, params)
From 239fffbdf0f4f93dbd32c377f55bfb2293020e43 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 14 Jun 2024 17:10:46 +0000
Subject: [PATCH 17/28] Bump bandit from 1.5.3 to 1.5.4 in /demo
Bumps [bandit](https://github.com/mtrudel/bandit) from 1.5.3 to 1.5.4.
- [Changelog](https://github.com/mtrudel/bandit/blob/main/CHANGELOG.md)
- [Commits](https://github.com/mtrudel/bandit/compare/1.5.3...1.5.4)
---
updated-dependencies:
- dependency-name: bandit
dependency-type: direct:production
update-type: version-update:semver-patch
...
Signed-off-by: dependabot[bot] 
+
[](https://github.com/naymspace/backpex/actions/workflows/ci.yml)
[](https://github.com/naymspace/backpex/blob/develop/LICENSE.md)
@@ -9,7 +9,7 @@
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.
-
+
Visit our Live Demo →
From b5fa82e93fda160ce65316ab4270c363fcd0f328 Mon Sep 17 00:00:00 2001
From: Florian Arens <60519307+Flo0807@users.noreply.github.com>
Date: Fri, 12 Apr 2024 15:01:16 +0200
Subject: [PATCH 24/28] Refactor sentry meta tag
---
demo/lib/demo_web/components/core_components.ex | 13 ++++++-------
demo/lib/demo_web/components/layouts/root.html.heex | 2 +-
2 files changed, 7 insertions(+), 8 deletions(-)
diff --git a/demo/lib/demo_web/components/core_components.ex b/demo/lib/demo_web/components/core_components.ex
index e2b2f6e4..e175b6aa 100644
--- a/demo/lib/demo_web/components/core_components.ex
+++ b/demo/lib/demo_web/components/core_components.ex
@@ -4,8 +4,6 @@ defmodule DemoWeb.CoreComponents do
"""
use Phoenix.Component
- import Phoenix.HTML.Tag
-
@doc """
Renders the analytics snippet.
"""
@@ -26,11 +24,12 @@ defmodule DemoWeb.CoreComponents do
@doc """
Builds sentry meta tag.
"""
- def sentry_meta_tag do
- case Application.get_env(:sentry, :dsn) do
- nil -> nil
- dsn -> tag(:meta, name: "sentry-dsn", content: dsn)
- end
+ def sentry_meta_tag(assigns) do
+ assigns = assign(assigns, :dsn, Application.get_env(:sentry, :dsn))
+
+ ~H"""
+
+ """
end
@doc """
diff --git a/demo/lib/demo_web/components/layouts/root.html.heex b/demo/lib/demo_web/components/layouts/root.html.heex
index f5d3006d..cda605a9 100644
--- a/demo/lib/demo_web/components/layouts/root.html.heex
+++ b/demo/lib/demo_web/components/layouts/root.html.heex
@@ -4,7 +4,7 @@
- <%= sentry_meta_tag() %>
+ <.sentry_meta_tag />
<.live_title suffix=" · Backpex">
<%= assigns[:page_title] || "Phoenix Admin Panel build with PETAL" %>
From 001c5dba5de3e298dba74aab4847bf33173b5fb2 Mon Sep 17 00:00:00 2001
From: Florian Arens <60519307+Flo0807@users.noreply.github.com>
Date: Mon, 17 Jun 2024 10:04:50 +0200
Subject: [PATCH 25/28] Update what is backpex guide
---
guides/about/what-is-backpex.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/guides/about/what-is-backpex.md b/guides/about/what-is-backpex.md
index 81c79a6a..a854168c 100644
--- a/guides/about/what-is-backpex.md
+++ b/guides/about/what-is-backpex.md
@@ -2,7 +2,7 @@
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.
+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 hours, not days.
Whether you want to quickly scaffold CRUD views for your existing data or build a full-fledged administration panel, Backpex has you covered.
From f600933bffae8a89179a5e2cdc1a98d6a8d5d3cc Mon Sep 17 00:00:00 2001
From: Florian Arens <60519307+Flo0807@users.noreply.github.com>
Date: Tue, 18 Jun 2024 08:30:25 +0200
Subject: [PATCH 26/28] Update contributing guide
---
guides/about/contribute-to-backpex.md | 18 ++++++++++++++----
1 file changed, 14 insertions(+), 4 deletions(-)
diff --git a/guides/about/contribute-to-backpex.md b/guides/about/contribute-to-backpex.md
index 93aa506d..899db9e7 100644
--- a/guides/about/contribute-to-backpex.md
+++ b/guides/about/contribute-to-backpex.md
@@ -4,13 +4,23 @@ We are excited to have you contribute to Backpex! We are always looking for ways
## 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:
+We provide a roadmap and a list of issues that you can work on to contribute to Backpex.
-- Reporting bugs
-- Requesting new features
+- Roadmap: https://github.com/orgs/naymspace/projects/2
+- Issues: https://github.com/naymspace/backpex/issues
+
+Especially, issues labeled with `good-first-issue` are a good starting point for new contributors.
+
+We also use GitHub's discussion feature to discuss new ideas and features.
+
+- Discussions: https://github.com/naymspace/backpex/discussions
+
+If you don't find an issue that you want to work on, you can always contribute to Backpex by:
+
+- Reporting bugs (create an issue)
+- Requesting new features (use the discussions)
- Improving the documentation
- Improving the demo application
-- Fixing bugs
## Fork the repository
From a9130e027ae14eb39ab217bbc2dc8c703edd70d3 Mon Sep 17 00:00:00 2001
From: Florian Arens <60519307+Flo0807@users.noreply.github.com>
Date: Tue, 18 Jun 2024 08:50:06 +0200
Subject: [PATCH 27/28] Link issue list with good-first-issue label
---
guides/about/contribute-to-backpex.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/guides/about/contribute-to-backpex.md b/guides/about/contribute-to-backpex.md
index 899db9e7..b7138957 100644
--- a/guides/about/contribute-to-backpex.md
+++ b/guides/about/contribute-to-backpex.md
@@ -9,7 +9,7 @@ We provide a roadmap and a list of issues that you can work on to contribute to
- Roadmap: https://github.com/orgs/naymspace/projects/2
- Issues: https://github.com/naymspace/backpex/issues
-Especially, issues labeled with `good-first-issue` are a good starting point for new contributors.
+Especially, [issues labeled with `good-first-issue`](https://github.com/naymspace/backpex/labels/good-first-issue) are a good starting point for new contributors.
We also use GitHub's discussion feature to discuss new ideas and features.
From d9803464543c386b7c9745de090a4926e64bbf2d Mon Sep 17 00:00:00 2001
From: Florian Arens <60519307+Flo0807@users.noreply.github.com>
Date: Tue, 18 Jun 2024 10:51:09 +0200
Subject: [PATCH 28/28] Bump version in mix.exs
---
mix.exs | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/mix.exs b/mix.exs
index dd1d1350..3dd6ac95 100644
--- a/mix.exs
+++ b/mix.exs
@@ -1,7 +1,7 @@
defmodule Backpex.MixProject do
use Mix.Project
- @version "0.3.1"
+ @version "0.3.2"
@source_url "https://github.com/naymspace/backpex"
def project do