Skip to content

Action Rules

Sometimes you need to control the behavior of rows, checkboxes, or buttons based on record value, user permission or the combination of multiple conditions.

A common example is to list out-of-stock products with a red background and without the "Order" button.

PowerGrid offers a set of Action Rules which can be combined to control style, content, and behavior of Action Buttons, Action Checkboxes and table rows.

Usage

Action Rules must be declared inside the array returned by the actionRules() method.

Each Rule is enforced on a specific Target (e.g: Button 'foo').

The Rule must contain one when() condition method and one or more modifier methods.

The modifiers will take effect when the condition is satisfied.

The following code represents the "out-of-stock" use case described in this page introduction:

php
// Create an Action Button for ordering a dish.
public function actions(): array
{
    return [
        Button::add('order-dish')
            ->slot('Order')
            ->class('bg-blue-500 cursor-pointer text-white px-3 py-2 m-1 rounded text-sm')
            ->dispatch('order-dish', ['dishId' => 'id'])
    ];
}

// Rules
public function actionRules(): array
{
    return [
        // Hide order button when dish is out-of-stock
        Rule::button('order-dish')
            ->when(fn($dish) => $dish->in_stock == false)
            ->hide(),
            
        // Set red background on rows for dishes which are not free and are out-of-stock 
        Rule::rows()
            ->when(function ($dish) { 
                return $dish->price > 0 && $dish->in_stock == false;
            })
            ->setAttribute('class', 'bg-red-200'),
    ];
}
// Create an Action Button for ordering a dish.
public function actions(): array
{
    return [
        Button::add('order-dish')
            ->slot('Order')
            ->class('bg-blue-500 cursor-pointer text-white px-3 py-2 m-1 rounded text-sm')
            ->dispatch('order-dish', ['dishId' => 'id'])
    ];
}

// Rules
public function actionRules(): array
{
    return [
        // Hide order button when dish is out-of-stock
        Rule::button('order-dish')
            ->when(fn($dish) => $dish->in_stock == false)
            ->hide(),
            
        // Set red background on rows for dishes which are not free and are out-of-stock 
        Rule::rows()
            ->when(function ($dish) { 
                return $dish->price > 0 && $dish->in_stock == false;
            })
            ->setAttribute('class', 'bg-red-200'),
    ];
}

Result:

Output

Combining modifiers

Modifiers can be combined under the same rule. For example:

php
// Sets the button class to spicy and caption with emoji
Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_spicy == true)
    ->slot('Order 🔥 🔥 🔥')
    ->setAttribute('class', 'bg-orange-400'),
// Sets the button class to spicy and caption with emoji
Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_spicy == true)
    ->slot('Order 🔥 🔥 🔥')
    ->setAttribute('class', 'bg-orange-400'),

Multiple Rules for the same Target

A Rule must have only one when() condition.

You must create a new Rule to match a different condition on the Target. For example:

php
//Captions per country on 'Order button'
Rule::button('order-dish')
    ->when(fn($dish) => $dish->country === 'Brazil')
    ->slot('Order 🇧🇷')
    
Rule::button('order-dish')
    ->when(fn($dish) => $dish->country === 'Portugal')
    ->slot('Order 🇵🇹')
    
//Disable order for dishes without country
Rule::button('order-dish')
    ->when(fn($dish) => $dish->country === '')
    ->disable()
//Captions per country on 'Order button'
Rule::button('order-dish')
    ->when(fn($dish) => $dish->country === 'Brazil')
    ->slot('Order 🇧🇷')
    
Rule::button('order-dish')
    ->when(fn($dish) => $dish->country === 'Portugal')
    ->slot('Order 🇵🇹')
    
//Disable order for dishes without country
Rule::button('order-dish')
    ->when(fn($dish) => $dish->country === '')
    ->disable()

Rule targets

Rules can be applied to 3 different targets:

  • Rule::button: Rules for a specific action button when the condition is satisfied.
  • Rule::rows: Rules to be applied to rows matching the condition.
  • Rule::checkbox: Rules to be applied to each checkbox on all table rows matching the condition.

Modifiers

The Modifiers will take effect when the Rule condition is satisfied. You can use more than one Modifier under the same rule.

Available methods:

disable

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

Example:

php
// Disable order button for dishes out out-of-stock
Rule::button('order-dish')
    ->when(fn($dish) => (bool) $dish->in_stock == false)
    ->disable(),
// Disable order button for dishes out out-of-stock
Rule::button('order-dish')
    ->when(fn($dish) => (bool) $dish->in_stock == false)
    ->disable(),

hide

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

Example:

php
// Hide checkbox for dishes out of stock
Rule::checkbox()
    ->when(fn($dish) => $dish->in_stock == false)
    ->hide(),
// Hide checkbox for dishes out of stock
Rule::checkbox()
    ->when(fn($dish) => $dish->in_stock == false)
    ->hide(),

slot

  • Sets the target slot value (available for Buttons).
Parameter
(string) $slot

Example:

php
// Changes the caption for dishes on sale
Rule::button('order-dish')
    ->when(fn($dish) => $dish->on_sale == true)
    ->slot('Order 💰 ON SALE 💰'),
// Changes the caption for dishes on sale
Rule::button('order-dish')
    ->when(fn($dish) => $dish->on_sale == true)
    ->slot('Order 💰 ON SALE 💰'),

dispatch

  • Sets the event emitted by the target (available for Buttons).
ParameterDescription
(string) $eventName of event
(array) $paramsParameters

TIP

Read more about Dispatch in the Livewire documentation.

Example:

php
// Emits an alert for spice dishes
Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_spicy == true)
    ->dispatch('showSpiceAlert', ['id' => 'id']),
// Emits an alert for spice dishes
Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_spicy == true)
    ->dispatch('showSpiceAlert', ['id' => 'id']),

dispatchTo

  • Sets an event and a target to which the event will be emitted to (available for Buttons).
ParameterDescription
(string) $toComponent name
(string) $eventName of event
(array) $paramsParameters

TIP

Read more about Dispatch in the Livewire documentation.

Example:

php
// Emits the event showSpiceAlert to a third part alert-component on click

Rule::button('order-dish')
    ->when(fn($dish) => $dish->is_spicy == true)
    ->dispatchTo('alert-component', 'showSpiceAlert', ['id' => 'id']),
// Emits the event showSpiceAlert to a third part alert-component on click

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

Read more in Livewire documentation.


setAttribute

  • Sets the specified target attribute to the given value.
ParameterDescription
(string) $attributeHTML attribute (class,id, x-on:click ...)
(string) $valueAttribute value

TIP

Multiples are issued for the target button only

Example:

Change row background to red when dish is out of stock

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

Output:

html
<button class="bg-indigo-500 cursor-pointer text-white px-3 py-2 m-1 rounded text-sm !bg-red-200">
        Edit
</button>
<button class="bg-indigo-500 cursor-pointer text-white px-3 py-2 m-1 rounded text-sm !bg-red-200">
        Edit
</button>

Add wire:click attribute when dish is out of stock

php

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

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

Output:

html
<button class="bg-indigo-500 cursor-pointer text-white px-3 py-2 m-1 rounded text-sm !bg-red-200" 
        wire:click="action({"params":1,"dishId":2})">
        Edit
</button>
<button class="bg-indigo-500 cursor-pointer text-white px-3 py-2 m-1 rounded text-sm !bg-red-200" 
        wire:click="action({"params":1,"dishId":2})">
        Edit
</button>

hideToggleable

Toggleable must be configured in the column. This feature will only hide the Toggleable, not disable it.

Example:

php
// Hide Toggleable for Soft deleted dishes
Rule::button('read-more')
    ->when(fn ($dish) => $dish->trashed() == true)
    ->hideToggleable(),
// Hide Toggleable for Soft deleted dishes
Rule::button('read-more')
    ->when(fn ($dish) => $dish->trashed() == true)
    ->hideToggleable(),

showToggleable

Toggleable must be configured in the column. This feature will only show the Toggleable, not disable it.

Example:

php
// Hide Toggleable for Soft deleted dishes
Rule::button('read-more')
    ->when(fn ($dish) => $dish->trashed() == false)
    ->showToggleable(),
// Hide Toggleable for Soft deleted dishes
Rule::button('read-more')
    ->when(fn ($dish) => $dish->trashed() == false)
    ->showToggleable(),

redirect

  • Sets target's redirect URL (available for Buttons).
ParameterDescriptionDefault
(Closure) $closureClosure_blank
(string) $targetHTML href target

Example:

php
// Redirects to Google search for exotic dishes
Rule::button('read-more')
    ->when(fn($dish) => $dish->is_exotic == true)
    ->redirect(fn($dish) => 'https://www.google.com/search?q='.$dish->name, '_blank'),
// Redirects to Google search for exotic dishes
Rule::button('read-more')
    ->when(fn($dish) => $dish->is_exotic == true)
    ->redirect(fn($dish) => 'https://www.google.com/search?q='.$dish->name, '_blank'),

bladeComponent

  • Change blade component when dish is out of stock
ParameterDefault
(string) $componentView component path (blade)
(array) $paramsBlade parameters

Example:

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

Created By Luan Freitas and DanSysAnalyst