diff --git a/content/docs/customizations.md b/content/docs/customizations.md index e2f4fc2..8256b6d 100644 --- a/content/docs/customizations.md +++ b/content/docs/customizations.md @@ -3,8 +3,8 @@ title: Customizations description: Learn how to add some basic customizations to your application prevTitle: 'Local Development' prevURL: '/docs/local-dev' -nextTitle: 'Upgrading' -nextURL: '/docs/upgrading' +nextTitle: 'Your Functionality' +nextURL: '/docs/your-functionality' --- # Customizations diff --git a/content/docs/guides/about.md b/content/docs/guides/about.md index 68106a8..f20fd24 100644 --- a/content/docs/guides/about.md +++ b/content/docs/guides/about.md @@ -1,10 +1,10 @@ --- title: About Guides description: Learn how you can host your website and make it live for the world to see. -nextTitle: 'Creating Themes' -nextURL: '/docs/guides/creating-themes' -prevTitle: 'Prompts' -prevURL: '/docs/prompts/create-a-role' +prevTitle: 'Create a Plugin' +prevURL: '/docs/prompts/create-plugin' +nextTitle: 'Using Filament with Volt' +nextURL: '/docs/guides/using-filament-with-volt' --- @@ -24,8 +24,7 @@ We will be adding more guides in the future, so be sure to check back on this pa ## Current Guides - - Creating Themes - - Theme Structure + - Using Filament With Volt ## What's Next? diff --git a/content/docs/guides/using-filament-with-volt.md b/content/docs/guides/using-filament-with-volt.md new file mode 100644 index 0000000..4c652ab --- /dev/null +++ b/content/docs/guides/using-filament-with-volt.md @@ -0,0 +1,31 @@ +--- +title: Using Filament With Volt +description: Learn how to use FilamentPHP with any Volt page +prevTitle: 'About Guides' +prevURL: '/docs/guides/about' +nextTitle: '' +nextURL: null +--- + +# Using Filament with Volt + +Using Filament with Wave and Volt can make your life a lot easier. In this guide we will use the example from the Your Functionality section and show you how to implement the same functionality using the Table Builder and the Form Builder. + +- [Using Filament with Volt](#using-filament-with-volt) + - [Using the Table Builder](#using-the-table-builder) + - [Using the Form Builder](#using-the-form-builder) + + +We will assume that you've already added the **database migration** and the **model** for the `projects` table in this section. Be sure to finish that section before continuing with this guide. + +## Using the Table Builder + +Looking at the **volt project page** that we created inside the theme page directory at `pages/projects/index.blade.php` we can utilize the Table builder to easily display our projects in a nice table view: + +```php + +``` + +## Using the Form Builder \ No newline at end of file diff --git a/content/docs/prompts/create-plugin.md b/content/docs/prompts/create-plugin.md index 834ac51..2aa4b15 100644 --- a/content/docs/prompts/create-plugin.md +++ b/content/docs/prompts/create-plugin.md @@ -3,8 +3,8 @@ title: Creating a Plugin description: Create a plugin using an artisan command prevTitle: 'Create a Role' prevURL: '/docs/prompts/create-role' -nextTitle: '' -nextURL: null +nextTitle: 'About Guides' +nextURL: '/docs/guides/about' --- ## Create a Plugin diff --git a/content/docs/upgrading.md b/content/docs/upgrading.md index bb0e6bd..bf21d09 100644 --- a/content/docs/upgrading.md +++ b/content/docs/upgrading.md @@ -1,8 +1,8 @@ --- title: Upgrading Wave description: Learn how to upgrade Wave -prevTitle: 'Customizations' -prevURL: '/docs/customizations' +prevTitle: 'Your Functionality' +prevURL: '/docs/your-functionality' nextTitle: 'Authentication' nextURL: '/docs/features/auth' --- diff --git a/content/docs/your-functionality.md b/content/docs/your-functionality.md index 004371b..3277312 100644 --- a/content/docs/your-functionality.md +++ b/content/docs/your-functionality.md @@ -1,52 +1,302 @@ --- title: Your Functionality description: Where should you add your own logic and functionality within Wave? -prevTitle: 'Local Development' -prevURL: '/docs/local-dev' +prevTitle: 'Customizations' +prevURL: '/docs/customizations' nextTitle: 'Upgrading' nextURL: '/docs/upgrading' --- # Your Functionality -If this is your first time using Wave, you may be asking yourself, "Where do I add my own logic and functionality". The Answer to that is pretty simple. Anywhere you want, with some considerations. +If this is your first time using Wave, you may find yourself asking, "Where do I add my own logic and functionality?" The Answer to that is pretty simple. Let's cover it below. + + +- [Your Functionality](#your-functionality) + - [Common Practice](#common-practice) + - [Recommended Approach](#recommended-approach) + - [Recommended Example](#recommended-example) + - [Using FilamentPHP](#using-filamentphp) + + ## Common Practice -Wave is a typical Laravel application, which means you can add functionality in all the familiar places like controllers, models, services, and more. There’s no wrong way to add logic to your application. If it works and you’re happy with it, feel free to keep building however you see fit. You will most-likely want to structure your code in a way that keeps everything organized and maintainable. With that said, we do have a mild recommendation that might help. +Wave is built using the popular Laravel Framework, which means you can add functionality in all the familiar places like controllers, models, services, and more. + +You will most-likely want to structure your code in a way that keeps everything organized and maintainable. With that said, we do have a small recommendation that might help. ## Recommended Approach -Because Wave utilizes Livewire Volt single-file pages, we recommend that you continue to use Single-file Volt pages for adding new functionality. Using Single-file Livewire Volt pages will help keep your code organized and make future upgrades more manageable. While this approach simplifies development, you’re completely free to choose how to structure your application based on your preferences and project needs. +Because Wave utilizes single-file volt pages, we recommend using single-file Livewire Volt pages when adding new functionality. It will help keep your code organized and make future Wave upgrades more manageable. + +If you follow this recommended approach, it may still be beneficial to abstract any complex logic into a service class or controller to keep the code within your **single-file volt page** clean and maintainable. -If you choose to follow the recommended approach and build your functionality using Volt pages, it can still be beneficial to abstract any complex logic out of the single-file Volt page itself. When the logic becomes lengthy, consider moving it to a service class or controller to keep your code clean and maintainable. This allows you to simplify your Volt page, making it easier to locate and modify functionality. +> While this approach simplifies development, you’re completely free to choose how to structure your application. The bottom line is that there’s no wrong way to add logic to your application. ## Recommended Example -Say that you want to create a `projects` table and allow your customers to create new projects. You could do this by simply creating a new model: +It may be helpful to see an example. In this example we will create a projects page where users can view, add, or delete projects. Here's a screenshot of the functional projects page that we will create. -``` -Projects Model -``` +Project List View -And then inside your `resources/themes/theme_name/pages` folder, you can add a new folder called `projects` and inside this folder you'll add an `index.blade.php`. Here is an example of how this page might look. -``` +First we'll create the **migration** and the **model**. Add the following files to your Wave project: + +**database/migrations/create\_projects\_table.php** + +```php +use Illuminate\Database\Migrations\Migration; +use Illuminate\Database\Schema\Blueprint; +use Illuminate\Support\Facades\Schema; + +class CreateProjectsTable extends Migration +{ + public function up() + { + Schema::create('projects', function (Blueprint $table) { + $table->id(); + $table->string('name'); + $table->text('description')->nullable(); + $table->date('start_date')->nullable(); + $table->date('end_date')->nullable(); + $table->foreignId('user_id')->constrained()->onDelete('cascade'); + $table->timestamps(); + }); + } + public function down() + { + Schema::dropIfExists('projects'); + } +} ``` -As you can see, this page will output all the projects that belong to this specific user. +**app/Models/Project.php** +```php +namespace App\Models; + +use Illuminate\Database\Eloquent\Model; + +class Project extends Model +{ + protected $fillable = [ + 'name', + 'description', + 'start_date', + 'end_date', + 'user_id', + ]; + + protected $casts = [ + 'start_date' => 'date', + 'end_date' => 'date', + ]; + + public function user() + { + return $this->belongsTo(User::class); + } +} ``` + +Make sure to run `php artisan migrate` to add the project table. + +Next, let's create the **volt page** to list our projects. Add the following file contents: + +**resources/themes/{theme}/pages/projects/index.blade.php** + +```php +projects = auth()->user()->projects()->latest()->get(); + } + + public function deleteProject(Project $project) + { + $project->delete(); + $this->projects = auth()->user()->projects()->latest()->get(); + } + } +?> + + + @volt('projects') + + +
+ + New Project +
+ + @if($projects->isEmpty()) +
+

You don't have any projects yet.

+
+ @else +
+ + + + + + + + + + + + @foreach($projects as $project) + + + + + + + + @endforeach + +
NameDescriptionStart DateEnd DateActions
{{ $project->name }}{{ Str::limit($project->description, 50) }}{{ $project->start_date ? $project->start_date->format('Y-m-d') : 'N/A' }}{{ $project->end_date ? $project->end_date->format('Y-m-d') : 'N/A' }} + Edit + +
+
+ @endif +
+ @endvolt +
``` -Next, perhaps you want to create a way for the user to create a new project, next inside the same `projects` folder, you can add a new file called `create.blade.php`, this might look something like this: +In order for the code above to work, you will need to add the `projects()` method to your `App/Models/User.php` +```php +public function projects() +{ + return $this->hasMany(Project::class); +} ``` -create page + +Visit your application URL at `app_url.test/projects` and you will see a screen like the following: + +Projects Empty + +This page will output all the projects that belong to this specific user, but right now there are no projects. But, we can easily add a **create project volt page** to allow us to create projects. Create another file inside the `projects` folder called `create.blade.php`, with the following contents: + +**resources/themes/{theme}/pages/projects/create.blade.php** + +```php +validate(); + + $project = auth()->user()->projects()->create($validated); + + session()->flash('message', 'Project created successfully.'); + + $this->redirect(route('projects')); + } + } +?> + + + @volt('projects.create') + + + + +
+ +
+ +
+
+ + + @error('name') {{ $message }} @enderror +
+
+ + + @error('description') {{ $message }} @enderror +
+ +
+ + + @error('start_date') {{ $message }} @enderror +
+ +
+ + + @error('end_date') {{ $message }} @enderror +
+ +
+ + Create Project + +
+
+
+ @endvolt +
``` -Now, if you navigate to `app_url.test/projects/create` the authenticated user will be able to create a simple project. They can also visit your application at `app_url.test/projects` to view/edit/delete their existing projects. +Thsi will allow us to navigate to `app_url.test/projects/create`, where we can create a new project. + +New Project Create + +After creating a few new projects, you can navigate back the `app_url.test/projects` and see a list of these new projects. + +Project List View + +This is just an example of how you can add custom logic for your application. But again, there is no right or wrong way to do this. However you're most comfortable adding and maintaining the logic in your app is the way to go. -This is just an example of how you can add custom logic for your application. Obviously there is no right or wrong way to do this. It is whatever way you feel the most comfortable adding and maintaining the logic in your application. +## Using FilamentPHP +FilamentPHP is used for the Admin section of Wave; however, it also provides a collection of components that we can utilize to make building our application even easier. This includes the Table Builder and the Form Builder. If you want to see how we can use the Table and Form Builder using this same Project Example, be sure to visit the Using Filament With Volt Guide. \ No newline at end of file diff --git a/includes/docs-sidebar.html b/includes/docs-sidebar.html index d0e8c59..20dd036 100644 --- a/includes/docs-sidebar.html +++ b/includes/docs-sidebar.html @@ -260,6 +260,42 @@ +
+
+ Guides + +
+ +