mirror of
https://github.com/filamentphp/filament.git
synced 2026-09-24 15:42:09 +08:00
rearrange actions docs
This commit is contained in:
@@ -15,7 +15,7 @@ protected function mutateFormDataBeforeCreate(array $data): array
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/create#customizing-data-before-saving).
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/create#customizing-data-before-saving).
|
||||
|
||||
## Customizing the creation process
|
||||
|
||||
@@ -30,7 +30,7 @@ protected function handleRecordCreation(array $data): Model
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/create#customizing-the-creation-process).
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/create#customizing-the-creation-process).
|
||||
|
||||
## Customizing redirects
|
||||
|
||||
@@ -69,7 +69,7 @@ protected function getCreatedNotificationTitle(): ?string
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/create#customizing-the-save-notification).
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/create#customizing-the-save-notification).
|
||||
|
||||
You may customize the entire notification by overriding the `getCreatedNotification()` method on the create page class:
|
||||
|
||||
@@ -191,7 +191,7 @@ class CreateUser extends CreateRecord
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/create#lifecycle-hooks).
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/create#lifecycle-hooks).
|
||||
|
||||
## Halting the creation process
|
||||
|
||||
@@ -221,7 +221,7 @@ protected function beforeCreate(): void
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/create#halting-the-creation-process).
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/create#halting-the-creation-process).
|
||||
|
||||
## Authorization
|
||||
|
||||
@@ -294,7 +294,7 @@ protected function getSteps(): array
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/create#using-a-wizard).
|
||||
Alternatively, if you're creating records in a modal action, check out the [Actions documentation](../../actions/create#using-a-wizard).
|
||||
|
||||
Now, create a new record to see your wizard in action! Edit will still use the form defined within the resource class.
|
||||
|
||||
@@ -389,7 +389,7 @@ protected function getHeaderActions(): array
|
||||
}
|
||||
```
|
||||
|
||||
The "importer" class [needs to be created](../../actions/prebuilt-actions/import#creating-an-importer) to tell Filament how to import each row of the CSV. You can learn everything about the `ImportAction` in the [Actions documentation](../../actions/prebuilt-actions/import).
|
||||
The "importer" class [needs to be created](../../actions/import#creating-an-importer) to tell Filament how to import each row of the CSV. You can learn everything about the `ImportAction` in the [Actions documentation](../../actions/import).
|
||||
|
||||
## Custom actions
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ protected function mutateFormDataBeforeFill(array $data): array
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/edit#customizing-data-before-filling-the-form).
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/edit#customizing-data-before-filling-the-form).
|
||||
|
||||
## Customizing data before saving
|
||||
|
||||
@@ -30,7 +30,7 @@ protected function mutateFormDataBeforeSave(array $data): array
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/edit#customizing-data-before-saving).
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/edit#customizing-data-before-saving).
|
||||
|
||||
## Customizing the saving process
|
||||
|
||||
@@ -47,7 +47,7 @@ protected function handleRecordUpdate(Model $record, array $data): Model
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/edit#customizing-the-saving-process).
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/edit#customizing-the-saving-process).
|
||||
|
||||
## Customizing redirects
|
||||
|
||||
@@ -95,7 +95,7 @@ protected function getSavedNotificationTitle(): ?string
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/edit#customizing-the-save-notification).
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/edit#customizing-the-save-notification).
|
||||
|
||||
You may customize the entire notification by overriding the `getSavedNotification()` method on the edit page class:
|
||||
|
||||
@@ -176,7 +176,7 @@ class EditUser extends EditRecord
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/edit#lifecycle-hooks).
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/edit#lifecycle-hooks).
|
||||
|
||||
## Saving a part of the form independently
|
||||
|
||||
@@ -237,7 +237,7 @@ protected function beforeSave(): void
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/edit#halting-the-saving-process).
|
||||
Alternatively, if you're editing records in a modal action, check out the [Actions documentation](../../actions/edit#halting-the-saving-process).
|
||||
|
||||
## Authorization
|
||||
|
||||
|
||||
@@ -91,7 +91,7 @@ protected function mutateFormDataBeforeFill(array $data): array
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, if you're viewing records in a modal action, check out the [Actions documentation](../../actions/prebuilt-actions/view#customizing-data-before-filling-the-form).
|
||||
Alternatively, if you're viewing records in a modal action, check out the [Actions documentation](../../actions/view#customizing-data-before-filling-the-form).
|
||||
|
||||
## Lifecycle hooks
|
||||
|
||||
|
||||
@@ -208,7 +208,7 @@ Please ensure that any pivot attributes are listed in the `withPivot()` method o
|
||||
|
||||
### Customizing the `CreateAction`
|
||||
|
||||
To learn how to customize the `CreateAction`, including mutating the form data, changing the notification, and adding lifecycle hooks, please see the [Actions documentation](../../actions/prebuilt-actions/create).
|
||||
To learn how to customize the `CreateAction`, including mutating the form data, changing the notification, and adding lifecycle hooks, please see the [Actions documentation](../../actions/create).
|
||||
|
||||
## Editing related records
|
||||
|
||||
@@ -235,7 +235,7 @@ Please ensure that any pivot attributes are listed in the `withPivot()` method o
|
||||
|
||||
### Customizing the `EditAction`
|
||||
|
||||
To learn how to customize the `EditAction`, including mutating the form data, changing the notification, and adding lifecycle hooks, please see the [Actions documentation](../../actions/prebuilt-actions/edit).
|
||||
To learn how to customize the `EditAction`, including mutating the form data, changing the notification, and adding lifecycle hooks, please see the [Actions documentation](../../actions/edit).
|
||||
|
||||
## Attaching and detaching records
|
||||
|
||||
@@ -540,11 +540,11 @@ public function table(Table $table): Table
|
||||
|
||||
### Customizing the `DeleteAction`
|
||||
|
||||
To learn how to customize the `DeleteAction`, including changing the notification and adding lifecycle hooks, please see the [Actions documentation](../../actions/prebuilt-actions/delete).
|
||||
To learn how to customize the `DeleteAction`, including changing the notification and adding lifecycle hooks, please see the [Actions documentation](../../actions/delete).
|
||||
|
||||
## Importing related records
|
||||
|
||||
The [`ImportAction`](../../actions/prebuilt-actions/import) can be added to the header of a relation manager to import records. In this case, you probably want to tell the importer which owner these new records belong to. You can use [import options](../../actions/prebuilt-actions/import#using-import-options) to pass through the ID of the owner record:
|
||||
The [`ImportAction`](../../actions/import) can be added to the header of a relation manager to import records. In this case, you probably want to tell the importer which owner these new records belong to. You can use [import options](../../actions/import#using-import-options) to pass through the ID of the owner record:
|
||||
|
||||
```php
|
||||
ImportAction::make()
|
||||
|
||||
@@ -92,7 +92,7 @@ public static function getGlobalSearchResultActions(Model $record): array
|
||||
}
|
||||
```
|
||||
|
||||
You can learn more about how to style action buttons [here](../../actions/trigger-button).
|
||||
You can learn more about how to style action buttons [here](../../actions/overview).
|
||||
|
||||
### Opening URLs from global search actions
|
||||
|
||||
|
||||
@@ -112,7 +112,7 @@ public function table(Table $table): Table
|
||||
|
||||
In this example, we have a `$category` property which holds a `Category` model instance. The category has a relationship named `products`. We use a function to return the relationship instance. This is a many-to-many relationship, so the inverse relationship is called `categories`, and is defined on the `Product` model. We just need to pass the name of this relationship to the `inverseRelationship()` method, not the whole instance.
|
||||
|
||||
Now that the table is using a relationship instead of a plain Eloquent query, all actions will be performed on the relationship instead of the query. For example, if you use a [`CreateAction`](../actions/prebuilt-actions/create), the new product will be automatically attached to the category.
|
||||
Now that the table is using a relationship instead of a plain Eloquent query, all actions will be performed on the relationship instead of the query. For example, if you use a [`CreateAction`](../actions/create), the new product will be automatically attached to the category.
|
||||
|
||||
If your relationship uses a pivot table, you can use all pivot columns as if they were normal columns on your table, as long as they are listed in the `withPivot()` method of the relationship *and* inverse relationship definition.
|
||||
|
||||
|
||||
@@ -192,7 +192,7 @@ In Filament v3, import and export jobs were retries continuously for 24 hours if
|
||||
|
||||
In v4, they are retried 3 times with a 60 second backoff between each retry.
|
||||
|
||||
This behaviour can be customized in the [importer](prebuilt-actions/import#customizing-the-import-job-retries) and [exporter](prebuilt-actions/export#customizing-the-export-job-retries) classes.
|
||||
This behaviour can be customized in the [importer](import#customizing-the-import-job-retries) and [exporter](export#customizing-the-export-job-retries) classes.
|
||||
</Disclosure>
|
||||
|
||||
<Disclosure x-show="packages.includes('widgets')">
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
title: Overview
|
||||
---
|
||||
import AutoScreenshot from "@components/AutoScreenshot.astro"
|
||||
|
||||
## Introduction
|
||||
|
||||
"Action" is a word that is used quite a bit within the Laravel community. Traditionally, action PHP classes handle "doing" something in your application's business logic. For instance, logging a user in, sending an email, or creating a new user record in the database.
|
||||
|
||||
@@ -47,91 +50,455 @@ Action::make('edit')
|
||||
|
||||
The entire look of the action's trigger button and the modal is customizable using fluent PHP methods. We provide a sensible and consistent styling for the UI, but all of this is customizable with CSS.
|
||||
|
||||
## Types of action
|
||||
## Available actions
|
||||
|
||||
The concept of "actions" is used throughout Filament in many contexts. Some contexts don't support opening modals from actions - they can only open a URL, call a public Livewire method, or dispatch a Livewire event. Additionally, different contexts use different action PHP classes since they provide the developer context-aware data that is appropriate to that use-case.
|
||||
Filament includes several actions that you can add to your app. Their aim is to simplify the most common Eloquent-related actions:
|
||||
|
||||
### Custom Livewire component actions
|
||||
- [Create](create)
|
||||
- [Edit](edit)
|
||||
- [View](view)
|
||||
- [Delete](delete)
|
||||
- [Replicate](replicate)
|
||||
- [Force-delete](force-delete)
|
||||
- [Restore](restore)
|
||||
- [Import](import)
|
||||
- [Export](export)
|
||||
|
||||
You can add an action to any Livewire component in your app, or even a page in a [panel](../panels/pages).
|
||||
## Choosing a trigger style
|
||||
|
||||
These actions use the `Filament\Actions\Action` class. They can open a modal if you choose, or even just a URL.
|
||||
Out of the box, action triggers have 4 styles - "button", "link", "icon button", and "badge".
|
||||
|
||||
If you're looking to add an action to a Livewire component, [visit this page](adding-an-action-to-a-livewire-component) in the docs. If you want to add an action to the header of a page in a panel, [visit this page](../panels/pages#header-actions) instead.
|
||||
|
||||
### Table actions
|
||||
|
||||
Filament's tables also use actions. Actions can be added to the end of any table row, or even in the header of a table. For instance, you may want an action to "create" a new record in the header, and then "edit" and "delete" actions on each row. Additionally, actions can be added to any table column, such that each cell in that column is a trigger for your action.
|
||||
|
||||
These actions use the `Filament\Actions\Action` class. They can open a modal if you choose, or even just a URL.
|
||||
|
||||
If you're looking to add an action to a table in your app, [visit this page](../tables/actions) in the docs.
|
||||
|
||||
#### Table bulk actions
|
||||
|
||||
Tables also support "bulk actions". These can be used when the user selects rows in the table. Traditionally, when rows are selected, a "bulk actions" button appears in the top left corner of the table. When the user clicks this button, they are presented with a dropdown menu of actions to choose from. Bulk actions may also be added to the header of a table, next to other header actions. In this case, bulk action trigger buttons are disabled until the user selects table rows.
|
||||
|
||||
These actions use the `Filament\Actions\BulkAction` class. They can open modals if you choose.
|
||||
|
||||
If you're looking to add a bulk action to a table in your app, [visit this page](../tables/actions#bulk-actions) in the docs.
|
||||
|
||||
### Form component actions
|
||||
|
||||
Form components can contain actions. A good use case for actions inside form components would be with a select field, and an action button to "create" a new record. When you click on the button, a modal opens to collect the new record's data. When the modal form is submitted, the new record is created in the database, and the select field is filled with the newly created record. Fortunately, [this case is handled for you out of the box](../forms/fields/select#creating-new-records), but it's a good example of how form component actions can be powerful.
|
||||
|
||||
These actions use the `Filament\Forms\Components\Actions\Action` class. They can open a modal if you choose, or even just a URL.
|
||||
|
||||
If you're looking to add an action to a form component in your app, [visit this page](../forms/actions) in the docs.
|
||||
|
||||
### Infolist component actions
|
||||
|
||||
Infolist components can contain actions. These use the `Filament\Infolists\Components\Actions\Action` class. They can open a modal if you choose, or even just a URL.
|
||||
|
||||
If you're looking to add an action to an infolist component in your app, [visit this page](../infolists/actions) in the docs.
|
||||
|
||||
### Notification actions
|
||||
|
||||
When you [send notifications](../notifications/overview), you can add actions. These buttons are rendered below the content of the notification. For example, a notification to alert the user that they have a new message should contain an action button that opens the conversation thread.
|
||||
|
||||
These actions use the `Filament\Notifications\Actions\Action` class. They aren't able to open modals, but they can open a URL or dispatch a Livewire event.
|
||||
|
||||
If you're looking to add an action to a notification in your app, [visit this page](../notifications/overview#adding-actions-to-notifications) in the docs.
|
||||
|
||||
### Global search result actions
|
||||
|
||||
In the Panel Builder, there is a [global search](../panels/resources/global-search) field that allows you to search all resources in your app from one place. When you click on a search result, it leads you to the resource page for that record. However, you may add additional actions below each global search result. For example, you may want both "Edit" and "View" options for a client search result, so the user can quickly edit their profile as well as view it in read-only mode.
|
||||
|
||||
These actions use the `Filament\GlobalSearch\Actions\Action` class. They aren't able to open modals, but they can open a URL or dispatch a Livewire event.
|
||||
|
||||
If you're looking to add an action to a global search result in a panel, [visit this page](../panels/resources/global-search#adding-actions-to-global-search-results) in the docs.
|
||||
|
||||
## Prebuilt actions
|
||||
|
||||
Filament includes several prebuilt actions that you can add to your app. Their aim is to simplify the most common Eloquent-related actions:
|
||||
|
||||
- [Create](prebuilt-actions/create)
|
||||
- [Edit](prebuilt-actions/edit)
|
||||
- [View](prebuilt-actions/view)
|
||||
- [Delete](prebuilt-actions/delete)
|
||||
- [Replicate](prebuilt-actions/replicate)
|
||||
- [Force-delete](prebuilt-actions/force-delete)
|
||||
- [Restore](prebuilt-actions/restore)
|
||||
- [Import](prebuilt-actions/import)
|
||||
- [Export](prebuilt-actions/export)
|
||||
|
||||
## Grouping actions
|
||||
|
||||
You may group actions together into a dropdown menu by using an `ActionGroup` object. Groups may contain many actions, or other groups:
|
||||
"Button" triggers have a background color, label, and optionally an [icon](#setting-an-icon). Usually, this is the default button style, but you can use it manually with the `button()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Actions\ActionGroup;
|
||||
|
||||
ActionGroup::make([
|
||||
Action::make('view'),
|
||||
Action::make('edit'),
|
||||
Action::make('delete'),
|
||||
])
|
||||
Action::make('edit')
|
||||
->button()
|
||||
```
|
||||
|
||||
To learn about how to group actions, see the [Grouping actions](grouping-actions) page.
|
||||
<AutoScreenshot name="actions/trigger-button/button" alt="Button trigger" version="4.x" />
|
||||
|
||||
"Link" triggers have no background color. They must have a label and optionally an [icon](#setting-an-icon). They look like a link that you might find embedded within text. You can switch to that style with the `link()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->link()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/link" alt="Link trigger" version="4.x" />
|
||||
|
||||
"Icon button" triggers are circular buttons with an [icon](#setting-an-icon) and no label. You can switch to that style with the `iconButton()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->icon('heroicon-m-pencil-square')
|
||||
->iconButton()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/icon-button" alt="Icon button trigger" version="4.x" />
|
||||
|
||||
"Badge" triggers have a background color, label, and optionally an [icon](#setting-an-icon). You can use a badge as trigger using the `badge()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->badge()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/badge" alt="Badge trigger" version="4.x" />
|
||||
|
||||
### Using an icon button on mobile devices only
|
||||
|
||||
You may want to use a button style with a label on desktop, but remove the label on mobile. This will transform it into an icon button. You can do this with the `labeledFrom()` method, passing in the responsive [breakpoint](https://tailwindcss.com/docs/responsive-design#overview) at which you want the label to be added to the button:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->icon('heroicon-m-pencil-square')
|
||||
->button()
|
||||
->labeledFrom('md')
|
||||
```
|
||||
|
||||
## Setting a label
|
||||
|
||||
By default, the label of the trigger button is generated from its name. You may customize this using the `label()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->label('Edit post')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
```
|
||||
|
||||
## Setting a color
|
||||
|
||||
Buttons may have a [color](../styling/colors) to indicate their significance:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->color('danger')
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/danger" alt="Red trigger" version="4.x" />
|
||||
|
||||
## Setting a size
|
||||
|
||||
Buttons come in 3 sizes - `Size::Small`, `Size::Medium` or `Size::Large`. You can change the size of the action's trigger using the `size()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Support\Enums\Size;
|
||||
|
||||
Action::make('create')
|
||||
->size(Size::Large)
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/large" alt="Large trigger" version="4.x" />
|
||||
|
||||
## Setting an icon
|
||||
|
||||
Buttons may have an [icon](../styling/icons) to add more detail to the UI. You can set the icon using the `icon()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->icon('heroicon-m-pencil-square')
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/icon" alt="Trigger with icon" version="4.x" />
|
||||
|
||||
You can also change the icon's position to be after the label instead of before it, using the `iconPosition()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Support\Enums\IconPosition;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->icon('heroicon-m-pencil-square')
|
||||
->iconPosition(IconPosition::After)
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/icon-after" alt="Trigger with icon after the label" version="4.x" />
|
||||
|
||||
## Authorization
|
||||
|
||||
You may conditionally show or hide actions for certain users. To do this, you can use either the `visible()` or `hidden()` methods:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->visible(auth()->user()->can('update', $this->post))
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->hidden(! auth()->user()->can('update', $this->post))
|
||||
```
|
||||
|
||||
This is useful for authorization of certain actions to only users who have permission.
|
||||
|
||||
### Disabling a button
|
||||
|
||||
If you want to disable a button instead of hiding it, you can use the `disabled()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->disabled()
|
||||
```
|
||||
|
||||
You can conditionally disable a button by passing a boolean to it:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->disabled(! auth()->user()->can('delete', $this->post))
|
||||
```
|
||||
|
||||
## Registering keybindings
|
||||
|
||||
You can attach keyboard shortcuts to trigger buttons. These use the same key codes as [Mousetrap](https://craig.is/killing/mice):
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('save')
|
||||
->action(fn () => $this->save())
|
||||
->keyBindings(['command+s', 'ctrl+s'])
|
||||
```
|
||||
|
||||
## Adding a badge to the corner of the button
|
||||
|
||||
You can add a badge to the corner of the button, to display whatever you want. It's useful for displaying a count of something, or a status indicator:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('filter')
|
||||
->iconButton()
|
||||
->icon('heroicon-m-funnel')
|
||||
->badge(5)
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/badged" alt="Trigger with badge" version="4.x" />
|
||||
|
||||
You can also pass a [color](../styling/colors) to be used for the badge:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('filter')
|
||||
->iconButton()
|
||||
->icon('heroicon-m-funnel')
|
||||
->badge(5)
|
||||
->badgeColor('success')
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/success-badged" alt="Trigger with green badge" version="4.x" />
|
||||
|
||||
## Outlined button style
|
||||
|
||||
When you're using the "button" trigger style, you might wish to make it less prominent. You could use a different [color](#setting-a-color), but sometimes you might want to make it outlined instead. You can do this with the `outlined()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->button()
|
||||
->outlined()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/outlined" alt="Outlined trigger button" version="4.x" />
|
||||
|
||||
## Adding extra HTML attributes
|
||||
|
||||
You can pass extra HTML attributes to the button which will be merged onto the outer DOM element. Pass an array of attributes to the `extraAttributes()` method, where the key is the attribute name and the value is the attribute value:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->extraAttributes([
|
||||
'title' => 'Edit this post',
|
||||
])
|
||||
```
|
||||
|
||||
If you pass CSS classes in a string, they will be merged with the default classes that already apply to the other HTML element of the button:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->extraAttributes([
|
||||
'class' => 'mx-auto my-8',
|
||||
])
|
||||
```
|
||||
|
||||
## Rate limiting actions
|
||||
|
||||
You can rate limit actions by using the `rateLimit()` method. This method accepts the number of attempts per minute that a user IP address can make. If the user exceeds this limit, the action will not run and a notification will be shown:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->rateLimit(5)
|
||||
```
|
||||
|
||||
If the action opens a modal, the rate limit will be applied when the modal is submitted.
|
||||
|
||||
If an action is opened with arguments or for a specific Eloquent record, the rate limit will apply to each unique combination of arguments or record for each action. The rate limit is also unique to the current Livewire component / page in a panel.
|
||||
|
||||
## Customizing the rate limited notification
|
||||
|
||||
When an action is rate limited, a notification is dispatched to the user, which indicates the rate limit.
|
||||
|
||||
To customize the title of this notification, use the `rateLimitedNotificationTitle()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\DeleteAction;
|
||||
|
||||
DeleteAction::make()
|
||||
->rateLimit(5)
|
||||
->rateLimitedNotificationTitle('Slow down!')
|
||||
```
|
||||
|
||||
You may customize the entire notification using the `rateLimitedNotification()` method:
|
||||
|
||||
```php
|
||||
use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;
|
||||
use Filament\Actions\DeleteAction;
|
||||
use Filament\Notifications\Notification;
|
||||
|
||||
DeleteAction::make()
|
||||
->rateLimit(5)
|
||||
->rateLimitedNotification(
|
||||
fn (TooManyRequestsException $exception): Notification => Notification::make()
|
||||
->warning()
|
||||
->title('Slow down!')
|
||||
->body("You can try deleting again in {$exception->secondsUntilAvailable} seconds."),
|
||||
)
|
||||
```
|
||||
|
||||
### Customizing the rate limit behavior
|
||||
|
||||
If you wish to customize the rate limit behavior, you can use Laravel's [rate limiting](https://laravel.com/docs/rate-limiting#basic-usage) features and Filament's [flash notifications](../notifications/overview) together in the action.
|
||||
|
||||
If you want to rate limit immediately when an action modal is opened, you can do so in the `mountUsing()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Notifications\Notification;
|
||||
use Illuminate\Support\Facades\RateLimiter;
|
||||
|
||||
Action::make('delete')
|
||||
->mountUsing(function () {
|
||||
if (RateLimiter::tooManyAttempts(
|
||||
$rateLimitKey = 'delete:' . auth()->id(),
|
||||
maxAttempts: 5,
|
||||
)) {
|
||||
Notification::make()
|
||||
->title('Too many attempts')
|
||||
->body('Please try again in ' . RateLimiter::availableIn($rateLimitKey) . ' seconds.')
|
||||
->danger()
|
||||
->send();
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
RateLimiter::hit($rateLimitKey);
|
||||
})
|
||||
```
|
||||
|
||||
If you want to rate limit when an action is run, you can do so in the `action()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Notifications\Notification;
|
||||
use Illuminate\Support\Facades\RateLimiter;
|
||||
|
||||
Action::make('delete')
|
||||
->action(function () {
|
||||
if (RateLimiter::tooManyAttempts(
|
||||
$rateLimitKey = 'delete:' . auth()->id(),
|
||||
maxAttempts: 5,
|
||||
)) {
|
||||
Notification::make()
|
||||
->title('Too many attempts')
|
||||
->body('Please try again in ' . RateLimiter::availableIn($rateLimitKey) . ' seconds.')
|
||||
->danger()
|
||||
->send();
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
RateLimiter::hit($rateLimitKey);
|
||||
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
## Action utility injection
|
||||
|
||||
The vast majority of methods used to configure actions accept functions as parameters instead of hardcoded values:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->label('Edit post')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
```
|
||||
|
||||
This alone unlocks many customization possibilities.
|
||||
|
||||
The package is also able to inject many utilities to use inside these functions, as parameters. All customization methods that accept functions as arguments can inject utilities.
|
||||
|
||||
These injected utilities require specific parameter names to be used. Otherwise, Filament doesn't know what to inject.
|
||||
|
||||
### Injecting the current modal form data
|
||||
|
||||
If you wish to access the current [modal form data](modals#modal-forms), define a `$data` parameter:
|
||||
|
||||
```php
|
||||
function (array $data) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Be aware that this will be empty if the modal has not been submitted yet.
|
||||
|
||||
### Injecting the current arguments
|
||||
|
||||
If you wish to access the [current arguments](adding-an-action-to-a-livewire-component#passing-action-arguments) that have been passed to the action, define an `$arguments` parameter:
|
||||
|
||||
```php
|
||||
function (array $arguments) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting the current Livewire component instance
|
||||
|
||||
If you wish to access the current Livewire component instance that the action belongs to, define a `$livewire` parameter:
|
||||
|
||||
```php
|
||||
use Livewire\Component;
|
||||
|
||||
function (Component $livewire) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting the current action instance
|
||||
|
||||
If you wish to access the current action instance, define a `$action` parameter:
|
||||
|
||||
```php
|
||||
function (Action $action) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting multiple utilities
|
||||
|
||||
The parameters are injected dynamically using reflection, so you are able to combine multiple parameters in any order:
|
||||
|
||||
```php
|
||||
use Livewire\Component;
|
||||
|
||||
function (array $arguments, Component $livewire) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting dependencies from Laravel's container
|
||||
|
||||
You may inject anything from Laravel's container like normal, alongside utilities:
|
||||
|
||||
```php
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
function (Request $request, array $arguments) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
@@ -391,7 +391,7 @@ Action::make('help')
|
||||
->modalCancelAction(fn (Action $action) => $action->label('Close'))
|
||||
```
|
||||
|
||||
The [methods available to customize trigger buttons](trigger-button) will work to modify the `$action` instance inside the closure.
|
||||
The [methods available to customize trigger buttons](overview) will work to modify the `$action` instance inside the closure.
|
||||
|
||||
### Removing a default modal footer action button
|
||||
|
||||
@@ -422,7 +422,7 @@ Action::make('create')
|
||||
])
|
||||
```
|
||||
|
||||
`$action->makeModalSubmitAction()` returns an action instance that can be customized using the [methods available to customize trigger buttons](trigger-button).
|
||||
`$action->makeModalSubmitAction()` returns an action instance that can be customized using the [methods available to customize trigger buttons](overview).
|
||||
|
||||
The second parameter of `makeModalSubmitAction()` allows you to pass an array of arguments that will be accessible inside the action's `action()` closure as `$arguments`. These could be useful as flags to indicate that the action should behave differently based on the user's decision:
|
||||
|
||||
@@ -1,259 +0,0 @@
|
||||
---
|
||||
title: Trigger button
|
||||
---
|
||||
import AutoScreenshot from "@components/AutoScreenshot.astro"
|
||||
|
||||
## Introduction
|
||||
|
||||
All actions have a trigger button. When the user clicks on it, the action is executed - a modal will open, a closure function will be executed, or they will be redirected to a URL.
|
||||
|
||||
This page is about customizing the look of that trigger button.
|
||||
|
||||
## Choosing a trigger style
|
||||
|
||||
Out of the box, action triggers have 4 styles - "button", "link", "icon button", and "badge".
|
||||
|
||||
"Button" triggers have a background color, label, and optionally an [icon](#setting-an-icon). Usually, this is the default button style, but you can use it manually with the `button()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->button()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/button" alt="Button trigger" version="4.x" />
|
||||
|
||||
"Link" triggers have no background color. They must have a label and optionally an [icon](#setting-an-icon). They look like a link that you might find embedded within text. You can switch to that style with the `link()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->link()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/link" alt="Link trigger" version="4.x" />
|
||||
|
||||
"Icon button" triggers are circular buttons with an [icon](#setting-an-icon) and no label. You can switch to that style with the `iconButton()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->icon('heroicon-m-pencil-square')
|
||||
->iconButton()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/icon-button" alt="Icon button trigger" version="4.x" />
|
||||
|
||||
"Badge" triggers have a background color, label, and optionally an [icon](#setting-an-icon). You can use a badge as trigger using the `badge()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->badge()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/badge" alt="Badge trigger" version="4.x" />
|
||||
|
||||
### Using an icon button on mobile devices only
|
||||
|
||||
You may want to use a button style with a label on desktop, but remove the label on mobile. This will transform it into an icon button. You can do this with the `labeledFrom()` method, passing in the responsive [breakpoint](https://tailwindcss.com/docs/responsive-design#overview) at which you want the label to be added to the button:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->icon('heroicon-m-pencil-square')
|
||||
->button()
|
||||
->labeledFrom('md')
|
||||
```
|
||||
|
||||
## Setting a label
|
||||
|
||||
By default, the label of the trigger button is generated from its name. You may customize this using the `label()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->label('Edit post')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
```
|
||||
|
||||
## Setting a color
|
||||
|
||||
Buttons may have a [color](../styling/colors) to indicate their significance:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->color('danger')
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/danger" alt="Red trigger" version="4.x" />
|
||||
|
||||
## Setting a size
|
||||
|
||||
Buttons come in 3 sizes - `Size::Small`, `Size::Medium` or `Size::Large`. You can change the size of the action's trigger using the `size()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Support\Enums\Size;
|
||||
|
||||
Action::make('create')
|
||||
->size(Size::Large)
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/large" alt="Large trigger" version="4.x" />
|
||||
|
||||
## Setting an icon
|
||||
|
||||
Buttons may have an [icon](../styling/icons) to add more detail to the UI. You can set the icon using the `icon()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->icon('heroicon-m-pencil-square')
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/icon" alt="Trigger with icon" version="4.x" />
|
||||
|
||||
You can also change the icon's position to be after the label instead of before it, using the `iconPosition()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Support\Enums\IconPosition;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->icon('heroicon-m-pencil-square')
|
||||
->iconPosition(IconPosition::After)
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/icon-after" alt="Trigger with icon after the label" version="4.x" />
|
||||
|
||||
## Authorization
|
||||
|
||||
You may conditionally show or hide actions for certain users. To do this, you can use either the `visible()` or `hidden()` methods:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->visible(auth()->user()->can('update', $this->post))
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->hidden(! auth()->user()->can('update', $this->post))
|
||||
```
|
||||
|
||||
This is useful for authorization of certain actions to only users who have permission.
|
||||
|
||||
### Disabling a button
|
||||
|
||||
If you want to disable a button instead of hiding it, you can use the `disabled()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->disabled()
|
||||
```
|
||||
|
||||
You can conditionally disable a button by passing a boolean to it:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->disabled(! auth()->user()->can('delete', $this->post))
|
||||
```
|
||||
|
||||
## Registering keybindings
|
||||
|
||||
You can attach keyboard shortcuts to trigger buttons. These use the same key codes as [Mousetrap](https://craig.is/killing/mice):
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('save')
|
||||
->action(fn () => $this->save())
|
||||
->keyBindings(['command+s', 'ctrl+s'])
|
||||
```
|
||||
|
||||
## Adding a badge to the corner of the button
|
||||
|
||||
You can add a badge to the corner of the button, to display whatever you want. It's useful for displaying a count of something, or a status indicator:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('filter')
|
||||
->iconButton()
|
||||
->icon('heroicon-m-funnel')
|
||||
->badge(5)
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/badged" alt="Trigger with badge" version="4.x" />
|
||||
|
||||
You can also pass a [color](../styling/colors) to be used for the badge:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('filter')
|
||||
->iconButton()
|
||||
->icon('heroicon-m-funnel')
|
||||
->badge(5)
|
||||
->badgeColor('success')
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/success-badged" alt="Trigger with green badge" version="4.x" />
|
||||
|
||||
## Outlined button style
|
||||
|
||||
When you're using the "button" trigger style, you might wish to make it less prominent. You could use a different [color](#setting-a-color), but sometimes you might want to make it outlined instead. You can do this with the `outlined()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->button()
|
||||
->outlined()
|
||||
```
|
||||
|
||||
<AutoScreenshot name="actions/trigger-button/outlined" alt="Outlined trigger button" version="4.x" />
|
||||
|
||||
## Adding extra HTML attributes
|
||||
|
||||
You can pass extra HTML attributes to the button which will be merged onto the outer DOM element. Pass an array of attributes to the `extraAttributes()` method, where the key is the attribute name and the value is the attribute value:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->extraAttributes([
|
||||
'title' => 'Edit this post',
|
||||
])
|
||||
```
|
||||
|
||||
If you pass CSS classes in a string, they will be merged with the default classes that already apply to the other HTML element of the button:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
->extraAttributes([
|
||||
'class' => 'mx-auto my-8',
|
||||
])
|
||||
```
|
||||
+1
-1
@@ -24,7 +24,7 @@ This page is about customizing the look of the group's trigger button and dropdo
|
||||
|
||||
## Customizing the group trigger style
|
||||
|
||||
The button which opens the dropdown may be customized in the same way as a normal action. [All the methods available for trigger buttons](trigger-button) may be used to customize the group trigger button:
|
||||
The button which opens the dropdown may be customized in the same way as a normal action. [All the methods available for trigger buttons](overview) may be used to customize the group trigger button:
|
||||
|
||||
```php
|
||||
use Filament\Actions\ActionGroup;
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Create action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to create Eloquent records. When the trigger button is clicked, a modal will open with a form inside. The user fills the form, and that data is validated and saved into the database. You may use it like so:
|
||||
Filament includes an action that is able to create Eloquent records. When the trigger button is clicked, a modal will open with a form inside. The user fills the form, and that data is validated and saved into the database. You may use it like so:
|
||||
|
||||
```php
|
||||
use Filament\Actions\CreateAction;
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Edit action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to edit Eloquent records. When the trigger button is clicked, a modal will open with a form inside. The user fills the form, and that data is validated and saved into the database. You may use it like so:
|
||||
Filament includes an action that is able to edit Eloquent records. When the trigger button is clicked, a modal will open with a form inside. The user fills the form, and that data is validated and saved into the database. You may use it like so:
|
||||
|
||||
```php
|
||||
use Filament\Actions\EditAction;
|
||||
@@ -1,193 +0,0 @@
|
||||
---
|
||||
title: Advanced actions
|
||||
---
|
||||
|
||||
## Action utility injection
|
||||
|
||||
The vast majority of methods used to configure actions accept functions as parameters instead of hardcoded values:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('edit')
|
||||
->label('Edit post')
|
||||
->url(fn (): string => route('posts.edit', ['post' => $this->post]))
|
||||
```
|
||||
|
||||
This alone unlocks many customization possibilities.
|
||||
|
||||
The package is also able to inject many utilities to use inside these functions, as parameters. All customization methods that accept functions as arguments can inject utilities.
|
||||
|
||||
These injected utilities require specific parameter names to be used. Otherwise, Filament doesn't know what to inject.
|
||||
|
||||
### Injecting the current modal form data
|
||||
|
||||
If you wish to access the current [modal form data](modals#modal-forms), define a `$data` parameter:
|
||||
|
||||
```php
|
||||
function (array $data) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Be aware that this will be empty if the modal has not been submitted yet.
|
||||
|
||||
### Injecting the current arguments
|
||||
|
||||
If you wish to access the [current arguments](adding-an-action-to-a-livewire-component#passing-action-arguments) that have been passed to the action, define an `$arguments` parameter:
|
||||
|
||||
```php
|
||||
function (array $arguments) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting the current Livewire component instance
|
||||
|
||||
If you wish to access the current Livewire component instance that the action belongs to, define a `$livewire` parameter:
|
||||
|
||||
```php
|
||||
use Livewire\Component;
|
||||
|
||||
function (Component $livewire) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting the current action instance
|
||||
|
||||
If you wish to access the current action instance, define a `$action` parameter:
|
||||
|
||||
```php
|
||||
function (Action $action) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting multiple utilities
|
||||
|
||||
The parameters are injected dynamically using reflection, so you are able to combine multiple parameters in any order:
|
||||
|
||||
```php
|
||||
use Livewire\Component;
|
||||
|
||||
function (array $arguments, Component $livewire) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Injecting dependencies from Laravel's container
|
||||
|
||||
You may inject anything from Laravel's container like normal, alongside utilities:
|
||||
|
||||
```php
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
function (Request $request, array $arguments) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## Rate limiting actions
|
||||
|
||||
You can rate limit actions by using the `rateLimit()` method. This method accepts the number of attempts per minute that a user IP address can make. If the user exceeds this limit, the action will not run and a notification will be shown:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Action::make('delete')
|
||||
->rateLimit(5)
|
||||
```
|
||||
|
||||
If the action opens a modal, the rate limit will be applied when the modal is submitted.
|
||||
|
||||
If an action is opened with arguments or for a specific Eloquent record, the rate limit will apply to each unique combination of arguments or record for each action. The rate limit is also unique to the current Livewire component / page in a panel.
|
||||
|
||||
## Customizing the rate limited notification
|
||||
|
||||
When an action is rate limited, a notification is dispatched to the user, which indicates the rate limit.
|
||||
|
||||
To customize the title of this notification, use the `rateLimitedNotificationTitle()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\DeleteAction;
|
||||
|
||||
DeleteAction::make()
|
||||
->rateLimit(5)
|
||||
->rateLimitedNotificationTitle('Slow down!')
|
||||
```
|
||||
|
||||
You may customize the entire notification using the `rateLimitedNotification()` method:
|
||||
|
||||
```php
|
||||
use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;
|
||||
use Filament\Actions\DeleteAction;
|
||||
use Filament\Notifications\Notification;
|
||||
|
||||
DeleteAction::make()
|
||||
->rateLimit(5)
|
||||
->rateLimitedNotification(
|
||||
fn (TooManyRequestsException $exception): Notification => Notification::make()
|
||||
->warning()
|
||||
->title('Slow down!')
|
||||
->body("You can try deleting again in {$exception->secondsUntilAvailable} seconds."),
|
||||
)
|
||||
```
|
||||
|
||||
### Customizing the rate limit behavior
|
||||
|
||||
If you wish to customize the rate limit behavior, you can use Laravel's [rate limiting](https://laravel.com/docs/rate-limiting#basic-usage) features and Filament's [flash notifications](../notifications/overview) together in the action.
|
||||
|
||||
If you want to rate limit immediately when an action modal is opened, you can do so in the `mountUsing()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Notifications\Notification;
|
||||
use Illuminate\Support\Facades\RateLimiter;
|
||||
|
||||
Action::make('delete')
|
||||
->mountUsing(function () {
|
||||
if (RateLimiter::tooManyAttempts(
|
||||
$rateLimitKey = 'delete:' . auth()->id(),
|
||||
maxAttempts: 5,
|
||||
)) {
|
||||
Notification::make()
|
||||
->title('Too many attempts')
|
||||
->body('Please try again in ' . RateLimiter::availableIn($rateLimitKey) . ' seconds.')
|
||||
->danger()
|
||||
->send();
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
RateLimiter::hit($rateLimitKey);
|
||||
})
|
||||
```
|
||||
|
||||
If you want to rate limit when an action is run, you can do so in the `action()` method:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Notifications\Notification;
|
||||
use Illuminate\Support\Facades\RateLimiter;
|
||||
|
||||
Action::make('delete')
|
||||
->action(function () {
|
||||
if (RateLimiter::tooManyAttempts(
|
||||
$rateLimitKey = 'delete:' . auth()->id(),
|
||||
maxAttempts: 5,
|
||||
)) {
|
||||
Notification::make()
|
||||
->title('Too many attempts')
|
||||
->body('Please try again in ' . RateLimiter::availableIn($rateLimitKey) . ' seconds.')
|
||||
->danger()
|
||||
->send();
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
RateLimiter::hit($rateLimitKey);
|
||||
|
||||
// ...
|
||||
})
|
||||
```
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: View action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to view Eloquent records. When the trigger button is clicked, a modal will open with information inside. Filament uses form fields to structure this information. All form fields are disabled, so they are not editable by the user. You may use it like so:
|
||||
Filament includes an action that is able to view Eloquent records. When the trigger button is clicked, a modal will open with information inside. Filament uses form fields to structure this information. All form fields are disabled, so they are not editable by the user. You may use it like so:
|
||||
|
||||
```php
|
||||
use Filament\Actions\ViewAction;
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Delete action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to delete Eloquent records. When the trigger button is clicked, a modal asks the user for confirmation. You may use it like so:
|
||||
Filament includes an action that is able to delete Eloquent records. When the trigger button is clicked, a modal asks the user for confirmation. You may use it like so:
|
||||
|
||||
```php
|
||||
use Filament\Actions\DeleteAction;
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Replicate action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to [replicate](https://laravel.com/docs/eloquent#replicating-models) Eloquent records. You may use it like so:
|
||||
Filament includes an action that is able to [replicate](https://laravel.com/docs/eloquent#replicating-models) Eloquent records. You may use it like so:
|
||||
|
||||
```php
|
||||
use Filament\Actions\ReplicateAction;
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Force-delete action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to force-delete [soft deleted](https://laravel.com/docs/eloquent#soft-deleting) Eloquent records. When the trigger button is clicked, a modal asks the user for confirmation. You may use it like so:
|
||||
Filament includes an action that is able to force-delete [soft deleted](https://laravel.com/docs/eloquent#soft-deleting) Eloquent records. When the trigger button is clicked, a modal asks the user for confirmation. You may use it like so:
|
||||
|
||||
```php
|
||||
use Filament\Actions\ForceDeleteAction;
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Restore action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to restore [soft deleted](https://laravel.com/docs/eloquent#soft-deleting) Eloquent records. When the trigger button is clicked, a modal asks the user for confirmation. You may use it like so:
|
||||
Filament includes an action that is able to restore [soft deleted](https://laravel.com/docs/eloquent#soft-deleting) Eloquent records. When the trigger button is clicked, a modal asks the user for confirmation. You may use it like so:
|
||||
|
||||
```php
|
||||
use Filament\Actions\RestoreAction;
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Import action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to import rows from a CSV. When the trigger button is clicked, a modal asks the user for a file. Once they upload one, they are able to map each column in the CSV to a real column in the database. If any rows fail validation, they will be compiled into a downloadable CSV for the user to review after the rest of the rows have been imported. Users can also download an example CSV file containing all the columns that can be imported.
|
||||
Filament includes an action that is able to import rows from a CSV. When the trigger button is clicked, a modal asks the user for a file. Once they upload one, they are able to map each column in the CSV to a real column in the database. If any rows fail validation, they will be compiled into a downloadable CSV for the user to review after the rest of the rows have been imported. Users can also download an example CSV file containing all the columns that can be imported.
|
||||
|
||||
This feature uses [job batches](https://laravel.com/docs/queues#job-batching) and [database notifications](../../notifications/database-notifications), so you need to publish those migrations from Laravel. Also, you need to publish the migrations for tables that Filament uses to store information about imports:
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ title: Export action
|
||||
|
||||
## Introduction
|
||||
|
||||
Filament includes a prebuilt action that is able to export rows to a CSV or XLSX file. When the trigger button is clicked, a modal asks for the columns that they want to export, and what they should be labeled. This feature uses [job batches](https://laravel.com/docs/queues#job-batching) and [database notifications](../../notifications/database-notifications), so you need to publish those migrations from Laravel. Also, you need to publish the migrations for tables that Filament uses to store information about exports:
|
||||
Filament includes an action that is able to export rows to a CSV or XLSX file. When the trigger button is clicked, a modal asks for the columns that they want to export, and what they should be labeled. This feature uses [job batches](https://laravel.com/docs/queues#job-batching) and [database notifications](../../notifications/database-notifications), so you need to publish those migrations from Laravel. Also, you need to publish the migrations for tables that Filament uses to store information about exports:
|
||||
|
||||
```bash
|
||||
# Laravel 11 and higher
|
||||
@@ -801,7 +801,7 @@ Select::make('technologies')
|
||||
|
||||
## Customizing the select action objects
|
||||
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/trigger-button) or [customize its modal](../actions/modals). The following methods are available to customize the actions:
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/overview) or [customize its modal](../actions/modals). The following methods are available to customize the actions:
|
||||
|
||||
- `createOptionAction()`
|
||||
- `editOptionAction()`
|
||||
|
||||
@@ -391,7 +391,7 @@ CheckboxList::make('technologies')
|
||||
|
||||
## Customizing the checkbox list action objects
|
||||
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/trigger-button). The following methods are available to customize the actions:
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/overview). The following methods are available to customize the actions:
|
||||
|
||||
- `selectAllAction()`
|
||||
- `deselectAllAction()`
|
||||
|
||||
@@ -702,7 +702,7 @@ This method will automatically enable the `distinct()` and `live()` methods on t
|
||||
|
||||
## Customizing the repeater item actions
|
||||
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/trigger-button). The following methods are available to customize the actions:
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/overview). The following methods are available to customize the actions:
|
||||
|
||||
- `addAction()`
|
||||
- `cloneAction()`
|
||||
|
||||
@@ -548,7 +548,7 @@ Builder::make('content')
|
||||
|
||||
## Customizing the builder item actions
|
||||
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/trigger-button). The following methods are available to customize the actions:
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/overview). The following methods are available to customize the actions:
|
||||
|
||||
- `addAction()`
|
||||
- `addBetweenAction()`
|
||||
|
||||
@@ -177,7 +177,7 @@ KeyValue::make('meta')
|
||||
|
||||
## Customizing the key-value action objects
|
||||
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/trigger-button). The following methods are available to customize the actions:
|
||||
This field uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/overview). The following methods are available to customize the actions:
|
||||
|
||||
- `addAction()`
|
||||
- `deleteAction()`
|
||||
|
||||
@@ -223,7 +223,7 @@ new FilamentNotification()
|
||||
|
||||
## Adding actions to notifications
|
||||
|
||||
Notifications support [Actions](../actions/trigger-button), which are buttons that render below the content of the notification. They can open a URL or dispatch a Livewire event. Actions can be defined as follows:
|
||||
Notifications support [Actions](../actions/overview), which are buttons that render below the content of the notification. They can open a URL or dispatch a Livewire event. Actions can be defined as follows:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
@@ -260,7 +260,7 @@ new FilamentNotification()
|
||||
|
||||
<AutoScreenshot name="notifications/actions" alt="Notification with actions" version="4.x" />
|
||||
|
||||
You can learn more about how to style action buttons [here](../actions/trigger-button).
|
||||
You can learn more about how to style action buttons [here](../actions/overview).
|
||||
|
||||
### Opening URLs from notification actions
|
||||
|
||||
|
||||
@@ -257,7 +257,7 @@ Wizard::make([
|
||||
|
||||
## Customizing the wizard action objects
|
||||
|
||||
This component uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/trigger-button). The following methods are available to customize the actions:
|
||||
This component uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the `$action` object, which you can use to [customize it](../actions/overview). The following methods are available to customize the actions:
|
||||
|
||||
- `nextAction()`
|
||||
- `previousAction()`
|
||||
|
||||
@@ -160,7 +160,7 @@ public function table(Table $table): Table
|
||||
|
||||
In this example, we define 2 actions for table rows. The first action is a "feature" action. When clicked, it will set the `is_featured` attribute on the record to `true` - which is written within the `action()` method. Using the `hidden()` method, the action will be hidden if the record is already featured. The second action is an "unfeature" action. When clicked, it will set the `is_featured` attribute on the record to `false`. Using the `visible()` method, the action will be hidden if the record is not featured.
|
||||
|
||||
We also define a bulk action. When bulk actions are defined, each row in the table will have a checkbox. This bulk action is [built-in to Filament](../actions/prebuilt-actions/delete#bulk-delete), and it will delete all selected records. However, you can [write your own custom bulk actions](actions#bulk-actions) easily too.
|
||||
We also define a bulk action. When bulk actions are defined, each row in the table will have a checkbox. This bulk action is [built-in to Filament](../actions/delete#bulk-delete), and it will delete all selected records. However, you can [write your own custom bulk actions](actions#bulk-actions) easily too.
|
||||
|
||||
<AutoScreenshot name="tables/overview/actions-modal" alt="Table with action modal open" version="4.x" />
|
||||
|
||||
@@ -375,7 +375,7 @@ public function table(Table $table): Table
|
||||
|
||||
### Customizing the reordering trigger action
|
||||
|
||||
To customize the reordering trigger button, you may use the `reorderRecordsTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../actions/trigger-button) can be used:
|
||||
To customize the reordering trigger button, you may use the `reorderRecordsTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../actions/overview) can be used:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
@@ -825,7 +825,7 @@ TextColumn::make('id')
|
||||
|
||||
#### Customizing the toggle columns dropdown trigger action
|
||||
|
||||
To customize the toggle dropdown trigger button, you may use the `toggleColumnsTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../actions/trigger-button) can be used:
|
||||
To customize the toggle dropdown trigger button, you may use the `toggleColumnsTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../actions/overview) can be used:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
@@ -143,7 +143,7 @@ public function table(Table $table): Table
|
||||
|
||||
### Customizing the apply filters action
|
||||
|
||||
When deferring filters, you can customize the "Apply" button, using the `filtersApplyAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../../actions/trigger-button) can be used:
|
||||
When deferring filters, you can customize the "Apply" button, using the `filtersApplyAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../../actions/overview) can be used:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
@@ -202,7 +202,7 @@ TernaryFilter::make('trashed')
|
||||
|
||||
## Customizing the filters trigger action
|
||||
|
||||
To customize the filters trigger buttons, you may use the `filtersTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../../actions/trigger-button) can be used:
|
||||
To customize the filters trigger buttons, you may use the `filtersTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../../actions/overview) can be used:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
@@ -7,7 +7,7 @@ import AutoScreenshot from "@components/AutoScreenshot.astro"
|
||||
|
||||
Filament's tables can use [Actions](../actions). They are buttons that can be added to the [end of any table row](#row-actions), or even in the [header](#header-actions) of a table. For instance, you may want an action to "create" a new record in the header, and then "edit" and "delete" actions on each row. [Bulk actions](#bulk-actions) can be used to execute code when records in the table are selected. Additionally, actions can be added to any [table column](#column-actions), such that each cell in that column is a trigger for your action.
|
||||
|
||||
It's highly advised that you read the documentation about [customizing action trigger buttons](../actions/trigger-button) and [action modals](../actions/modals) to that you are aware of the full capabilities of actions.
|
||||
It's highly advised that you read the documentation about [customizing action trigger buttons](../actions/overview) and [action modals](../actions/modals) to that you are aware of the full capabilities of actions.
|
||||
|
||||
## Row actions
|
||||
|
||||
@@ -265,20 +265,6 @@ This is useful for things like "create" actions, which are not related to any sp
|
||||
|
||||
Actions can be added to columns, such that when a cell in that column is clicked, it acts as the trigger for an action. You can learn more about [column actions](columns/overview#triggering-actions) in the documentation.
|
||||
|
||||
## Prebuilt table actions
|
||||
|
||||
Filament includes several prebuilt actions and bulk actions that you can add to a table. Their aim is to simplify the most common Eloquent-related actions:
|
||||
|
||||
- [Create](../actions/prebuilt-actions/create)
|
||||
- [Edit](../actions/prebuilt-actions/edit)
|
||||
- [View](../actions/prebuilt-actions/view)
|
||||
- [Delete](../actions/prebuilt-actions/delete)
|
||||
- [Replicate](../actions/prebuilt-actions/replicate)
|
||||
- [Force-delete](../actions/prebuilt-actions/force-delete)
|
||||
- [Restore](../actions/prebuilt-actions/restore)
|
||||
- [Import](../actions/prebuilt-actions/import)
|
||||
- [Export](../actions/prebuilt-actions/export)
|
||||
|
||||
## Grouping actions
|
||||
|
||||
You may use an `ActionGroup` object to group multiple table actions together in a dropdown:
|
||||
|
||||
@@ -286,7 +286,7 @@ public function table(Table $table): Table
|
||||
|
||||
## Customizing the groups dropdown trigger action
|
||||
|
||||
To customize the groups dropdown trigger button, you may use the `groupRecordsTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../actions/trigger-button) can be used:
|
||||
To customize the groups dropdown trigger button, you may use the `groupRecordsTriggerAction()` method, passing a closure that returns an action. All methods that are available to [customize action trigger buttons](../actions/overview) can be used:
|
||||
|
||||
```php
|
||||
use Filament\Actions\Action;
|
||||
|
||||
Reference in New Issue
Block a user