## Understanding the Report Manager

The Alpha Report Manager is your central hub for managing all custom and pre-built reports in Alpha Insights. It provides a visual interface where you can view, organize, create, edit, and share reports with ease.

### What is the Report Manager?

The Report Manager is a dedicated page that displays all your reports as interactive cards. Think of it as a dashboard for your dashboards - a place where you can:

- See all your installed reports at a glance
- Create new custom reports from scratch
- Install pre-built default reports
- Edit report settings and configurations
- Duplicate existing reports as templates
- Export reports for backup or sharing
- Import reports from JSON files
- Manage live share links
- Organize reports by category

### Accessing the Report Manager

There are two ways to access the Report Manager:

#### Method 1: From the Main Reports Page

1. Go to Alpha Insights → Reports in your WordPress admin
2. If no specific report is selected, you'll see the Report Manager automatically

#### Method 2: From Any Report

1. When viewing any report, look for the breadcrumb navigation at the top
2. Click on Reports or Alpha Insights to return to the Report Manager

Note: The Report Manager appears when there's no `subpage` parameter in the URL, making it your reports home page.

### Report Manager Interface Overview

The Report Manager interface consists of several key sections that help you manage your reports efficiently:

#### 1. Header Section

At the very top, you'll see the Alpha Insights branding and report summary:

- Alpha Insights Logo - Visual branding
- Title: "Alpha Report Manager"
- Report Count: Shows how many reports are installed and how many default reports are available (e.g., "12 installed • 8 default reports")

#### 2. Action Buttons (Top Right)

Three primary action buttons are always visible in the top-right corner:

- Import Report: Upload and install reports from JSON files
- Install Default Reports: Batch install all pre-built reports
- Create Report: Start building a new custom report from scratch

#### 3. Category Tabs

Below the header, you'll find four tabs to filter and organize your reports:

- All Reports: Shows every report - both installed and uninstalled defaults
- Sales Reports: Filters to show only revenue, orders, products, and customer-related reports
- Website Traffic: Shows only analytics, sessions, acquisitions, and traffic reports
- Not Installed: Displays only default reports that haven't been installed yet

Each tab shows a count badge indicating how many reports it contains (e.g., "Sales Reports (15)").

#### 4. Report Grid

The main area displays your reports as cards in a responsive grid layout. Each card represents one report and shows key information at a glance.

### Understanding Report Cards

Each report is displayed as an information-rich card. The appearance differs slightly between installed reports and uninstalled default reports.

#### Installed Report Cards

When a report is installed and ready to use, its card displays:

- Color-Coded Icon: A large circular icon with the report's custom color theme (top center)
- Report Name: The display name you've chosen
- Required Badge: If applicable, shows a checkmark badge labeled "Required" for mandatory reports
- Category Label: Shows whether it's a "Sales Reports" or "Website Traffic" report
- Menu Order: Displays the position in the navigation menu (e.g., "Menu Order: 5")
- Menu Visibility: Shows "Not Visible In Menu" if the report is hidden from WordPress admin navigation
- Live Share Links: If live share links exist, shows "Live Share Links (2)" with a link icon
- Action Buttons: Four icon buttons at the bottom for Settings, Duplicate, Download, and Delete

#### Uninstalled Report Cards

Default reports that haven't been installed yet show a simplified card:

- Icon: The report's default icon with its color theme
- Report Name: The pre-configured name
- Category Label: Shows the report category
- "Not Currently Installed" Status: Clear indicator that this is an available template
- Install Button: Large "Install Report" button to add it to your system

### Report Card Action Buttons

Each installed report card has four action buttons at the bottom. Here's what each one does:

#### Settings Button (Gear Icon)

Purpose: Opens the Report Settings modal where you can configure the report's metadata, design, and advanced options.

What you can edit:

- Report name and slug (identifier)
- Category assignment (Sales Reports or Website Traffic)
- Menu visibility and order
- Icon and color theme
- Version number
- Advanced JSON configuration
- View performance metrics

See "Editing Report Settings" below for detailed instructions.

#### Duplicate Button (Copy Icon)

Purpose: Creates a complete copy of the report including all widgets, filters, and configurations.

What happens:

- Opens the Report Settings modal in "duplicate mode"
- Pre-fills all settings from the original report
- Adds " (Copy)" to the report name
- Adds "-copy" to the slug
- Requires you to modify the slug to avoid conflicts
- Creates a new, independent report

See "Duplicating Reports" section for use cases and instructions.

#### Download Button (Download Icon)

Purpose: Exports the entire report configuration as a JSON file.

What you get:

- A file named `dashboard-config-[slug].json`
- Contains all report settings, widgets, filters, and layout
- Can be imported on any Alpha Insights installation
- Perfect for backups or sharing with others

See "Exporting and Importing Reports" for more details.

#### Delete Button (Trash Icon)

Purpose: Permanently removes the report from your system.

Important notes:

- Shows a confirmation dialog before deletion
- Cannot be undone - the report and all its widgets are permanently deleted
- Disabled for Required Reports (these cannot be deleted, only hidden)
- If you hover over a disabled delete button, you'll see a tooltip explaining why

Tip: If you're unsure about deleting a report, duplicate it first as a backup, or export it as JSON.

### Report Categories Explained

Alpha Insights organizes reports into two main categories. Understanding these helps you keep your reports organized and makes them easier to find.

#### Sales Reports

Category: `sales_reports`

Menu Location: Appears under Alpha Insights → Sales Reports in WordPress admin

Typical Reports Include:

- Revenue and profit dashboards
- Order analytics
- Product performance
- Customer analysis
- Financial statements
- Expense tracking
- Advertising campaign reports (Facebook Ads, Google Ads)
- Subscription analytics
- Coupon usage reports
- Tax reports

#### Website Traffic

Category: `website_traffic`

Menu Location: Appears under Alpha Insights → Website Traffic in WordPress admin

Typical Reports Include:

- Website analytics overview
- Session analytics
- Traffic acquisition sources
- Campaign performance (UTM tracking)
- E-commerce activity (page views, add-to-cart events)
- Form submissions
- Real-time visitor data

Why This Matters: When you create or edit a report, choosing the right category ensures it appears in the correct section of your WordPress admin menu, making it easier for you and your team to find the right report quickly.

### Required Reports

Alpha Insights includes five "Required" reports that are essential to the plugin's functionality. These reports have special status:

#### The Five Required Reports

1. Orders: Core order analytics dashboard
2. Facebook: Facebook Ads integration report
3. Google Ads: Google Ads integration report
4. Expenses: Business expense tracking
5. Profit & Loss Statement: Financial P&L reporting

#### What Makes Them Special?

- Cannot Be Deleted: The delete button is disabled with an explanation tooltip
- Auto-Installation: If you try to access one that's not installed, Alpha Insights will automatically install it
- Visual Indicator: Each card shows a "Required" badge with a checkmark icon
- Protection: Prevents accidental removal of essential reports

#### What If I Don't Want to See a Required Report?

You can't delete required reports, but you can hide them from the WordPress admin menu:

1. Click the Settings button on the required report
2. Go to the Data tab
3. Toggle off "Appear In Menu"
4. Click Update Report

The report will still exist and be accessible from the Report Manager, but won't clutter your navigation menu.

### Live Share Links Indicator

If a report has active live share links, you'll see a special section on its card:

What It Shows:

- A link icon with blue accent color
- Text: "Live Share Links (X)" where X is the count of active links

What You Can Do:

- Click the Live Share Links section to open the management modal
- View all active share links for that report
- Create new share links
- Copy link URLs to clipboard
- Delete expired or unused links

For complete details on creating and managing live share links, see the "Live Share Links" documentation.

### Understanding Menu Order

The menu order number controls where a report appears in your WordPress admin navigation. This number is displayed on each report card as "Menu Order: X".

#### How Menu Order Works

- Lower numbers appear first: Menu Order: 0 will be at the top
- Higher numbers appear later: Menu Order: 100 will be near the bottom
- Same numbers are sorted alphabetically: If two reports have Menu Order: 5, they're sorted by name
- Applies within categories: Sales Reports and Website Traffic have separate ordering

#### Best Practices for Menu Order

- Use increments of 10: (0, 10, 20, 30) This makes it easy to insert new reports later
- Reserve 0-10 for most important reports: Your primary dashboard should be Menu Order: 0
- Group related reports: Use similar numbers for related reports (e.g., all product reports in 20-29 range)
- Leave gaps: Don't use consecutive numbers - leave room for future additions

#### Example Organization

Sales Reports Menu:

- 0 - Store Overview Dashboard (most important)
- 10 - Orders Report
- 20 - Products Report
- 30 - Customers Report
- 40 - Profit & Loss Statement
- 50 - Expenses Report
- 60 - Facebook Ads Report
- 70 - Google Ads Report

### Menu Visibility Status

Reports can be visible or hidden from the WordPress admin menu while still being accessible from the Report Manager.

#### Visible in Menu

Status: No special indicator on the card

Behavior:

- Report appears in WordPress admin navigation under its category
- Positioned according to menu order
- Easily accessible to all admin users

#### Hidden from Menu

Status: Card shows "Not Visible In Menu" in gray text

Behavior:

- Report does not appear in WordPress admin navigation
- Still accessible from Report Manager
- Can still be accessed via direct URL
- Perfect for draft reports or rarely-used reports

#### Why Hide Reports?

- Reduce Menu Clutter: Hide rarely-used reports to keep navigation clean
- Draft Reports: Work on reports before making them visible to your team
- Seasonal Reports: Hide off-season reports (e.g., hide Black Friday report in summer)
- Required Reports You Don't Use: Hide required reports if you don't need them but can't delete them
- Experimental Reports: Test new report designs without exposing them to users

### Report Card Colors and Icons

Each report has a customizable color theme and icon that appears on its card and in the WordPress menu.

#### Available Color Themes

Alpha Insights provides 16 color themes:

- Primary Colors: Blue (default), Indigo, Purple, Pink
- Success Colors: Green, Teal, Lime
- Warm Colors: Yellow, Orange, Amber
- Alert Colors: Red, Deep Orange
- Neutral Colors: Gray, Slate, Stone, Zinc

The color is applied to:

- The circular icon background on the report card
- The menu icon in WordPress admin (if visible)
- Visual accents throughout the report (when applicable)

#### Available Icons

Choose from 60+ Material Design icons including:

- Commerce: shopping_cart, receipt, credit_card, local_shipping
- Analytics: trending_up, trending_down, analytics, bar_chart, pie_chart
- Finance: attach_money, account_balance, savings, payment
- Marketing: campaign, ads_click, public, language
- Reports: dashboard, assessment, description, insert_chart
- And many more...

Tip: Choose icons that visually represent the report's purpose. For example, use "trending_up" for performance reports, "shopping_cart" for order reports, and "people" for customer reports.

### Filtering Reports by Tab

The tab navigation at the top of the Report Manager makes it easy to find specific reports.

#### All Reports Tab

Shows: Every report in your system - both installed and uninstalled defaults

Count: Total of all reports available (installed + uninstalled)

Use When:

- Getting an overview of everything available
- Searching for a specific report across all categories
- Comparing installed vs uninstalled reports

#### Sales Reports Tab

Shows: Only reports with category "Sales Reports"

Count: Number of sales-related reports

Includes:

- Installed sales reports
- Uninstalled default sales reports

Use When:

- Managing e-commerce reports
- Finding revenue, order, or product reports
- Installing sales-related default reports

#### Website Traffic Tab

Shows: Only reports with category "Website Traffic"

Count: Number of traffic/analytics reports

Includes:

- Installed traffic reports
- Uninstalled default traffic reports

Use When:

- Managing analytics reports
- Finding visitor, session, or acquisition reports
- Installing traffic-related default reports

#### Not Installed Tab

Shows: Only default reports that haven't been installed yet

Count: Number of available default reports

Use When:

- Browsing available pre-built reports
- Installing default reports one at a time
- Discovering new report templates
- Checking which defaults you haven't added yet

Note: The count will decrease as you install more default reports, until it reaches 0 when all defaults are installed.

### Empty State: No Reports

If you have no reports installed (unlikely, as Alpha Insights auto-installs required reports), you'll see a friendly empty state:

What It Shows:

- Icon: Large report icon
- Title: "No Reports Found"
- Message: Explains that no reports are configured yet
- Two Action Buttons:
  - Create Report - Start building from scratch
  - Install Default Reports - Add pre-built reports

### Visual Design Elements

The Report Manager uses several visual design elements to create a modern, professional interface:

#### Card Styling

- White background with subtle shadow
- Rounded corners for a modern look
- Hover effects: Cards slightly elevate when you hover over them
- Color gradients: Icon backgrounds use gradient effects matching the report's color

#### Interactive Elements

- Buttons: Modern flat design with hover states
- Icons: Material Design icons throughout
- Tabs: Active tab shows accent color and underline
- Badges: Rounded badges for counts and status indicators

#### Color Coding

- Primary Blue: Create Report button and main actions
- Secondary Gray: Install and Import buttons
- Report Colors: Each report uses its custom theme color
- Status Indicators: Gray for "Not Visible," Green for "Required"

### Loading States

When the Report Manager is loading, you'll see skeleton screens that indicate content is being fetched:

#### What You See While Loading

- Skeleton Header: Animated placeholders for logo and title
- Skeleton Tabs: Gray animated tabs
- Skeleton Cards: 6 placeholder cards with animated shimmer effect
- Loading Overlay: "Loading Reports" message with animation

#### Loading Time

- First Load: 1-2 seconds typically
- Subsequent Loads: Nearly instant (data is cached)
- Slow Loads: If loading takes longer than 5 seconds, check your internet connection or server performance

### Error States

If something goes wrong while loading reports, you'll see an error screen:

#### Error Display

- Error Icon: Red warning icon
- Title: "Unable to Load Reports"
- Error Message: Specific description of what went wrong
- Retry Button: Click to reload the page and try again

#### Common Error Causes

- Internet Connection: Lost connection to server
- Server Timeout: WordPress server not responding
- Database Error: Cannot access report data
- Permission Error: User lacks required permissions

#### How to Resolve

1. Click the Retry button
2. If that doesn't work, refresh your browser
3. Check your internet connection
4. Contact your site administrator if the problem persists

### Next Steps

Now that you understand the Report Manager interface, learn how to:

- Create New Reports: Build custom reports from scratch
- Edit Report Settings: Configure report metadata, design, and advanced options
- Duplicate Reports: Use existing reports as templates
- Export and Import: Back up and share reports as JSON
- Install Default Reports: Add pre-built report templates
- Manage Live Share Links: Create shareable report links

Each of these topics has its own detailed documentation guide.