Merge branch 'release/0.3.2'

.github/release.yml

@@ -15,6 +15,9 @@ changelog:
     - title: Bug fixes
       labels:
         - bug
+    - title: Documentation
+      labels:
+        - documentation
     - title: Dependency updates
       labels:
         - dependencies

.github/workflows/ci.yml

@@ -117,6 +117,12 @@ jobs:
           otp-version: ${{ steps.otp_version.outputs.version }}
           elixir-version: ${{ steps.elixir_version.outputs.version }}
 
+      - name: Install dependencies
+        run: |
+          mix local.hex --force --if-missing
+          mix local.rebar --force --if-missing
+          mix deps.get
+
       - name: Publish package on hex.pm
         env:
           HEX_API_KEY: ${{ secrets.HEX_API_KEY }}

README.md

@@ -1,38 +1,42 @@
-# Backpex
+<img src="https://github.com/naymspace/backpex/blob/develop/priv/static/images/logo.svg?raw=true" width="100" height="100">
 
 [![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?raw=true)
 
-## Development
+<div align="center">
+  <a href="https://backpex.live/"><strong>Visit our Live Demo →</strong></a>
+</div>
 
-### 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/what-is-backpex.md)
+- [Why we built Backpex?](guides/about/why-we-built-backpex.md)
+- [Contribute to Backpex](guides/about/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).

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"""
+    <meta :if={@dsn} name="sentry-dsn" content={@dsn} />
+    """
   end
 
   @doc """

demo/lib/demo_web/components/layouts/root.html.heex

@@ -4,7 +4,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="csrf-token" content={get_csrf_token()} />
-    <%= sentry_meta_tag() %>
+    <.sentry_meta_tag />
     <.live_title suffix=" · Backpex">
       <%= assigns[:page_title] || "Phoenix Admin Panel build with PETAL" %>
     </.live_title>

demo/mix.lock

@@ -1,5 +1,5 @@
 %{
-  "bandit": {:hex, :bandit, "1.5.3", "c7ee44871da696371a5674dd2c2062e974a18cd787732efcf50cc70b98c78fdc", [:mix], [{:hpax, "~> 0.1.1", [hex: :hpax, repo: "hexpm", optional: false]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:thousand_island, "~> 1.0", [hex: :thousand_island, repo: "hexpm", optional: false]}, {:websock, "~> 0.5", [hex: :websock, repo: "hexpm", optional: false]}], "hexpm", "3812ed5e48c1f1e3109edb5c463c6f8aaf25ecfac2826606be3e5237550116ef"},
+  "bandit": {:hex, :bandit, "1.5.4", "8e56e7cfc06f3c57995be0d9bf4e45b972d8732f5c7e96ef8ec0735f52079527", [:mix], [{:hpax, "~> 0.2.0", [hex: :hpax, repo: "hexpm", optional: false]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:thousand_island, "~> 1.0", [hex: :thousand_island, repo: "hexpm", optional: false]}, {:websock, "~> 0.5", [hex: :websock, repo: "hexpm", optional: false]}], "hexpm", "04c2b38874769af67fe7f10034f606ad6dda1d8f80c4d7a0c616b347584d5aff"},
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
   "castore": {:hex, :castore, "1.0.7", "b651241514e5f6956028147fe6637f7ac13802537e895a724f90bf3e36ddd1dd", [:mix], [], "hexpm", "da7785a4b0d2a021cd1292a60875a784b6caef71e76bf4917bdee1f390455cf5"},
   "certifi": {:hex, :certifi, "2.12.0", "2d1cca2ec95f59643862af91f001478c9863c2ac9cb6e2f89780bfd8de987329", [:rebar3], [], "hexpm", "ee68d85df22e554040cdb4be100f33873ac6051387baf6a8f6ce82272340ff1c"},
@@ -11,7 +11,7 @@
   "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"},
   "ecto": {:hex, :ecto, "3.11.2", "e1d26be989db350a633667c5cda9c3d115ae779b66da567c68c80cfb26a8c9ee", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "3c38bca2c6f8d8023f2145326cc8a80100c3ffe4dcbd9842ff867f7fc6156c65"},
   "ecto_psql_extras": {:hex, :ecto_psql_extras, "0.8.0", "440719cd74f09b3f01c84455707a2c3972b725c513808e68eb6c5b0ab82bf523", [:mix], [{:ecto_sql, "~> 3.7", [hex: :ecto_sql, repo: "hexpm", optional: false]}, {:postgrex, "~> 0.16.0 or ~> 0.17.0 or ~> 0.18.0", [hex: :postgrex, repo: "hexpm", optional: false]}, {:table_rex, "~> 3.1.1 or ~> 4.0.0", [hex: :table_rex, repo: "hexpm", optional: false]}], "hexpm", "f1512812dc196bcb932a96c82e55f69b543dc125e9d39f5e3631a9c4ec65ef12"},
-  "ecto_sql": {:hex, :ecto_sql, "3.11.2", "c7cc7f812af571e50b80294dc2e535821b3b795ce8008d07aa5f336591a185a8", [:mix], [{:db_connection, "~> 2.4.1 or ~> 2.5", [hex: :db_connection, repo: "hexpm", optional: false]}, {:ecto, "~> 3.11.0", [hex: :ecto, repo: "hexpm", optional: false]}, {:myxql, "~> 0.6.0", [hex: :myxql, repo: "hexpm", optional: true]}, {:postgrex, "~> 0.16 or ~> 1.0", [hex: :postgrex, repo: "hexpm", optional: true]}, {:tds, "~> 2.1.1 or ~> 2.2", [hex: :tds, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4.0 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "73c07f995ac17dbf89d3cfaaf688fcefabcd18b7b004ac63b0dc4ef39499ed6b"},
+  "ecto_sql": {:hex, :ecto_sql, "3.11.3", "4eb7348ff8101fbc4e6bbc5a4404a24fecbe73a3372d16569526b0cf34ebc195", [:mix], [{:db_connection, "~> 2.4.1 or ~> 2.5", [hex: :db_connection, repo: "hexpm", optional: false]}, {:ecto, "~> 3.11.0", [hex: :ecto, repo: "hexpm", optional: false]}, {:myxql, "~> 0.6", [hex: :myxql, repo: "hexpm", optional: true]}, {:postgrex, "~> 0.16 or ~> 1.0", [hex: :postgrex, repo: "hexpm", optional: true]}, {:tds, "~> 2.1.1 or ~> 2.2", [hex: :tds, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4.0 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "e5f36e3d736b99c7fee3e631333b8394ade4bafe9d96d35669fca2d81c2be928"},
   "esbuild": {:hex, :esbuild, "0.8.1", "0cbf919f0eccb136d2eeef0df49c4acf55336de864e63594adcea3814f3edf41", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:jason, "~> 1.4", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "25fc876a67c13cb0a776e7b5d7974851556baeda2085296c14ab48555ea7560f"},
   "ex_doc": {:hex, :ex_doc, "0.34.0", "ab95e0775db3df71d30cf8d78728dd9261c355c81382bcd4cefdc74610bef13e", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "60734fb4c1353f270c3286df4a0d51e65a2c1d9fba66af3940847cc65a8066d7"},
   "ex_machina": {:hex, :ex_machina, "2.7.0", "b792cc3127fd0680fecdb6299235b4727a4944a09ff0fa904cc639272cd92dc7", [:mix], [{:ecto, "~> 2.2 or ~> 3.0", [hex: :ecto, repo: "hexpm", optional: true]}, {:ecto_sql, "~> 3.0", [hex: :ecto_sql, repo: "hexpm", optional: true]}], "hexpm", "419aa7a39bde11894c87a615c4ecaa52d8f107bbdd81d810465186f783245bf8"},
@@ -23,7 +23,7 @@
   "gettext": {:hex, :gettext, "0.24.0", "6f4d90ac5f3111673cbefc4ebee96fe5f37a114861ab8c7b7d5b30a1108ce6d8", [:mix], [{:expo, "~> 0.5.1", [hex: :expo, repo: "hexpm", optional: false]}], "hexpm", "bdf75cdfcbe9e4622dd18e034b227d77dd17f0f133853a1c73b97b3d6c770e8b"},
   "hackney": {:hex, :hackney, "1.20.1", "8d97aec62ddddd757d128bfd1df6c5861093419f8f7a4223823537bad5d064e2", [:rebar3], [{:certifi, "~>2.12.0", [hex: :certifi, repo: "hexpm", optional: false]}, {:idna, "~>6.1.0", [hex: :idna, repo: "hexpm", optional: false]}, {:metrics, "~>1.0.0", [hex: :metrics, repo: "hexpm", optional: false]}, {:mimerl, "~>1.1", [hex: :mimerl, repo: "hexpm", optional: false]}, {:parse_trans, "3.4.1", [hex: :parse_trans, repo: "hexpm", optional: false]}, {:ssl_verify_fun, "~>1.1.0", [hex: :ssl_verify_fun, repo: "hexpm", optional: false]}, {:unicode_util_compat, "~>0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "fe9094e5f1a2a2c0a7d10918fee36bfec0ec2a979994cff8cfe8058cd9af38e3"},
   "heroicons": {:hex, :heroicons, "0.5.5", "c2bcb05a90f010df246a5a2a2b54cac15483b5de137b2ef0bead77fcdf06e21a", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:phoenix_live_view, ">= 0.18.2", [hex: :phoenix_live_view, repo: "hexpm", optional: false]}], "hexpm", "2f4bf929440fecd5191ba9f40e5009b0f75dc993d765c0e4d068fcb7026d6da1"},
-  "hpax": {:hex, :hpax, "0.1.2", "09a75600d9d8bbd064cdd741f21fc06fc1f4cf3d0fcc335e5aa19be1a7235c84", [:mix], [], "hexpm", "2c87843d5a23f5f16748ebe77969880e29809580efdaccd615cd3bed628a8c13"},
+  "hpax": {:hex, :hpax, "0.2.0", "5a58219adcb75977b2edce5eb22051de9362f08236220c9e859a47111c194ff5", [:mix], [], "hexpm", "bea06558cdae85bed075e6c036993d43cd54d447f76d8190a8db0dc5893fa2f1"},
   "idna": {:hex, :idna, "6.1.1", "8a63070e9f7d0c62eb9d9fcb360a7de382448200fbbd1b106cc96d3d8099df8d", [:rebar3], [{:unicode_util_compat, "~> 0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "92376eb7894412ed19ac475e4a86f7b413c1b9fbb5bd16dccd57934157944cea"},
   "jason": {:hex, :jason, "1.4.1", "af1504e35f629ddcdd6addb3513c3853991f694921b1b9368b0bd32beb9f1b63", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "fbb01ecdfd565b56261302f7e1fcc27c4fb8f32d56eab74db621fc154604a7a1"},
   "libcluster": {:hex, :libcluster, "3.3.3", "a4f17721a19004cfc4467268e17cff8b1f951befe428975dd4f6f7b84d927fe0", [:mix], [{:jason, "~> 1.1", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "7c0a2275a0bb83c07acd17dab3c3bfb4897b145106750eeccc62d302e3bdfee5"},

demo/yarn.lock

@@ -566,11 +566,11 @@ brace-expansion@^1.1.7:
     concat-map "0.0.1"
 
 braces@^3.0.2, braces@~3.0.2:
-  version "3.0.2"
-  resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.2.tgz#3454e1a462ee8d599e236df336cd9ea4f8afe107"
-  integrity sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==
+  version "3.0.3"
+  resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.3.tgz#490332f40919452272d55a8480adc0c441358789"
+  integrity sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==
   dependencies:
-    fill-range "^7.0.1"
+    fill-range "^7.1.1"
 
 builtins@^5.0.1:
   version "5.0.1"
@@ -1247,10 +1247,10 @@ file-entry-cache@^7.0.0:
   dependencies:
     flat-cache "^3.1.1"
 
-fill-range@^7.0.1:
-  version "7.0.1"
-  resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-7.0.1.tgz#1919a6a7c75fe38b2c7c77e5198535da9acdda40"
-  integrity sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==
+fill-range@^7.1.1:
+  version "7.1.1"
+  resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-7.1.1.tgz#44265d3cac07e3ea7dc247516380643754a05292"
+  integrity sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==
   dependencies:
     to-regex-range "^5.0.1"
 

guides/about/contribute-to-backpex.md

@@ -0,0 +1,60 @@
+# 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 provide a roadmap and a list of issues that you can work on to contribute to Backpex.
+
+- Roadmap: https://github.com/orgs/naymspace/projects/2
+- Issues: https://github.com/naymspace/backpex/issues
+
+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.
+
+- 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
+
+## 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=<SECRET_KEY_BASE>
+LIVE_VIEW_SIGNING_SALT=<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.

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 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.
+
+TODO: add screenshots of key features here

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.