Livewire PowerGrid

Appearance

Exporting Data ​

This section covers the PowerGrid Data Export functionality.

Here you will find:

Enable Data Export ​

To enable Data Exporting, follow the steps described below.

1. Add the WithExport Trait ​

First, add the WithExport Trait to your PowerGrid Component, as illustrated in the example below.

php
// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;  

class DishTable extends PowerGridComponent
{
    use WithExport; 
}

2. Configure the Export Feature ​

Next, add a call to Export::make() in your Component's setUp() method. You must provide the parameter $fileName, with the desired output file name.

To configure the feature, proceed to chain to make() as many Data Export Configuration Methods as you need.

php
// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\Components\SetUp\Exportable; 
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;

class DishTable extends PowerGridComponent
{
    use WithExport;

    public function setUp(): array
    {
        PowerGrid::exportable(fileName: 'my-export-file') 
            ->type(Exportable::TYPE_XLS, Exportable::TYPE_CSV), 
    }
}

The example above illustrates the Exportable featured enabled for Microsoft Excel and CSV files.

🚀 See it in action

See an interactive example using Data Export.

Exclude Columns From Exporting ​

Sometimes, it may be necessary to omit certain Columns when exporting data but still show them in the grid. This might be the case with images or HTML links.

To implement this scenario, you should use the method Column::visibleInExport() to control whether the column will be included in the export file and the method Column::hidden() to hide the column in the grid.

By default, Action Column are not included in export, the method Column::visibleInExport() will allow you to add them if you need.

Using these two methods, you can create a column with formatted data, displayed in the grid but hidden in export, and a column with raw data hidden in the grid but included in the exported file.

Example:

php
// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Column;

class DishTable extends PowerGridComponent
{
public function columns(): array
    {
        return [
            Column::make('ID', 'id')
                ->searchable()
                ->sortable(),
 
            //Displayed in the grid, but not in the exported file
            Column::make('Name', 'name_html_link', 'name')
                ->visibleInExport(false)
                ->sortable(),
 
            //Hidden in the grid, but included in the exported file
            Column::make('Name', 'name')
                ->searchable()
                ->hidden()
                ->visibleInExport(true),
        ];
    }
}

File Appearance ​

Column width ​

Specify column and size for Openspout Column Width.

Example:

php
// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\Components\SetUp\Exportable;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;

class DishTable extends PowerGridComponent
{
    use WithExport;

    public function setUp(): array
    {
        PowerGRid::exportable(fileName: 'my-export-file') 
            ->columnWidth([
                        2 => 30,
                        4 => 20,
            ]),
    }
}

📝 NOTE

This feature is only available for XLS files.

Striped Rows ​

You can add stripped row style to your outputted file style using the striped() and passing the $color with a color hex code.

If used without passing a color, d0d3d8 is used by default.

Example:

php
// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\Components\SetUp\Exportable;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;

class DishTable extends PowerGridComponent
{
    use WithExport;

    public function setUp(): array
    {
        PowerGrid::exportable(fileName: 'my-export-file') 
            ->striped('A6ACCD'),
    }
}

📝 NOTE

This feature is only available for XLS files.

Queue Export ​

If you are working with lots of data, it's recommended to enable Queue Export.

Queue export will divide your records into batches, increasing the export performance.

For instance, if you have 1 million records, you may set up 10 queues. Each batch will contain a total of 100,000 records.

📝 NOTE

Queues only take effect when exporting ALL records. If you have manually selected some records, they will be exported in a single batch.

Enable Queue Export ​

To enable the Queue Export feature, you must configure the methods by calling the Facade Exportable within the setUp() method.

Configuration Methods ​

->queues(): Number of queues to be used.

->onQueue(): Queue name. If blank, default will be used.

->onConnection(): Connection.

public property $showExporting: Show the export progress on the screen if true (default).

💡 TIP

Read more about Batches in Laravel's Queue documentation.

Example:

php
// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\Components\SetUp\Exportable;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;

class DishTable extends PowerGridComponent
{
    public function setUp()
    {
        return [
            PowerGrid::exportable('export')
               ->striped()
               ->type(Exportable::TYPE_XLS, Exportable::TYPE_CSV)
               ->queues(6)
               ->onQueue('my-dishes')
               ->onConnection('redis'),
        ];
    }
}

Back-end ​

You can manipulate the state of processing in the back-end:

php
public function onBatchThen(Batch $batch): void
{
    // All jobs completed successfully...
    // TODO notify user!
}

public function onBatchCatch(Batch $batch, Throwable $e): void
{
   // First batch job failure detected...
   // TODO add to failure log.
}

public function onBatchFinally(Batch $batch): void
{
   // The batch has finished executing...  
   // TODO add to success log.
}

Front-end ​

You can manipulate the state of processing in the front end (Livewire):

php
public function onBatchExecuting(Batch $batch): void
{
    // send alert

   if ($batch->finished()) {
       $this->dispatchBrowserEvent('batch-finished', $batch);
       
       return;
   } 
   
   $this->dispatchBrowserEvent('batch-executing', $batch);
}

💡 TIP

Read more about Batches in Laravel's Batch documentation.

Passing Attributes ​

When performing a Batch Export, you might need to pass some attributes to the datasource() method.

PowerGrid automatically injects all public attributes of your Component inside the variable $parameters in the dataset() method, as demonstrated in the next example.

php
// app/Livewire/DishTable.php

use App\Models\Dish;
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use Illuminate\Database\Eloquent\Builder; 

class DishTable extends PowerGridComponent
{
    public $categoryId;

    public function datasource(array $parameters): ?Builder
    {
        return Dish::with('category')
            ->where('category_id', $parameters['categoryId'] ?? $this->category->id);
    }
}

Data Export Configuration Methods ​

make() ​

Make new \PowerComponents\LivewirePowerGrid\Facades\PowerGrid; facade.

ParametersDescription
(string) $fileNameName of the file that will contain exported data
php
PowerGrid::exportable(fileName: 'my-export-file'),

type() ​

Set the file types available for data exporting.

ParametersDescription
(string) $typesFile types (Exportable::TYPE_XLS, Exportable::TYPE_CSV)

Example:

php
PowerGrid::exportable('my-export-file')
    ->type(types: Exportable::TYPE_XLS, Exportable::TYPE_CSV),

csvSeparator() ​

When exporting to CSV, you may configure the field separator and field delimiter:

ParametersDescription
(string) $separatorCSV Separator
(string) $delimiterCSV Delimiter
php
PowerGrid::exportable('my-export-file')
    ->type(Exportable::TYPE_CSV)
    ->csvSeparator(separator: '|')
    ->csvDelimiter(delimiter: "'"),

The code above would result in something similar to the example below.

plain
ID|Dish|Price
1|'Pizza'|10.00
2|'Bacon Cheeseburger'|4.99
3|'Caesar Salad'|7.50

stripTags() ​

If you're using HTML when formatting your data, this allow to automatically strip HTML tags from file content when exporting, default to false.

ParametersDescription
(boolean) $valueStrip tags when exporting

Example:

php
PowerGrid::exportable('my-export-file')
    ->stripTags(true),

csvDelimiter() ​

See the csvSeparator() example.

striped() ​

See Striped Rows.

columnWidth() ​

See Column Width.

Created By Luan Freitas and @DanSysAnalyst