## Creating Custom Reports in Alpha Insights

The Report Builder in Alpha Insights allows you to create fully customizable reports tailored to your specific business needs. You can add widgets, arrange them in flexible layouts, apply filters, and save your reports for future use.

### Why Create Custom Reports?

Every business has unique questions they need to answer. Custom reports let you:

- Focus on specific products, categories, or time periods
- Compare different metrics side-by-side
- Track the metrics that matter most to your business
- Create executive summaries or detailed analysis reports
- Monitor ad campaign performance with profit data

### Accessing the Report Builder

1. Go to Alpha Insights → Reports in your WordPress dashboard
2. Click the Create New Report button
3. You'll see the Report Builder interface with your first empty report

### Understanding the Report Builder Interface

The Report Builder consists of several key areas:

#### 1. Top Toolbar

The toolbar at the top contains essential controls:

- Report Name: Click to edit the report title
- Date Range Selector: Choose which dates to include in your report
- Filters Button: Open advanced filters for products, orders, customers, etc.
- Settings Button: Access report settings and configuration
- Build Mode Toggle: Enable/disable editing mode (more on this below)
- Save Button: Appears when you have unsaved changes

#### 2. Report Canvas

This is the main area where your widgets are displayed. Reports use a flexible 12-column grid system that automatically adjusts to different screen sizes.

#### 3. Row Inserters

Between each row (and at the top and bottom of your report), you'll see + Add Row buttons when Build Mode is enabled. These let you add new rows with widgets.

### Build Mode: The Key to Editing Reports

Important: To edit, move, resize, or delete widgets, you must enable Build Mode using the toggle switch in the top toolbar.

#### What is Build Mode?

Build Mode is a special editing state that unlocks all customization features. When Build Mode is disabled, your report is in "view-only" mode - perfect for presenting data without accidentally making changes.

#### Enabling Build Mode

1. Look for the Build Mode toggle switch in the top-right area of the toolbar
2. Click the toggle to turn it ON (it will turn blue/active)
3. You'll immediately see editing controls appear on all widgets

#### What Changes When Build Mode is Enabled?

When you enable Build Mode, you'll see:

- Grab Zones: A hover-sensitive area at the top of each widget
- Widget Actions: Buttons appear in the grab zone when you hover over a widget
- Resize Handles: Appear on the sides of widgets
- Row Inserters: Buttons to add new rows between existing rows
- Row Controls: Options to edit or delete entire rows

#### Disabling Build Mode

When you're done editing:

1. Click the Build Mode toggle to turn it OFF
2. If you have unsaved changes, you'll be prompted to save or discard them
3. Choose Save & Exit Build Mode to keep your changes
4. Or choose Discard & Exit Build Mode to revert to the last saved version

Tip: Build Mode is session-based, so it persists across different reports until you explicitly turn it off. This lets you quickly edit multiple reports without re-enabling it each time.

### Widget Actions: The Hover Section

When Build Mode is enabled, hovering over any widget reveals a grab zone at the top with action buttons. These buttons let you interact with the widget:

#### Available Widget Actions

When you hover over a widget in Build Mode, you'll see these action buttons in the grab zone:

- Edit (Pencil Icon): Opens the widget configuration modal to change settings, metrics, colors, and more
- Duplicate (Copy Icon): Creates a copy of the widget in the same row
- Download (Download Icon): Exports widget data as CSV (only appears for charts and tables)
- Delete (Trash Icon): Removes the widget from the report

#### How to Access Widget Actions

1. Make sure Build Mode is enabled
2. Move your mouse over any widget
3. The grab zone at the top of the widget will become visible
4. The action buttons will appear in the grab zone
5. Click any button to perform that action

Note: You cannot access widget actions when Build Mode is disabled. The grab zone and all action buttons are hidden in view-only mode.

### Moving Widgets

With Build Mode enabled, you can reorganize your report by moving widgets:

#### How to Move a Widget

1. Enable Build Mode
2. Hover over the widget you want to move
3. Click and hold on the grab zone (the top section, but not on the action buttons)
4. Drag the widget to a new location
5. As you drag, you'll see drop zones highlighted throughout the report
6. Release the mouse button to drop the widget in the new location

#### Drop Zone Types

While dragging a widget, you'll see several types of drop zones:

- Column Drop Zones: Drop into existing columns to replace or add alongside other widgets
- Row Inserter Drop Zones: Drop between rows to create a new row with your widget
- Empty Column Fillers: Drop into empty spaces in partially-filled rows

The active drop zone will be highlighted as you hover over it.

### Resizing Widgets

Widgets use a 12-column grid system. You can resize widgets to span anywhere from 1 to 12 columns.

#### How to Resize a Widget

1. Enable Build Mode
2. Look for the resize handle on the right side of any widget
3. Click and drag the resize handle left or right
4. As you resize, you'll see a width indicator showing the column count
5. Release to set the new width

Tip: Widgets will automatically adjust their layout based on their width. Narrower widgets may stack elements vertically, while wider widgets can display more data horizontally.

### Adding Widgets to Your Report

#### Method 1: Using Row Inserters

1. Enable Build Mode
2. Click any + Add Row button (above your first widget, between rows, or at the bottom)
3. Choose how many columns you want in the row (1, 2, 3, 4, or 6 columns)
4. Empty widget placeholders will appear
5. Click + Add Widget in any placeholder
6. Select a widget type from the widget selector
7. Configure the widget in the modal that appears
8. Click Save Widget

#### Method 2: Adding to Existing Rows

If a row has empty space (doesn't fill all 12 columns), you'll see an empty column filler where you can add more widgets:

1. Enable Build Mode
2. Look for empty gray placeholders in existing rows
3. Click + Add Widget in the placeholder
4. Select and configure your widget

### Editing Widgets

To modify an existing widget's configuration:

1. Enable Build Mode
2. Hover over the widget
3. Click the Edit button (pencil icon) in the grab zone
4. The Widget Configuration modal opens
5. Make your changes to:
   - Widget title and icon
   - Selected metrics or data
   - Colors and visual styling
   - Chart types and display options
   - Filters and sorting
6. Click Save Widget to apply changes

### Available Widget Types

Alpha Insights offers several widget types for different visualization needs:

#### Metric Card

Best for: Displaying a single key metric prominently

Features: Large number display, optional comparison to previous period, colored indicators, custom icons

Use cases: Total revenue, profit margin, order count, average order value

#### Metric List

Best for: Showing multiple related metrics in a compact list

Features: Multiple metrics in one widget, icons for each metric, optional change indicators

Use cases: Dashboard summary cards, KPI lists, grouped metrics

#### Line Chart

Best for: Showing trends over time

Features: Single or multiple lines, customizable time granularity, tooltips, legends

Use cases: Revenue trends, profit over time, order volume patterns

#### Bar Chart

Best for: Comparing values across categories

Features: Vertical or horizontal orientation, single or grouped bars, customizable colors

Use cases: Product comparisons, category performance, top/bottom rankings

#### Pie Chart / Doughnut Chart

Best for: Showing proportions and percentages

Features: Percentage labels, customizable colors, legend, hover tooltips

Use cases: Revenue by category, traffic source distribution, expense breakdown

#### Data Table

Best for: Displaying detailed, sortable data with multiple columns

Features: Sortable columns, row limits, customizable columns, conditional formatting

Use cases: Product lists with metrics, order details, customer segments

#### Simple Table

Best for: Clean, formatted tables with custom structure

Features: Custom row and column layout, manual data entry, styling options

Use cases: Summary tables, comparison matrices, custom reports

#### Profit & Loss Statement

Best for: Complete financial reporting

Features: Automatic P&L calculation, revenue/costs/expenses breakdown, net profit calculation

Use cases: Monthly financial reports, executive summaries, accounting reports

#### Heading Widget

Best for: Adding section titles and descriptions to your report

Features: Customizable text, size, and color

Use cases: Report sections, explanatory text, visual organization

### Working with Rows

#### Adding Rows

Click any + Add Row button and choose your column layout. Available layouts:

- 1 Column: Full-width (12 columns) - great for large charts or tables
- 2 Columns: Two equal widgets (6 columns each) - good for side-by-side comparison
- 3 Columns: Three equal widgets (4 columns each) - ideal for metric cards
- 4 Columns: Four equal widgets (3 columns each) - compact KPI display
- 6 Columns: Six equal widgets (2 columns each) - very compact layout

#### Editing Rows

When Build Mode is enabled, hover over the left side of any row to see row controls:

- Edit Row: Change the column layout or add/remove columns
- Delete Row: Remove the entire row and all widgets in it

### Using Filters

Filters control what data appears throughout your entire report.

#### Date Filters

Use the date range selector in the toolbar:

- Quick Presets: Today, Yesterday, Last 7 Days, Last 30 Days, This Month, Last Month, This Year, All Time
- Custom Range: Pick specific start and end dates
- Comparison Toggle: Enable to compare current period to previous period

#### Advanced Filters

Click the Filters button in the toolbar to access:

- Product Filters: Specific products, categories, tags
- Order Filters: Order status, device type, query parameters (UTM tracking)
- Customer Filters: Billing country
- Traffic Source Filters: Traffic source categories, device type, query parameters
- Campaign Filters: Specific ad campaigns from Facebook Ads or Google Ads (requires integration)
- Expense Filters: Expense categories, paid/unpaid status, recurring/one-time
- Website Traffic Filters: Traffic sources, device type, session events, page URL contains, query parameters

All filters apply to the entire report - every widget respects the active filters.

For a complete guide to all available filters, see the Using Report Filters documentation.

### Saving Your Report

#### Manual Save

1. Make your changes to the report
2. The Save Report button will appear in the toolbar
3. Click Save Report
4. Your changes are saved to the database

#### Auto-Save on Build Mode Exit

When you disable Build Mode with unsaved changes:

1. A confirmation modal appears
2. Choose Save & Exit Build Mode to save changes
3. Or Discard & Exit Build Mode to revert changes
4. Or Cancel to stay in Build Mode

### Step-by-Step: Creating Your First Custom Report

Let's create a practical example: "Monthly Profit Overview"

#### Step 1: Create and Name the Report

1. Go to Alpha Insights → Reports
2. Click Create New Report
3. Click on "Untitled Report" at the top to rename it to "Monthly Profit Overview"

#### Step 2: Set the Date Range

1. Click the date selector in the toolbar
2. Choose This Month
3. Enable Compare to Previous Period to see last month's comparison

#### Step 3: Enable Build Mode

1. Look for the Build Mode toggle in the top toolbar
2. Click it to turn it ON
3. Editing controls will appear

#### Step 4: Add a Summary Row

1. Click + Add Row
2. Select 3 Columns
3. Three empty placeholders appear
4. In the first placeholder, click + Add Widget
5. Select Metric Card
6. Choose metric: orders.totals.revenue
7. Set title: "Total Revenue"
8. Set color: Blue
9. Click Save Widget

6. Repeat for the second placeholder with orders.totals.profit (green color)
7. Repeat for the third placeholder with orders.totals.profit_margin (purple color)

#### Step 5: Add a Trend Chart

1. Click + Add Row below your metric cards
2. Select 1 Column (full width)
3. Click + Add Widget
4. Select Line Chart
5. Set title: "Profit Trend"
6. Choose metrics: orders.data_by_date.profit
7. Set time granularity: Daily
8. Click Save Widget

#### Step 6: Add Top Products Table

1. Click + Add Row
2. Select 1 Column
3. Click + Add Widget
4. Select Data Table
5. Set title: "Top 10 Products by Profit"
6. Choose entity: Products
7. Select columns: Product Name, Units Sold, Revenue, Profit, Profit Margin
8. Set sort by: Profit (descending)
9. Set row limit: 10
10. Click Save Widget

#### Step 7: Save and View

1. Click Save Report in the toolbar
2. Turn off Build Mode to view your report
3. Your custom report is now saved and accessible from the Reports page

### Tips for Effective Reports

#### 1. Start with Key Metrics at the Top

Place your most important numbers (revenue, profit, orders) in metric cards at the top of the report. This gives an immediate overview.

#### 2. Use Visual Hierarchy

- Top: Summary metrics (what happened)
- Middle: Trend charts (how it changed over time)
- Bottom: Detailed tables (drill-down data)

#### 3. Limit Widget Count

Keep reports focused. 5-8 widgets is usually enough. If you need more analysis, create a separate report rather than cramming everything into one.

#### 4. Use Consistent Colors

- Green for profit and positive metrics
- Blue for revenue and neutral metrics
- Red for costs and expenses
- Purple/Orange for special metrics

#### 5. Enable Comparison for Context

Always enable "Compare to Previous Period" in metric cards to show whether numbers are improving or declining.

#### 6. Name Reports Descriptively

Use clear, specific names:

- Good: "Weekly Product Performance - November 2024"
- Bad: "Report 1" or "My Report"

#### 7. Test Different Screen Sizes

Preview your report at different screen sizes. The responsive grid will adjust automatically, but you may want to adjust widget widths for better mobile display.

### Common Questions

#### Why can't I edit my widgets?

Make sure Build Mode is enabled. Widget actions are only available when Build Mode is turned on.

#### How do I delete a widget?

Enable Build Mode, hover over the widget, and click the trash icon in the grab zone at the top of the widget.

#### Can I move a widget to a different row?

Yes! Enable Build Mode, click and drag the widget from its grab zone, and drop it on a row inserter or into another row's drop zone.

#### How do I make a widget full-width?

Enable Build Mode and drag the right resize handle all the way to the right until it spans 12 columns.

#### Do filters affect all widgets?

Yes. When you apply filters (date range, products, etc.), they affect every widget in the report.

#### Can I export individual widget data?

Yes! Enable Build Mode, hover over a chart or table widget, and click the download icon. The data will be exported as CSV.

#### What happens if I don't save before closing?

If you have unsaved changes and try to leave the page or disable Build Mode, you'll be prompted to save or discard your changes.

### Next Steps

Now that you know how to create custom reports, explore:

- Using Report Filters: Learn advanced filtering techniques
- Report Widgets Guide: Deep dive into each widget type
- Widget Configuration: Detailed guides for configuring specific widgets