Usage Guide

Creating Reports

Navigate to "Custom Reports" in your Filament panel
Click "New Custom Report"
Enter a name and select your data model

Column Configuration

Adding Columns

Use the column builder to add:

Direct model fields
Related model fields through relationships
Aggregate columns for calculations

Column Formatting

Click the paint brush icon to customize:

Display Options:

Text color (danger, gray, info, primary, success, warning)
Text size (xs, sm, md, lg)
Font weight (thin to black)
Font family (sans-serif, serif, monospace)

Text Enhancements:

Prefix/suffix text (e.g., "$" for currency, "%" for percentages)
Heroicons with customizable position and color
Character/word limits with truncation
Line clamping for multi-line text
HTML rendering (sanitized)

Numeric Formatting:

Decimal places control
Locale-specific formatting (e.g., "en_US", "de_DE")
Value division (e.g., cents to dollars with divideBy: 100)

Date Formatting:

Predefined formats: date only, datetime, time only, relative time
Custom PHP date format strings
Date tooltips on hover

Interactive Features:

Copy to clipboard functionality
Custom success messages

Aggregate Columns

Create calculated columns using the aggregate configuration modal (gear icon):

Supported Functions:

COUNT - Count related records
COUNT DISTINCT - Count unique values
SUM - Total numeric values
AVG - Average values
MIN/MAX - Find minimum/maximum values

Aggregate Filtering:

Complex filter conditions
Multiple filter groups with AND/OR logic
Field and relationship-based filters

Relationship Support

Data Lens intelligently handles all Laravel relationship types:

Single-Value Relationships:

BelongsTo - Direct parent record access
HasOne - Single related record fields
HasOneThrough - Navigate through intermediate models
MorphOne - Polymorphic single relationships

Multi-Value Relationships:

HasMany - Aggregate multiple related records
HasManyThrough - Aggregate through intermediates
BelongsToMany - Many-to-many aggregations

Report Filtering

Use the visual filter builder to create conditions with:

Field filters with various operators (equals, contains, between, etc.)
Relationship filters for related data
Nested AND/OR logic

Share reports with other users in your organization.

Open a report and click "Edit"
In the "Share with Users" dropdown, select users
Save the report

Notifications

When you share a report, selected users receive:

In-app notification - Appears in the notification bell
Email notification - Sent to their email address

Both notification types can be enabled/disabled in configuration. See Report Sharing Configuration for details.

Access Control

Report creators always have access
Shared users can view the report
Users only see other users from their tenant in the sharing dropdown

Data Export

Export report data in multiple formats:

Manual Export

Navigate to your report
Click the export button in the toolbar
Select format (CSV or XLSX)
Download begins automatically

Queued Exports

For large datasets, exports are automatically queued:

Progress tracked via notifications
Download link provided when complete
Configurable chunk size for performance

Export Configuration

// Per-panel settings in your panel provider
DataLensPlugin::make()
    ->exportsEnabled()
    ->exportFormats(['csv', 'xlsx'])
    ->defaultExportFormat('xlsx')
    ->useTimestampsInFilename(false)

// Global settings in config/data-lens.php
'exports' => [
    'should_queue' => true,  // Queue large exports
    'chunk_size' => 1000,    // Rows per batch
],

Report Scheduling

Schedule reports for automatic generation and email delivery.

Setting Up Schedules

Note: The Schedules tab only appears when scheduling is enabled in the plugin configuration.

Open a report and navigate to the "Schedules" tab
Click "New Schedule"
Configure schedule settings:
- Name: Schedule identifier
- Frequency: One-time, daily, weekly, monthly
- Recipients: Email addresses for delivery
- Export Format: CSV or XLSX
- Email Content: Subject and optional body text

Frequency Options

One-time: Run once on a specific date
Daily: Every day at specified time
Weekdays: Monday-Friday only
Weekly: Specific days of the week
Monthly by Date: e.g., 1st and 15th
Monthly by Day: e.g., First Monday

Schedule Requirements

Add to your Laravel scheduler (routes/console.php for Laravel 11):

use Illuminate\Support\Facades\Schedule;

Schedule::command('data-lens:check-scheduled-reports')->everyMinute();

API Access

Access reports programmatically via REST API.

Enabling API Access

Enable API in plugin configuration:
```
DataLensPlugin::make()->apiEnabled()
```
Configure API settings for individual reports:
- Navigate to report settings
- Enable API access
- Choose authentication method
- Generate API key if needed

Authentication Methods

API Key:

curl "https://example.com/api/data-lens/reports/{uuid}/data?api_key=YOUR_KEY"

Sanctum Token:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://example.com/api/data-lens/reports/{uuid}/data"

No Authentication (if enabled):

curl "https://example.com/api/data-lens/reports/{uuid}/data"

API Endpoints

GET /api/data-lens/reports/{uuid} - Report metadata
GET /api/data-lens/reports/{uuid}/data - Report data (paginated)

Pagination Parameters

page - Page number (default: 1)
per_page - Records per page (default: 50, max: 1000)

Example:

GET /api/data-lens/reports/{uuid}/data?page=2&per_page=100

Multi-Tenant Usage

For multi-tenant applications:

Enable tenant awareness in configuration
Reports automatically scope to current tenant
API calls respect tenant boundaries
Scheduled reports maintain tenant context

Performance Tips

Add database indexes on frequently filtered columns
Use filters to limit dataset size
Enable caching for complex relationships
Queue large exports
Optimize database queries with proper indexes

Documents