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.
// 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.
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\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.
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:
// 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(visible: true)
->sortable(),
//Hidden in the grid, but included in the exported file
Column::make('Name', 'name')
->searchable()
->hidden()
->visibleInExport(visible: true),
];
}
}
File Appearance โ
Column width โ
Specify column and size for Openspout Column Width.
Example:
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\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.
Example:
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\Exportable;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
class DishTable extends PowerGridComponent
{
use WithExport;
public function setUp(): array
{
PowerGrid::exportable(fileName: 'my-export-file')
->stripe('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:
// app/Livewire/DishTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Traits\WithExport;
use PowerComponents\LivewirePowerGrid\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:
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):
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.
// 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.
Parameters | Description |
---|---|
(string) $fileName | Name of the file that will contain exported data |
PowerGrid::exportable(fileName: 'my-export-file'),
type() โ
Set the file types available for data exporting.
Parameters | Description |
---|---|
(string) $types | File types (Exportable::TYPE_XLS , Exportable::TYPE_CSV ) |
Example:
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
:
Parameters | Description |
---|---|
(string) $separator | CSV Separator |
(string) $delimiter | CSV Delimiter |
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.
ID|Dish|Price
1|'Pizza'|10.00
2|'Bacon Cheeseburger'|4.99
3|'Caesar Salad'|7.50
csvDelimiter() โ
See the csvSeparator() example.
striped() โ
See Striped Rows.
columnWidth() โ
See Column Width.