diff --git a/packages/app/docs/02-getting-started.md b/packages/app/docs/02-getting-started.md index 5fde6b1bad..956dd02cf6 100644 --- a/packages/app/docs/02-getting-started.md +++ b/packages/app/docs/02-getting-started.md @@ -635,13 +635,13 @@ public function table(Table $table): Table ## Introducing widgets -Filament has "widgets" - which are components that you can use to display information, especially statistics. Widgets typically get added to the Dashboard of the app, but you can add them to any page you wish, including resource pages. Filament includes built-in widgets, like the [stats widget](../dashboard/stats) to render important statistics in a simple card, [chart widget](../dashboard/charts) which can render an interactive chart, and [table widget](../dashboard/tables) which allows you to easily embed the table builder. +Filament has "widgets" - which are components that you can use to display information, especially statistics. Widgets typically get added to the Dashboard of the app, but you can add them to any page you wish, including resource pages. Filament includes built-in widgets, like the [stats widget](../widgets/stats) to render important statistics in a simple card, [chart widget](../dashboard/charts) which can render an interactive chart, and [table widget](../app/dashboard#table-widgets) which allows you to easily embed the table builder. In our system, we could add statistics for the type of patient, as well as treatments that are administered over time. ### Creating a stats widget -Let's create a [stats widget](../dashboard/stats) to render patient types: +Let's create a [stats widget](../widgets/stats) to render patient types: ```bash php artisan make:filament-widget PatientTypeOverview --stats-overview diff --git a/packages/app/docs/04-pages.md b/packages/app/docs/04-pages.md index c5460969cc..a1b4febef0 100644 --- a/packages/app/docs/04-pages.md +++ b/packages/app/docs/04-pages.md @@ -128,7 +128,7 @@ protected function getHeaderWidgetsColumns(): int | array } ``` -This pairs well with [responsive widget widths](dashboard/getting-started#responsive-widget-widths). +This pairs well with [responsive widget widths](dashboard#responsive-widget-widths). ## Customization diff --git a/packages/app/docs/05-dashboard/01-getting-started.md b/packages/app/docs/05-dashboard.md similarity index 75% rename from packages/app/docs/05-dashboard/01-getting-started.md rename to packages/app/docs/05-dashboard.md index 204c9b513d..67bc4ad259 100644 --- a/packages/app/docs/05-dashboard/01-getting-started.md +++ b/packages/app/docs/05-dashboard.md @@ -4,19 +4,11 @@ title: Getting started Filament allows you to build dynamic dashboards, comprised of "widget" cards, very easily. -Widgets are pure [Livewire](https://laravel-livewire.com) components, so may use any features of that package. +To learn how to use widgets, you should visit the [widgets documentation](../widgets/overview). There, you will find a list of [available widgets](../widgets/overview#available-widgets) that you can add to your app, and details on how to build custom widgets. -Widgets may also be used on [resource pages](../resources/widgets) or other [custom pages](../pages#widgets). +You may also [create your own custom widgets](#custom-widgets) which can then have a consistent design with Filament's pre-built widgets. -## Available widgets - -Filament ships with a few pre-built widgets, as well as the ability to create [custom widgets](#custom-widgets): - -- [Stats](stats) widgets display any data, often numeric data, within cards in a row. -- [Chart](charts) widgets display numeric data in a visual chart. -- [Table](tables) widgets render data in a table, which supports sorting, searching, filtering, actions, and everything else included within the [table builder](../../tables). - -You may also [create your own custom widgets](#custom-widgets). +The following document will explain how to use these widgets to assemble a dashboard using the app framework. ## Sorting widgets @@ -89,17 +81,16 @@ public static function canView(): bool } ``` -## Disabling the default widgets +## Table widgets -By default, two widgets are displayed on the dashboard. These widgets can be disabled by updating the `widgets.register` property of the [configuration](installation#publishing-configuration) file: +You may easily add tables to your dashboard. Start by creating a widget with the command: -```php -'widgets' => [ - // ... - 'register' => [], -], +```bash +php artisan make:filament-widget LatestOrders --table ``` +You may now [customize the table](../tables/getting-started) by editing the widget file. + ## Custom widgets To get started building a `BlogPostsOverview` widget: @@ -110,6 +101,17 @@ php artisan make:filament-widget BlogPostsOverview This command will create two files - a widget class in the `/Widgets` directory of the Filament directory, and a view in the `/widgets` directory of the Filament views directory. +## Disabling the default widgets + +By default, two widgets are displayed on the dashboard. These widgets can be disabled by updating the `widgets.register` property of the [configuration](installation#publishing-configuration) file: + +```php +'widgets' => [ + // ... + 'register' => [], +], +``` + ## Customizing the dashboard page If you want to customize the dashboard class, for example to [change the number of widget columns](#customizing-widget-width), create a new file at `app/Filament/Pages/Dashboard.php`: @@ -135,3 +137,13 @@ Finally, remove the original `Dashboard` class from the [configuration file](ins 'register' => [], ], ``` + +### Creating more than one dashboard + +If you want to create more than one dashboard, you can do so by repeating the process described above. Creating new pages that extend the `Dashboard` class will allow you to create as many dashboards as you need. + +You may change the title of the dashboard by overriding the `$title` property: + +```php +protected static ?string $title = 'Finance dashboard'; +``` diff --git a/packages/app/docs/05-dashboard/04-tables.md b/packages/app/docs/05-dashboard/04-tables.md deleted file mode 100644 index 8a5e805d59..0000000000 --- a/packages/app/docs/05-dashboard/04-tables.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Tables ---- - -Filament comes with a "table" widget template, which you can use to display a table of data without needing to write a custom view. - -Start by creating a widget with the command: - -```bash -php artisan make:filament-widget LatestOrders --table -``` - -Then update the `getTableQuery()` and `getTableColumns()` methods to return the data query and columns you want to display: - -```php -latest(); - } - - protected function getTableColumns(): array - { - return [ - Tables\Columns\TextColumn::make('id'), - Tables\Columns\TextColumn::make('customer.name') - ->label('Customer'), - ]; - } -} -``` - -Now, check out your widget in the dashboard. - -Table widgets support all features of the [Table Builder](../../tables), including [filters](../../tables/filters) and [actions](../../tables/actions). diff --git a/packages/app/src/Resources/Pages/EditRecord.php b/packages/app/src/Resources/Pages/EditRecord.php index f38692c5c9..870efa7dec 100644 --- a/packages/app/src/Resources/Pages/EditRecord.php +++ b/packages/app/src/Resources/Pages/EditRecord.php @@ -4,11 +4,13 @@ namespace Filament\Resources\Pages; use Filament\Actions\Action; use Filament\Actions\ActionGroup; +use Filament\Actions\Contracts\HasActions; use Filament\Actions\DeleteAction; use Filament\Actions\ForceDeleteAction; use Filament\Actions\ReplicateAction; use Filament\Actions\RestoreAction; use Filament\Actions\ViewAction; +use Filament\Forms\Contracts\HasForms; use Filament\Forms\Form; use Filament\Notifications\Notification; use Filament\Pages\Concerns\InteractsWithFormActions; diff --git a/packages/tables/docs/02-getting-started.md b/packages/tables/docs/02-getting-started.md index 268e7df3f7..7463f1b87a 100644 --- a/packages/tables/docs/02-getting-started.md +++ b/packages/tables/docs/02-getting-started.md @@ -2,7 +2,7 @@ title: Getting started --- -Filament's table package allows you to [add an interactive datatable to any Livewire component](adding-a-table-to-a-livewire-component). It's also used within other Filament packages, such as the [app framework](../app) for displaying [app resources](../app/resources) and [relation managers](../app/resources/relation-managers), as well as for the [table widget](../widgets/table). Learning the feature's of the table builder will be incredibly time-saving when both building your own custom Livewire tables and using Filament's other packages. +Filament's table package allows you to [add an interactive datatable to any Livewire component](adding-a-table-to-a-livewire-component). It's also used within other Filament packages, such as the [app framework](../app) for displaying [app resources](../app/resources) and [relation managers](../app/resources/relation-managers), as well as for the [table widget](../app/dashboard#table-widgets). Learning the feature's of the table builder will be incredibly time-saving when both building your own custom Livewire tables and using Filament's other packages. This guide will walk you through the basics of building tables with Filament's table package. If you're planning to add a new table to your own Livewire component, you should [do that first](adding-a-table-to-a-livewire-component) and then come back. If you're adding a table to an [app resource](../app/resources), or another Filament package, you're ready to go! diff --git a/packages/widgets/docs/02-overview.md b/packages/widgets/docs/02-overview.md new file mode 100644 index 0000000000..88e4b88e07 --- /dev/null +++ b/packages/widgets/docs/02-overview.md @@ -0,0 +1,12 @@ +--- +title: Overview +--- + +Widgets are pre-built [Laravel Livewire](https://laravel-livewire.com) components that allow you to quickly assemble interactive dashboards for your application. + +## Available widgets + +Filament ships with these widgets: + +- [Stats overview](stats-overview) widgets display any data, often numeric data, within cards in a row. +- [Chart](charts) widgets display numeric data in a visual chart. \ No newline at end of file diff --git a/packages/app/docs/05-dashboard/02-stats.md b/packages/widgets/docs/03-stats-overview.md similarity index 99% rename from packages/app/docs/05-dashboard/02-stats.md rename to packages/widgets/docs/03-stats-overview.md index f2b72ba887..3bdd9a53c9 100644 --- a/packages/app/docs/05-dashboard/02-stats.md +++ b/packages/widgets/docs/03-stats-overview.md @@ -1,5 +1,5 @@ --- -title: Stats +title: Stats overview widgets --- ## Getting started diff --git a/packages/app/docs/05-dashboard/03-charts.md b/packages/widgets/docs/04-charts.md similarity index 99% rename from packages/app/docs/05-dashboard/03-charts.md rename to packages/widgets/docs/04-charts.md index 588113ceb8..5df32b674b 100644 --- a/packages/app/docs/05-dashboard/03-charts.md +++ b/packages/widgets/docs/04-charts.md @@ -1,5 +1,5 @@ --- -title: Charts +title: Chart widgets --- ## Getting started diff --git a/packages/widgets/docs/05-adding-a-widget-to-a-blade-view.md b/packages/widgets/docs/05-adding-a-widget-to-a-blade-view.md new file mode 100644 index 0000000000..6552d70db2 --- /dev/null +++ b/packages/widgets/docs/05-adding-a-widget-to-a-blade-view.md @@ -0,0 +1,11 @@ +--- +title: Adding a widget to a Blade view +--- + +Since widgets are Livewire components, you can easily render a widget in any Blade view using the `@livewire` directive: + +```blade +
+ @livewire(\App\Http\Livewire\Dashboard\PostsChart::class) +
+``` \ No newline at end of file diff --git a/packages/widgets/src/BarChartWidget.php b/packages/widgets/src/BarChartWidget.php index f883d55552..809fc28c1d 100644 --- a/packages/widgets/src/BarChartWidget.php +++ b/packages/widgets/src/BarChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class BarChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/src/BubbleChartWidget.php b/packages/widgets/src/BubbleChartWidget.php index 14a5f5eeef..7c571f5ca5 100644 --- a/packages/widgets/src/BubbleChartWidget.php +++ b/packages/widgets/src/BubbleChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class BubbleChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/src/ChartWidget.php b/packages/widgets/src/ChartWidget.php index b1d210445c..3cc78ba823 100644 --- a/packages/widgets/src/ChartWidget.php +++ b/packages/widgets/src/ChartWidget.php @@ -2,7 +2,7 @@ namespace Filament\Widgets; -class ChartWidget extends Widget +abstract class ChartWidget extends Widget { use Concerns\CanPoll; @@ -34,6 +34,8 @@ class ChartWidget extends Widget $this->dataChecksum = $this->generateDataChecksum(); } + abstract protected function getType(): string; + protected function generateDataChecksum(): string { return md5(json_encode($this->getCachedData())); diff --git a/packages/widgets/src/Commands/MakeWidgetCommand.php b/packages/widgets/src/Commands/MakeWidgetCommand.php index b4a13a18fa..7becf9e901 100644 --- a/packages/widgets/src/Commands/MakeWidgetCommand.php +++ b/packages/widgets/src/Commands/MakeWidgetCommand.php @@ -133,7 +133,16 @@ class MakeWidgetCommand extends Command $this->copyStubToApp('ChartWidget', $path, [ 'class' => $widgetClass, 'namespace' => filled($resource) ? "{$resourceNamespace}\\{$resource}\\Widgets" . ($widgetNamespace !== '' ? "\\{$widgetNamespace}" : '') : $namespace . ($widgetNamespace !== '' ? "\\{$widgetNamespace}" : ''), - 'chart' => Str::studly($chart), + 'type' => match ($chart) { + 'Bar chart' => 'bar', + 'Bubble chart' => 'bubble', + 'Doughnut chart' => 'doughnut', + 'Line chart' => 'line', + 'Pie chart' => 'pie', + 'Polar area chart' => 'polarArea', + 'Radar chart' => 'radar', + 'Scatter chart' => 'scatter', + }, ]); } elseif ($this->option('table')) { $this->copyStubToApp('TableWidget', $path, [ diff --git a/packages/widgets/src/DoughnutChartWidget.php b/packages/widgets/src/DoughnutChartWidget.php index 114e461b18..631520d1b7 100644 --- a/packages/widgets/src/DoughnutChartWidget.php +++ b/packages/widgets/src/DoughnutChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class DoughnutChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/src/LineChartWidget.php b/packages/widgets/src/LineChartWidget.php index b005d573f7..367f4d5a23 100644 --- a/packages/widgets/src/LineChartWidget.php +++ b/packages/widgets/src/LineChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class LineChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/src/PieChartWidget.php b/packages/widgets/src/PieChartWidget.php index 8ca816eeca..4c0443146b 100644 --- a/packages/widgets/src/PieChartWidget.php +++ b/packages/widgets/src/PieChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class PieChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/src/PolarAreaChartWidget.php b/packages/widgets/src/PolarAreaChartWidget.php index f2d18edd10..89b96b1b95 100644 --- a/packages/widgets/src/PolarAreaChartWidget.php +++ b/packages/widgets/src/PolarAreaChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class PolarAreaChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/src/RadarChartWidget.php b/packages/widgets/src/RadarChartWidget.php index 50b5db800b..34139b91b7 100644 --- a/packages/widgets/src/RadarChartWidget.php +++ b/packages/widgets/src/RadarChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class RadarChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/src/ScatterChartWidget.php b/packages/widgets/src/ScatterChartWidget.php index 396d9b0b56..cce975d8da 100644 --- a/packages/widgets/src/ScatterChartWidget.php +++ b/packages/widgets/src/ScatterChartWidget.php @@ -2,6 +2,9 @@ namespace Filament\Widgets; +/** + * @deprecated Extend `ChartWidget` instead and define the `getType()` method. + */ class ScatterChartWidget extends ChartWidget { protected function getType(): string diff --git a/packages/widgets/stubs/ChartWidget.stub b/packages/widgets/stubs/ChartWidget.stub index 2a0a34558a..65332d835a 100644 --- a/packages/widgets/stubs/ChartWidget.stub +++ b/packages/widgets/stubs/ChartWidget.stub @@ -2,9 +2,9 @@ namespace {{ namespace }}; -use Filament\Widgets\{{ chart }}Widget; +use Filament\Widgets\ChartWidget; -class {{ class }} extends {{ chart }}Widget +class {{ class }} extends ChartWidget { protected static ?string $heading = 'Chart'; @@ -14,4 +14,9 @@ class {{ class }} extends {{ chart }}Widget // ]; } + + protected function getType(): string + { + return '{{ type }}'; + } }