Data Source Fields
This section covers the PowerGrid Data Source fields.
Here you will find:
Introduction
Once your Table Data Source method is properly configured, it's time to decide which fields you want to bring as columns to be later displayed on your Table.
Adding Fields
To include fields from your data source, call the PowerGrid::fields() inside the fields() method. Then, proceed to chain as many data source fields as you need.
The next example adds the fields id, name, and price, bringing data directly from the database.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
class DishTable extends PowerGridComponent
{
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('id')
->add('name')
->add('price');
}
}🎉 Super!
Now, let's check out how to Add Columns.
Custom Fields
Sometimes, we need to modify data from the database before showing it on the Table Component.
In addition to a data source field name, PowerGrid::fields()->add() also accepts a closure as a second parameter, allowing you to modify the data coming from the database.
❗ WARNING
Be careful: Data returned in Custom Fields is NOT escaped by default. As a result, your application might be vulnerable to XSS attacks.
It's highly recommended to use Laravel's e() helper to escape data return in Custom Fields.
In the next example, in addition to the database name and price fields, the data source will have two new Custom Fields. These Custom Fields will output the name in UPPER CASE and the price with a 10% discount.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('id')
->add('name')
->add('price')
->add('name_uppercase', function ($dish) {
return e(strtoupper($dish->name));
})
->add('price_with_discount', function ($dish) {
return floatval($dish->price - ($dish->price * 0.1));
});
}Formatting Data Examples
Sometimes, you need might to display data in a human-friendly way. This is often the case with dates, currencies and boolean values.
Custom Fields provides you a convenient way to prepare and format your data.
Here are examples of some common ways of data formatting.
Date
This example adds a new column created_at_formatted to display the formatted created_at datetime column.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
use Illuminate\Support\Carbon;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('created_at') // 2024-01-20 10:05:44
->add('created_at_formatted', function ($dish) {
return Carbon::parse($dish->created_at)->format('d/m/Y H:i'); //20/01/2024 10:05
});
}Currency
Displaying formatted currency can vastly improve the user experience.
This example adds a new column price_in_eur to display the formatted price.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
use Illuminate\Support\Number;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('price') // 170.90
->add('price_in_eur', function ($dish) {
return Number::currency($dish->price, in: 'EUR', locale: 'pt_PT'); //€ 170,90
});
}Boolean
Boolean values are not user-friendly.
This example adds a new column in_stock_label to return yes/no instead of true/false in in_stock.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('in_stock') // 1/0
->add('in_stock_label', function ($dish) {
return $dish->in_stock ? 'Yes' : 'No'; // Yes/No
});
}Text summary
Large amounts of text can compromise the readability of your Table
This example adds a description_excerpt with only the first 8 words of the description field.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('description')
->add('description_excerpt', function ($dish) {
return str(e($dish->description))->words(8); //Gets the first 8 words
});
}❗ WARNING
Be careful: Data returned in Custom Fields is NOT escaped by default. As a result, your application might be vulnerable to XSS attacks.
It's highly recommended to use Laravel's e() helper to escape data return in Custom Fields.
HTML Link
Sometimes, you may need to render an HTML link inside a Table cell.
This example adds a search_dish_name column with a link to search for a dish name on Google, based on the name field.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('name')
->add('search_dish_name', function ($dish) {
return sprintf(
'<a href="https://www.google.com/search?q=%s">Search "%s"</a>',
urlencode(e($dish->name)),
e($dish->name)
);
});
}❗ WARNING
Be careful: Data returned in Custom Fields is NOT escaped by default. As a result, your application might be vulnerable to XSS attacks.
It's highly recommended to use Laravel's e() helper to escape data return in Custom Fields.
🚀 See it in action
See an interactive example generating an HTML Link.
Dropdown Menu
Dropdown menus allow users to choose an option from a pre-established list. This can be very useful in a grid for manipulating data.
In the example below, we have created a Blade component that receives a list of options and the select category ID of each item. The component is rendered as a Custom Field, and it displays a select input with the category of each dish pre-selected.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
public function fields(): PowerGridFields
{
$options = collect([1 => 'Category A', 2 => 'Category B', 1 => 'Category C' ]);
return PowerGrid::fields()
->add('id')
->add('name')
->add('category_name', function ($dish){
return Blade::render('<x-select-category type="occurrence" :options=$options :dishId=$dishId :selected=$selected/>',
[
'options' => $options,
'dishId' => intval($dish->id),
'selected' => intval($dish->category_id)
]);
});
}//app/View/Components/SelectCategory.php
namespace App\View\Components;
use Closure;
use Illuminate\Contracts\View\View;
use Illuminate\Support\Collection;
use Illuminate\View\Component;
class SelectCategory extends Component
{
/**
* Create a new component instance.
*/
public function __construct(public Collection $options, public int $dishId, public string $selected)
{
}
/**
* Get the view / contents that represent the component.
*/
public function render(): View|Closure|string
{
return view('components.select-category');
}
}//resources/views/components/select-category.blade.php
@props(['selected', 'dishId'])
<div>
<select wire:change="categoryChanged($event.target.value, {{ $dishId }})">
@foreach ($options as $id => $name)
<option
value="{{ $id }}"
@if ($id == $selected)
selected="selected"
@endif
>
{{ $name }}
</option>
@endforeach
</select>
</div>🚀 See it in action
See an interactive example using Dropdown Menu on a Table.
Image
This example demonstrates how to display images within a cell.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('name')
->add('avatar', function ($dish) {
return '<img src="' . asset("images/{$dish->id}.jpg") . '">';
});
}🚀 See it in action
See an interactive example using Images on a Table.
Blade Component
Combining Custom Fields with Blade components can be a powerful tool to display customized content inside cells.
You can return a Blade Component as demonstrated below:
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
use Illuminate\Support\Facades\Blade;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('name')
->add('rating_stars', fn ($dish) => Blade::render('<x-rate rate="' . $dish->rating . '"/>'));
}🚀 See it in action
See an interactive example using a Custom Field Blade Component.
Enum
When you have an Enum with labels, you can use a closure to display label values instead of the default case values.
// app/Enums/Diet.php
enum Diet: int
{
case ALL = 0;
case VEGAN = 1;
case CELIAC = 2;
public function labels(): string
{
return match ($this) {
self::ALL => "🍽️ All diets",
self::VEGAN => "🌱 Suitable for Vegans",
self::CELIAC => "🥜 Suitable for Celiacs",
};
}
}The following example renders 🍽️ All diets instead of the database value 0.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\PowerGridFields;
use App\Enums\Diet;
public function fields(): PowerGridFields
{
return PowerGrid::fields()
->add('name')
->add('diet', function ($dish) {
return Diet::from($dish->diet)->labels();
});
}🚀 See it in action
See an interactive example using Enums.
Exporting Data
Sometimes, it may be necessary to omit certain formatted Columns when exporting data but still show them in the grid. This might be the case with images or HTML links.
To remove these Columns, see Exclude Columns From Exporting.