From a8dc0b6056c4829c3736edc3511ff036394fc5a5 Mon Sep 17 00:00:00 2001 From: Florian Arens <60519307+Flo0807@users.noreply.github.com> Date: Fri, 6 Sep 2024 08:10:59 +0200 Subject: [PATCH 1/3] Move prerequisites to installation guide --- guides/get_started/installation.md | 57 ++++++++++++++++++++++++++++- guides/get_started/prerequisites.md | 56 ---------------------------- 2 files changed, 56 insertions(+), 57 deletions(-) delete mode 100644 guides/get_started/prerequisites.md diff --git a/guides/get_started/installation.md b/guides/get_started/installation.md index b6ad8ff4..3ba7966f 100644 --- a/guides/get_started/installation.md +++ b/guides/get_started/installation.md @@ -2,7 +2,62 @@ 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. -Make sure you meet the [prerequisites](prerequisites.md) before you start the installation. +## 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. + +### Alpine.js + +Backpex uses [Alpine.js](https://alpinejs.dev/) for some interactivity. Make sure you have Alpine.js installed in your application. + +You can install Alpine.js by installing it via npm: + +```bash +cd assets && npm install alpinejs +``` + +Then, import Alpine.js in your `app.js` file, start it and adjust your LiveView configuration: + +```javascript +import Alpine from "alpinejs"; + +window.Alpine = Alpine; +Alpine.start(); + +const liveSocket = new LiveSocket('/live', Socket, { + // add this + dom: { + onBeforeElUpdated (from, to) { + if (from._x_dataStack) { + window.Alpine.clone(from, to) + } + }, + }, + params: { _csrf_token: csrfToken }, +}) +``` + +### 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/). + +### Ecto + +Backpex currently depends on Ecto as the database layer. Make sure you have a running Ecto repository in your application. + +> #### Warning {: .warning} +> +> Backpex requires an `id` field in your database schema. We tested Backpex with UUID (binary_id) and integer (bigserial) primary keys. + +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. ## Add to list of dependencies diff --git a/guides/get_started/prerequisites.md b/guides/get_started/prerequisites.md deleted file mode 100644 index bf57c69a..00000000 --- a/guides/get_started/prerequisites.md +++ /dev/null @@ -1,56 +0,0 @@ -# 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. - -## Alpine.js - -Backpex uses [Alpine.js](https://alpinejs.dev/) for some interactivity. Make sure you have Alpine.js installed in your application. - -You can install Alpine.js by installing it via npm: - -```bash -cd assets && npm install alpinejs -``` - -Then, import Alpine.js in your `app.js` file, start it and adjust your LiveView configuration: - -```javascript -import Alpine from "alpinejs"; - -window.Alpine = Alpine; -Alpine.start(); - -const liveSocket = new LiveSocket('/live', Socket, { - // add this - dom: { - onBeforeElUpdated (from, to) { - if (from._x_dataStack) { - window.Alpine.clone(from, to) - } - }, - }, - params: { _csrf_token: csrfToken }, -}) -``` - -## 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/). - -## Ecto - -Backpex currently depends on Ecto as the database layer. Make sure you have a running Ecto repository in your application. - -> #### Warning {: .warning} -> -> Backpex requires an `id` field in your database schema. We tested Backpex with UUID (binary_id) and integer (bigserial) primary keys. - -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 From 4bc7b14e0b137d0efde0e0284779ff54b36d7021 Mon Sep 17 00:00:00 2001 From: Florian Arens <60519307+Flo0807@users.noreply.github.com> Date: Fri, 6 Sep 2024 08:23:21 +0200 Subject: [PATCH 2/3] Remove prerequisites from mix.exs --- mix.exs | 1 - 1 file changed, 1 deletion(-) diff --git a/mix.exs b/mix.exs index 4bb5c8d2..a9d97772 100644 --- a/mix.exs +++ b/mix.exs @@ -91,7 +91,6 @@ defmodule Backpex.MixProject do "guides/about/contribute-to-backpex.md", # Get Started - "guides/get_started/prerequisites.md", "guides/get_started/installation.md", # Live Resource From df0f8cf259468150c30a1513441ff2d2074dcd59 Mon Sep 17 00:00:00 2001 From: Florian Arens <60519307+Flo0807@users.noreply.github.com> Date: Fri, 6 Sep 2024 08:37:55 +0200 Subject: [PATCH 3/3] Improve readme --- README.md | 48 ++++++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index bc7835a2..78339ef2 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,22 @@ - - [![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) +
+ +
+
+ Phoenix Admin Panel built with PETAL ยท Backpex +
+
+ ๐Ÿ“š Documentation + โ€ข + ๐Ÿ› ๏ธ Installation Guide + โ€ข + ๐Ÿฉต Contribute +
+ # Backpex 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. @@ -15,28 +27,28 @@ Welcome! Backpex is a highly customizable administration panel for Phoenix LiveV Visit our Live Demo โ†’ -## Key Features +## ๐Ÿš€ Key Features -- **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. +- ๐Ÿ“Š **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 and add custom filters for instant, LiveView-powered results. +- โšก **Resource Actions**: Implement global custom actions like user invitations or exports, with support for additional form fields. +- ๐Ÿ”’ **Authorization**: Handle CRUD and custom action authorization via simple pattern matching, with optional integration for external authorization libraries. +- ๐Ÿงฉ **Field Types**: Out-of-the-box support for Text, Number, Date, Upload, and more. Easily extend with your own custom field type modules. +- ๐Ÿ”— **Associations**: Effortlessly handle HasOne, BelongsTo, and HasMany(Through) associations with minimal configuration. Customize available options and rendered columns. +- ๐Ÿ“ˆ **Metrics**: Add value metrics such as sums or averages for quick data insights, with more metric types on the horizon. -## Installation & Documentation +## ๐Ÿ› ๏ธ Installation & Documentation -See our comprehensive [installation guide](guides/get_started/installation.md) for more information on how to install and configure Backpex in your Phoenix application. +See our comprehensive [installation guide](https://hexdocs.pm/backpex/installation.html) for more information on how to install and configure Backpex in your Phoenix application. 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. -## Learn More +## ๐Ÿค” Learn More -- [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) +- [What is Backpex?](https://hexdocs.pm/backpex/what-is-backpex.html) +- [Why we built Backpex?](https://hexdocs.pm/backpex/what-is-backpex.html) +- [Contribute to Backpex](https://hexdocs.pm/backpex/contribute-to-backpex.html) -## License +## ๐Ÿ“œ License -Backpex source code is licensed under the [MIT License](https://github.com/naymspace/backpex/blob/main/LICENSE.md). \ No newline at end of file +Backpex is open-source software, licensed under the [MIT License](https://github.com/naymspace/backpex/blob/main/LICENSE.md). \ No newline at end of file