`.
## Wrapper / Layout
Control each metric's wrapper `
` attributes via the `wrapper` option:
```php
$this->addMetric('big_chart', [
'type' => 'line',
'label' => 'Revenue',
'wrapper' => ['class' => 'col-md-12'],
]);
$this->addMetric('small_stat', [
'type' => 'stat',
'label' => 'Users',
'wrapper' => ['class' => 'col-md-3', 'style' => 'min-height: 120px;'],
]);
```
Default wrappers per type are defined in the config file.
## Filters
Auto-injected filters (added before `setupReportOperation()`):
- `report_date_range` — `date_range` filter
- `report_interval` — `dropdown` filter (Daily, Weekly, Monthly, Yearly)
Remove or override them:
```php
protected function setupReportOperation()
{
$this->crud->removeFilter('report_interval');
$this->crud->removeFilter('report_date_range');
$this->crud->addFilter([
'name' => 'report_date_range',
'type' => 'date_range',
'label' => 'Period',
], false, function ($value) {
// custom logic
});
// ... add metrics
}
```
## Metrics API
Methods available via the `ReportOperation` trait:
| Method | Description |
|--------|-------------|
| `$this->addMetric(string $name, array $config)` | Add a metric |
| `$this->removeMetric(string $name)` | Remove a metric by name |
| `$this->metric(string $name)` | Get a single `CrudMetric` instance |
| `$this->metrics()` | Get all metrics as flat associative array |
| `$this->metricGroups()` | Get all metric groups for rendering |
| `$this->modifyMetric(string $name, array $config)` | Update properties of an existing metric |
| `$this->addMetricGroup(array $attributes, Closure $callback)` | Add a visual metric group |
| `$this->groupMetrics(string $groupName, array $metricNames)` | Batch metrics into a single AJAX request |
```php
$this->modifyMetric('total_orders', [
'label' => 'All Orders',
'wrapper' => ['class' => 'col-md-6'],
]);
$this->removeMetric('avg_order_value');
```
## Configuration
Publish:
```bash
php artisan vendor:publish --tag=backpack-report-config
```
Config file `config/backpack/operations/report.php`:
```php
return [
'contentClass' => 'col-md-12',
'defaultPeriodColumn' => 'created_at',
'defaultInterval' => 'day', // day | week | month | year
'defaultWrappers' => [
'stat' => ['class' => 'col-md-3'],
'line' => ['class' => 'col-md-6'],
'bar' => ['class' => 'col-md-6'],
'stacked-bar' => ['class' => 'col-md-6'],
'stacked-line' => ['class' => 'col-md-6'],
'pie' => ['class' => 'col-md-6'],
'view' => ['class' => 'col-md-12'],
'table' => ['class' => 'col-md-12'],
],
];
```
Override per-controller:
```php
$this->crud->setOperationSetting('contentClass', 'col-md-10 mx-auto');
```
## Overriding Views
Create override files in `resources/views/vendor/backpack-report/`:
| View | Purpose |
|------|---------|
| `report.blade.php` | Main report page layout |
| `metrics/stat.blade.php` | Stat card template |
| `metrics/line.blade.php` | Line chart (delegates to `chart.blade.php`) |
| `metrics/bar.blade.php` | Bar chart (delegates to `chart.blade.php`) |
| `metrics/pie.blade.php` | Pie chart template |
| `metrics/stacked-bar.blade.php` | Stacked bar (delegates to `stacked-chart.blade.php`) |
| `metrics/stacked-line.blade.php` | Stacked line (delegates to `stacked-chart.blade.php`) |
| `metrics/stacked-chart.blade.php` | Shared stacked chart container |
| `metrics/chart.blade.php` | Shared chart container (canvas + Chart.js) |
| `metrics/view.blade.php` | View metric card |
| `metrics/inc/report_scripts.blade.php` | JS for AJAX fetching and metric dispatch |
| `buttons/report.blade.php` | Report button in List operation |
## Full Example
```php
addMetricGroup(['class' => 'row'], function () {
$this->addMetric('total_orders', [
'type' => 'stat', 'label' => 'Total Orders',
'aggregate' => 'count', 'period' => 'created_at',
'compare' => true, 'wrapper' => ['class' => 'col-md-4'],
]);
$this->addMetric('total_revenue', [
'type' => 'stat', 'label' => 'Total Revenue',
'column' => 'total', 'aggregate' => 'sum',
'format' => '$:value', 'period' => 'created_at',
'compare' => true, 'wrapper' => ['class' => 'col-md-4'],
]);
$this->addMetric('avg_order', [
'type' => 'stat', 'label' => 'Avg Order Value',
'column' => 'total', 'aggregate' => 'avg',
'format' => '$:value', 'wrapper' => ['class' => 'col-md-4'],
]);
});
// Charts
$this->addMetricGroup(['class' => 'row mt-2'], function () {
$this->addMetric('orders_over_time', [
'type' => 'line', 'label' => 'Orders Over Time',
'aggregate' => 'count', 'period' => 'created_at',
]);
$this->addMetric('revenue_over_time', [
'type' => 'bar', 'label' => 'Revenue Over Time',
'column' => 'total', 'aggregate' => 'sum',
'period' => 'created_at',
]);
});
// Pie chart
$this->addMetricGroup(['class' => 'row mt-2'], function () {
$this->addMetric('orders_by_status', [
'type' => 'pie', 'label' => 'Orders by Status',
'column' => 'status',
]);
});
// Stacked bar
$this->addMetricGroup(['class' => 'row mt-2'], function () {
$this->addMetric('orders_stacked_by_status', [
'type' => 'stacked-bar', 'label' => 'Orders by Status Over Time',
'aggregate' => 'count', 'period' => 'created_at',
'stack_by' => 'status',
'colors' => [
'pending' => 'rgba(255, 206, 86, 0.8)',
'completed' => 'rgba(0, 200, 83, 0.8)',
'cancelled' => 'rgba(255, 99, 132, 0.8)',
],
]);
});
// Batch stat cards into one AJAX request
$this->groupMetrics('stats', ['total_orders', 'total_revenue', 'avg_order']);
}
}
```
## JavaScript Events
DOM events dispatched on every metric refresh:
| Event | Target | Detail |
|-------|--------|--------|
| `backpack:metric:updated` | Widget element (bubbles) | `{ name, type, data, widget }` |
| `backpack:metric:updated:{name}` | `document` | `{ name, type, data, widget }` |
| `backpack:metric:error` | Widget element (bubbles) | `{ name }` |
| `backpack:metric:error:{name}` | `document` | `{ name }` |
Listen to a specific metric:
```js
document.addEventListener('backpack:metric:updated:total_orders', function(e) {
console.log('Total orders:', e.detail.data.value);
});
```
Listen to all metrics from a parent container:
```js
document.getElementById('report-metrics').addEventListener('backpack:metric:updated', function(e) {
console.log(e.detail.name, 'refreshed with', e.detail.data);
});
```
Error handling:
```js
document.addEventListener('backpack:metric:error:total_orders', function(e) {
console.warn('Failed to load total_orders metric');
});
```
Events fire for all metric types (stat, line, bar, pie, view, and custom types). This is the recommended way to add JS behavior to `view` metrics, since `