Conditional Action Rules

This section covers the Conditional Action Rules feature.

Here you will find:

• Introduction
• Usage
• Performance
• Conditional Cell Data Formatting
• Modifiers

Introduction

Many web applications require the ability to control how data is displayed and what actions are available to the user based on certain conditions.

For example, you may want to remove a button if the user lacks the necessary permissions for that particular action, or display a red background to indicate that a product is no longer available.

PowerGrid provides a set of Action Rules that you can use to control the style, visibility, and behavior of Table rows, checkboxes, and buttons. These rules can be combined to meet specific conditions and requirements.

Usage

Action Rules are registered inside the method actionRules() in your Table Component class.

Rules can be applied to 3 different targets: Rows, Buttons and checkboxes. A target may appear in more than one rule.

Each Rule consists of a target object and a single condition that must be satisfied, along with any number of modifiers. The modifiers will be applied once the condition is met.

To add a Rule, you must add a call to Rule::class, and proceed by defining a target using the methods button(), row() or checkbox. Next, you must chain a condition using the method when() and proceed by chaining modifiers.

For instance, a single button can be the target of two different rules. The first rule will change the button text and its background if the price is under a certain amount. The second rule will disable the button if the product is sold out.

In addition to these two Rules, we can also hide the checkboxes and change the row background when the product is out of stock.

Let's see the code for the example above:

// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\Rule; 

class DishTable extends PowerGridComponent
{
    public function actionRules(): array
    {
        return [                
            Rule::button('order-dish')
                ->when(fn($dish) => $dish->price < 100)
                ->slot('Order NOW! 🔥')
                ->setAttribute('class', '!bg-orange-400'),

            Rule::button('order-dish')
                ->when(fn($dish) => $dish->in_stock === false)
                ->hide()

            Rule::checkbox()
                ->when(fn ($dish) => $dish->in_stock == false)
                ->hide(),
                
            Rule::rows()
                ->when(fn ($dish) => $dish->in_stock == false)
                ->setAttribute('class', '!bg-red-200'),
        ];
    }
}

🚀 See it in action

See an interactive example using Conditional Rules on a Table.

Performance

Actions Rules are processed on the server side. If you are working with many Rules or caching data, you should consider using Actions From View to improve your application's performance.

Conditional Cell Data Formatting

See Custom Fields and Formatting Data Examples.

Modifiers

The Modifiers will take effect when the Rule condition is satisfied.

Available methods:

• disable()
• dispatch()
• dispatchTo()
• hide()
• hideToggleable()
• redirect()
• loop()
• slot()
• setAttribute()
• showToggleable()
• bladeComponent()

---

disable()

Disables the Rule target (available for Buttons and Checkboxes).

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::button('order-dish')
    ->when(fn($dish) => $dish->in_stock == false)
    ->disable(),

---

dispatch()

Sets the event to be emitted by the Rule target (available for Buttons).

Parameter	Description
(string) $event	Name of event
(array) $params	Parameters

💡 TIP

Read more about Dispatch in the Livewire documentation.

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_spicy == true)
    ->dispatch('showSpiceAlert', ['id' => 'id']),

---

dispatchTo()

Sets the target component and the event name to be emitted by the Rule target (available for Buttons).

Parameter	Description
(string) $to	Component name
(string) $event	Name of event
(array) $params	Parameters

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_spicy == true)
    ->dispatchTo('alert-component', 'showSpiceAlert', ['id' => 'id']),

💡 TIP

Read more about Dispatch in the Livewire documentation.

---

hide()

Hides the Rule target (available for Buttons and Checkboxes).

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::checkbox()
    ->when(fn($dish) => $dish->in_stock == false)
    ->hide(),

---

hideToggleable()

Hides the Toggleable Switch for the row. See also showToggleable().

Note that this feature will only hide the Toggleable, not disable it.

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::rows()
    ->when(fn ($dish) => $dish->trashed() == true)
    ->hideToggleable(),

---

redirect()

Sets Rule target's redirect URL (available for Buttons).

Parameter	Description	Default
(Closure) $closure	Closure	null
(string) $target	HTML href target	_blank

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_new == true)
    ->redirect(fn($dish) => 'https://www.google.com/search?q='.urlencode(e($dish->name)), '_blank'),

---

loop()

Interacts with the Row index.

The example below generates a zebra striped Table by applying a background on even rows.

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::rows()
    ->loop(fn ($loop) => $loop->index % 2)
    ->setAttribute('class', '!bg-gunmetal-100'),

---

slot()

Sets the Rule target slot content (available for Buttons).

Parameter
(string) $slot

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::button('order-dish')
    ->when(fn($dish) => $dish->on_sale == true)
    ->slot('Order 💰 ON SALE 💰'),

---

setAttribute()

Sets a value to the Rule target attribute.

Parameter	Description
(string) $attribute	HTML attribute (class,id, x-on:click ...)
(string) $value	Attribute value

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::rows()
    ->when(fn($dish) => $dish->in_stock == false)
    ->setAttribute('class', '!bg-red-200'),

When using Buttons as targets, you may chain as many setAttribute() methods as need.

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::button('order-dish')
    ->when(fn($dish) => $dish->in_stock == false)
    ->setAttribute('class', '!bg-red-200')
    ->setAttribute('wire:click', ['action' => [
        'params' => 1,
        'dishId' => 'id',
    ]]),

---

showToggleable()

Shows the Toggleable Switch for the row. See also hideToggleable().

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::rows()
    ->when(fn ($dish) => $dish->trashed() == false)
    ->showToggleable(),

---

bladeComponent()

Changes the Blade Component in the Rule target.

Parameter	Default
(string) $component	View component path (blade)
(array) $params	Blade parameters

Example:

use PowerComponents\LivewirePowerGrid\Facades\Rule;

Rule::button('order-dish')
    ->when(fn($dish) => $dish->in_stock == false)
    ->bladeComponent('another-custom-button', ['dishId' => 'id']),