Merge pull request #78 from savannabits/3.x-dev

Updated README with the package's documentation for v3.x

README.md

@@ -1,11 +1,38 @@
-# Add support for Modules in Filament using nwidart/laravel-modules
+# Filament Modules
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/coolsam/modules.svg?style=flat-square)](https://packagist.org/packages/coolsam/modules)
 [![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/savannabits/filament-modules/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/savannabits/filament-modules/actions?query=workflow%3Arun-tests+branch%3Amain)
 [![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/savannabits/filament-modules/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/savannabits/filament-modules/actions?query=workflow%3Afix-php-code-style+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/coolsam/modules.svg?style=flat-square)](https://packagist.org/packages/coolsam/modules)
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+This package brings the power of modules to Laravel Filament. It allows you to organize your filament code into fully
+autonomous modules that can be easily shared and reused across multiple projects.
+With this package, you can turn each of your modules into a fully functional Filament Plugin with its own resources,
+pages, widgets, components and more. What's more, you don't even need to register each of these plugins in your main
+Filament Panel. All you need to do is register the `ModulesPlugin` in your panel, and it will take care of the rest for
+you.
+
+This package is simple a wrapper of [nwidart/laravel-modules](https://docs.laravelmodules.com) package to make it work
+with Laravel Filament.
+
+## Features
+
+- A command to prepare your module for Filament
+- A command to create a Filament Cluster in your module
+- A command to create additional Filament Plugins in your module
+- A command to create a new Filament resource in your module
+- A command to create a new Filament page in your module
+- A command to create a new Filament widget in your module
+- Organize your admin panel into Cluster, one for each supported module.
+
+## Requirements
+
+v3 of this package requires the following dependencies:
+
+- Laravel 10.x or higher
+- Filament 3.x or higher
+- PHP 8.1 or higher
+- nwidart/laravel-modules 10.x
 
 ## Installation
 
@@ -15,39 +42,141 @@ You can install the package via composer:
 composer require coolsam/modules
 ```
 
-You can publish and run the migrations with:
-
-```bash
-php artisan vendor:publish --tag="modules-migrations"
-php artisan migrate
-```
+This will automatically install `nwidart/laravel-modules` as well. Make sure you go through
+the [documentation](https://docs.laravelmodules.com) to understand how to use the package and to configure it properly
+before proceeding.
 
 You can publish the config file with:
 
 ```bash
 php artisan vendor:publish --tag="modules-config"
 ```
 
-Optionally, you can publish the views using
+Alternatively, just run the installation command and follow the prompts:
 
 ```bash
-php artisan vendor:publish --tag="modules-views"
+php artisan modules:install
 ```
 
-This is the contents of the published config file:
+### Configuration
 
-```php
-return [
-];
-```
+After publishing the config file, you can configure the package to your liking. The configuration file is located
+at `config/filament-modules.php`.
+The following can be adjusted in the configuration file:
+
+- **auto-register-plugins**: If set to true, the package will automatically register all the plugins in your modules.
+  Otherwise, you will need to register each plugin manually in your Filament Panel.
+- **clusters.enabled**: If set to true, a cluster will be created in each module during the `module:filament:install`
+  command and all filament files for that module may reside inside that cluster. Otherwise, filament files will reside
+  in Filament/Resources, Filament/Pages, Filament/Widgets, etc.
+- **clusters.use-top-navigation**: If set to true, the top navigation will be used to navigate between clusters while
+  the actual links will be loaded as a side sub-navigation. In my opinion, this improves UX. Otherwise, the package will
+  honor the configuration that you have in your panel.
 
 ## Usage
 
+### Register the plugin
+
+The package comes with a `ModulesPlugin` that you can register in your Filament Panel. This plugin will automatically
+load all the modules in your application and register them as Filament plugins.
+In order to achieve this, you need to register the `ModulesPlugin` in your panel of choice (e.g. Admin Panel) like so:
+
 ```php
-$modules = new Coolsam\Modules();
-echo $modules->echoPhrase('Hello, Coolsam!');
+// e.g. in App\Providers\Filament\AdminPanelProvider.php
+
+use Filament\Plugin\ModulesPlugin;
+public function panel(Panel $panel): Panel
+{
+    return $panel
+        ...
+        ->plugin(ModulesPlugin::make());
+}
+```
+
+That's it! now you are ready to start creating some filament code in your module of choice!
+
+### Installing Filament in a module
+
+If you don't have a module already, you can generate one using the `module:make` command like so:
+
+```bash
+php artisan module:make MyModule
+```
+
+Next, run the `module:filament:install` command to generate the necessary Filament files and directories in your module:
+
+```bash
+php artisan module:filament:install MyModule
+```
+
+This will guide you interactively on whether you want to organize your code in clusters, and whether you would like to
+create a default cluster.
+At the end of this installation, you will have the following structure in your module:
+
+- Modules
+    - MyModule
+        - App
+            - Filament
+                - Clusters
+                    - MyModule
+                        - Pages
+                        - Resources
+                        - Widgets
+                    - **MyModule.php**
+                - Pages
+                - Resources
+                - Widgets
+                - **MyModulePlugin.php**
+
+As you can see, there are two main files generated: The plugin class and optionally the cluster class. After generation,
+you are free to make any modifications to these classes as you may see fit.
+
+The **plugin** will be loaded automatically unless the configuration is set otherwise. As a result, it will also load
+all its clusters automatically.
+
+Your module is now ready to be used in your Filament Panel. Use the following commands during development to generate
+new resources, pages, widgets and clusters in your module:
+
+### Creating a new resource
+
+```bash
+php artisan module:make:filament-resource
+```
+
+Follow the interactive prompts to create a new resource in your module.
+
+### Creating a new page
+
+```bash
+php artisan module:make:filament-page
 ```
 
+Follow the interactive prompts to create a new page in your module.
+
+###Creating a new widget
+
+```bash
+php artisan module:make:filament-widget
+```
+
+Follow the interactive prompts to create a new widget in your module.
+
+### Creating a new cluster
+
+```bash
+php artisan module:make:filament-cluster
+```
+
+Follow the interactive prompts to create a new cluster in your module.
+
+### Creating a new plugin
+
+```bash
+php artisan module:make:filament-plugin
+```
+
+Follow the interactive prompts to create a new plugin in your module.
+
 ## Testing
 
 ```bash