README

A Nova package for rendering buttons on different views.

Use buttons to trigger backend events, navigate Nova routes or visit links.

This package is a continuation of dillingham/nova-button.

I created this fork because the original package seemed abandoned (last release on 16-09-2020 at the time of writing) and for me it was too useful to leave unmaintained. I also noticed that there still was activity in the issues and pull requests, which I didn't want to be left ignored.

This package remains open source, so I encourage everyone to keep contributing! And if you want to get in touch with me, feel free to do so!

Versions

For Nova 4 certain changes had to be made that rendered the package not backwards compatible with Nova 3. For that reason the package was split up into multiple versions. Please see the table below to determine which version you need.

Please note: the main branch will always be the latest major version.

Requirements

Installation

You can install this package by running the following command:

composer require dnwjn/nova-button:^4.0

To publish the config file, run the following command:

php artisan vendor:publish --tag="nova-button-config"

Usage

use Dnwjn\NovaButton\Button;

public function fields(Request $request)
{
    return [
        ID::make('ID', 'id')->sortable(),
        Text::make('Name', 'name'),
        Button::make('Notify'),
    ];
}

Confirm

You can require a confirmation for destructive actions:

Button::make('Cancel Account')->confirm('Are you sure?'),
Button::make('Cancel Account')->confirm('Confirmation', 'Are you sure you want to cancel your account?'),
Button::make('Cancel Account')->confirm('Confirmation', 'Are you sure you want to cancel your account?', 'Cancel'),

Reload

You can reload the page after all events have finished.

Button::make('Notify')->reload()

If you click multiple buttons, reloading will wait for all buttons to finish.

If an error occurs, the page will not be reloaded.

Laravel Events

By default, clicking the button will trigger an event via AJAX.

Default event: Dnwjn\NovaButton\Events\ButtonClick.

The event will receive the key it was triggered from and, if available, the resource model:

$event->key = 'notify'
$event->resource = \Illuminate\Database\Eloquent\Model|null

You can override the key:

Button::make('Notify', 'notify-some-user')

And also the event:

Button::make('Notify')->event(App\Events\NotifyRequested::class)

You can listen to the event by creating a listener and registering it in your EventServiceProvider.

JavaScript Events

By default, clicking the button will cause an event to be dispatched via Nova.$emit.

Default event: Dnwjn\NovaButton\Events\ButtonClick.

The event can then be picked up via Nova.$on, and will receive the triggering key and any optional arguments.

You can specify the key and optional arguments:

Button::make('Notify', 'notify-some-user')
    ->emit('notification', ['article_id' => 1, 'which' => 'tags'])

You can listen to the event by creating a listener in your Vue component or JavaScript:

Nova.$on('notification', (e) => {
    // e.article_id = 1
    // e.which = 'tags'
})

Texts

Title

You can set the title attribute for the button:

Button::make('Notify')->title('Button title')

Label

You can set the label for the button, which is shown on the detail, create and update views:

Button::make('Notify')->label('Button label')

Index name

You can set the index name for the button, which is shown on the index view as the table header:

Button::make('Notify')->indexName('Actions')

Default is set to the button name. You can also pass null to have no index name.

State

Visibility

You can conditionally show the button:

Button::make('Activate')->visible($this->is_active === false),
Button::make('Deactivate')->visible($this->is_active === true),

Or, if you only want specific users to see the button:

Button::make('Notify')->visible($request->user()->can('notifyUser', $this))

Of course you can also use Nova's builtin methods, like for authorization or to limit visibility to specific views.

If you want to show a button on the create or update views you can simply use Nova's builtin methods:

Button::make('Notify')->showOnCreating()->showOnUpdating()

Disabled

You can disable the button:

Button::make('Notify')->disabled()
Button::make('Notify')->disabled($this->is_complete === false)

Feedback

When using events, you might want to provide visual feedback to the end user. This is especially useful for long running listeners.

Button::make('Notify')
    ->loadingText('Sending...')
    ->successText('Sent!')
    ->errorText('Something went wrong...')

There are 3 events and for each event you can provide the text and style:

The defaults are defined in the config file.

Nova routes

You can also choose to navigate to any Nova route:

Button::make('Text')->route('vuejs-route-name', ['id' => 1])
Button::make('Text')->index(App\Nova\User::class)
Button::make('Text')->detail(App\Nova\User::class, $this->user_id)
Button::make('Text')->create(App\Nova\User::class)
Button::make('Text')->edit(App\Nova\User::class, $this->user_id)

You can also set query parameters:

Button::make('Text')
    ->route('home')
    ->withParams(['referrer' => 'nova'])

It's also possible to use a resource's filters:

Button::make('Text')
    ->index(App\Nova\Order::class)
    ->withFilters([
        App\Nova\Filters\UserOrders::class => $this->user_id,
        App\Nova\Filters\OrderStatus::class => 'active',
    ])

Links

You can configure the button to open external links:

Button::make('Text')->link('https://nova.laravel.com')
Button::make('Text')->link('https://nova.laravel.com', '_self')

Classes

The button uses the following classes that you can style to your liking:

.nova-button
.nova-button-{resource-name}
.nova-button-success
.nova-button-error
.nova-button-loading

You can also add more classes to a button:

// One class
Button::make('Notify')->classes('some-class')

// Or multiple classes
Button::make('Notify')->classes('some-class', 'another-class')

Styles

This package uses tailwind-css classes. The default class used is the link class.

You can define the class the button should use:

Button::make('Delete')->style('danger')

The default available classes are as follows:

The passed key refers to one of the classes defined in the config file. You are free to change these classes or add your own.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

dnwjn

Author of original package: dillingham

License

The MIT License (MIT). Please see License File for more information.

dnwjn / nova-button

Maintainers

Details