# Comparison Pages Quick Start


**Last Updated:** 2025-11-20

## Create a New Comparison Page in 5 Minutes

### Prerequisites

- Competitor name and slug
- Basic competitor information (ratings, pricing, description)
- Logo images prepared

### Step 1: Copy Data Template (30 seconds)

```bash
cp v2/data/competitors/clockin_example.php v2/data/competitors/SLUG.php
```

### Step 2: Fill Essential Data (3 minutes)

Open `v2/data/competitors/SLUG.php` and update:

```php
<?php
require_once __DIR__ . '/../competitor_template_data.php';

$competitorData = [
    // === REQUIRED (Fill these first) ===
    'name' => 'CompetitorName',
    'slug' => 'competitorslug',
    'category' => 'Zeiterfassung',  // or HR-Software, etc.
    'focus' => 'What they focus on',
    'target' => 'Target audience',

    // Logo paths (update competitor slug in paths)
    'logo' => [
        'alt' => 'competitorname',
        'class' => '',  // or 'brightness-0 invert' if needed
        'paths' => [
            'vergleich_160w' => '/v2/img/alternativen/SLUG-vergleich-logo-160w.webp',
            'vergleich_320w' => '/v2/img/alternativen/SLUG-vergleich-logo-320w.webp',
        ]
    ],

    // Ratings (get from OMR/Capterra/etc.)
    'rating' => [
        'overall' => 4.5,
        'review_count' => 250,
        'distribution' => [
            '5' => ['count' => 150, 'percentage' => 60],
            '4' => ['count' => 75, 'percentage' => 30],
            '3' => ['count' => 20, 'percentage' => 8],
            '2' => ['count' => 5, 'percentage' => 2],
            '1' => ['count' => 0, 'percentage' => 0],
        ],
        'category_ratings' => [
            'benutzerfreundlichkeit' => ['score' => 9.0, 'category' => 'Zeiterfassung', 'average' => 9],
            'erfuellung' => ['score' => 8.8, 'category' => 'Zeiterfassung', 'average' => 9.1],
            'kundensupport' => ['score' => 9.2, 'category' => 'Zeiterfassung', 'average' => 9.1],
            'einrichtung' => ['score' => 8.5, 'category' => 'Zeiterfassung', 'average' => 8.8]
        ]
    ],

    // Description
    'description' => 'Paste competitor description here...',
    'description_heading' => '',  // Leave empty for default

    // Pricing
    'pricing' => [
        'starting_price' => '9.99',
        'currency' => 'EUR',
        'unit' => 'pro User pro Monat',
        'plans' => [
            ['name' => 'Basic', 'description' => 'Essential features', 'price' => '9.99', 'unit' => 'User / Monat'],
            ['name' => 'Pro', 'description' => 'Advanced features', 'price' => '19.99', 'unit' => 'User / Monat'],
        ]
    ],

    // Details section - Set to true/false
    'has_details' => true,  // Change to false for well-known competitors
    'details' => [
        'button_text' => 'CompetitorName Details',
        'features' => ['Feature 1', 'Feature 2'],
        'integrations' => ['Integration 1', 'Integration 2'],
        'special' => ['Special thing 1', 'Special thing 2']
    ],

    // FAQ - Placeholder
    'faq' => [
        'title' => '',  // Auto-generated
        'items' => [
            ['question' => 'Was kostet CompetitorName?', 'answer' => 'Answer...']
        ]
    ],

    // Schema
    'schema' => [
        'name' => 'CompetitorName',
        'description' => 'Schema description...'
    ]
];

$validation = validateCompetitorData($competitorData);
if (!$validation['valid']) {
    error_log('Data validation failed:');
    error_log(print_r($validation['errors'], true));
}

$competitorData = applyDefaultValues($competitorData);
return $competitorData;
?>
```

### Step 3: Generate Page (10 seconds)

**Option A: Use generator script**

```bash
php scripts/generate_comparison_page.php competitorslug
```

**Option B: Manual**

```bash
cp v2/pages/compare_template_unified.php v2/pages/compare_competitorslug.php
```

Then update line ~20 in the new file:

```php
$competitorData = require __DIR__ . '/../data/competitors/competitorslug.php';
```

### Step 4: Test (1 minute)

Visit: `http://localhost:8003/v2/pages/compare_competitorslug.php`

Check:

- ✓ Page loads
- ✓ Logo displays
- ✓ Ratings show correctly
- ✓ Pricing renders
- ✓ Details section works (if has_details = true)

### Step 5: Validate (30 seconds)

```bash
# Validate data
php scripts/validate_competitor_data.php v2/data/competitors/competitorslug.php

# Test schema
# Copy URL and test at: https://search.google.com/test/rich-results
```

## Common Examples

### Example 1: Competitor WITH Details

```php
'has_details' => true,
'details' => [
    'button_text' => 'Clockin Details',
    'features' => [
        'Digitale Checklisten & Formulare',
        'Notizen, Foto-Dokumentation',
        'Digitale Projektakten'
    ],
    'integrations' => [
        'DATEV Lohnimport',
        'Lexware Office',
        'sevdesk'
    ],
    'special' => [
        'Besonders einfache Bedienung',
        'Schnelle Einrichtung',
        'DATEV-Marktplatzpartner'
    ]
]
```

### Example 2: Competitor WITHOUT Details

```php
'has_details' => false,
'details' => [
    'button_text' => '',
    'features' => [],
    'integrations' => [],
    'special' => []
]
```

### Example 3: "On Request" Pricing

```php
'pricing' => [
    'starting_price' => '0.00',
    'currency' => 'EUR',
    'unit' => 'auf Anfrage',
    'plans' => [
        ['name' => 'Professional', 'description' => 'For growing teams', 'price' => 'Auf Anfrage', 'unit' => '']
    ]
]
```

### Example 4: Logo Needs Inversion

```php
'logo' => [
    'alt' => 'personio',
    'class' => 'brightness-0 invert',  // Inverts dark logo on gray background
    'paths' => [...]
]
```

## Quick Reference

### Required Fields Checklist

- [ ] `name` - Display name
- [ ] `slug` - URL slug (lowercase, no spaces)
- [ ] `category` - Product category
- [ ] `focus` - Focus/use case
- [ ] `target` - Target audience
- [ ] `logo.alt`, `logo.class`, `logo.paths`
- [ ] `rating.overall`, `rating.review_count`
- [ ] `rating.distribution` (5 levels)
- [ ] `rating.category_ratings` (4 ratings)
- [ ] `description`
- [ ] `pricing.starting_price`, `pricing.unit`, `pricing.plans`
- [ ] `has_details` (true/false)
- [ ] `details` (can be empty if has_details = false)
- [ ] `faq.items` (at least 1 item)
- [ ] `schema.name`, `schema.description`

### Common Mistakes

❌ **Forgot to update competitor slug in logo paths**

```php
'paths' => [
    'vergleich_160w' => '/v2/img/alternativen/clockin-vergleich-logo-160w.webp',  // Still says "clockin"!
]
```

✓ **Correct:**

```php
'paths' => [
    'vergleich_160w' => '/v2/img/alternativen/YOURSLUG-vergleich-logo-160w.webp',
]
```

❌ **Rating distribution doesn't sum correctly**

```php
'review_count' => 250,
'distribution' => [
    '5' => ['count' => 150, 'percentage' => 60],
    '4' => ['count' => 50, 'percentage' => 20],   // Total: 200, not 250!
]
```

✓ **Correct:**

```php
'review_count' => 250,
'distribution' => [
    '5' => ['count' => 150, 'percentage' => 60],
    '4' => ['count' => 75, 'percentage' => 30],
    '3' => ['count' => 20, 'percentage' => 8],
    '2' => ['count' => 5, 'percentage' => 2],
    '1' => ['count' => 0, 'percentage' => 0],
    // Total: 150 + 75 + 20 + 5 + 0 = 250 ✓
]
```

❌ **has_details = true but details are empty**

```php
'has_details' => true,
'details' => [
    'button_text' => '',  // This will cause validation error!
    'features' => [],
]
```

✓ **Correct:**

```php
'has_details' => true,
'details' => [
    'button_text' => 'CompetitorName Details',
    'features' => ['At least one feature'],
    'integrations' => ['At least one integration'],
    'special' => ['At least one special thing']
]
```

### Data Sources

**Where to get competitor data:**

- **Ratings**: OMR Reviews, Capterra, G2, Trustpilot
- **Pricing**: Competitor website, pricing page
- **Features**: Competitor website, product page
- **Description**: Competitor about page, marketing materials
- **Category ratings**: OMR Reviews (specific categories)

### File Naming

- Data file: `v2/data/competitors/{slug}.php`
- Page file: `v2/pages/compare_{slug}.php`
- Logo files: `v2/img/alternativen/{slug}-vergleich-logo-{size}w.webp`

Where `{slug}` is lowercase, no spaces, hyphens allowed.

## Troubleshooting

**Problem: Page shows "Invalid Competitor Data"**
→ Run validation script to see specific errors

**Problem: Logo not displaying**
→ Check image paths and verify files exist

**Problem: Details section not expanding**
→ Check browser console for JavaScript errors

**Problem: Rating percentages don't add up to 100%**
→ Recalculate percentages (sum should be 98-102%)

## Next Steps

After creating your first page:

1. Review full usage guide: `docs/guides/COMPARISON_PAGES_UNIFIED_TEMPLATE.md`
2. Read cursor rules: `.cursor/rules/comparison-pages-core.mdc`
3. Check examples: `v2/data/competitors/clockin_example.php`, `personio_example.php`
4. Test schema validation
5. Check performance metrics

## Resources

- **Full Guide**: `docs/guides/COMPARISON_PAGES_UNIFIED_TEMPLATE.md`
- **Implementation Details**: `docs/guides/UNIFIED_TEMPLATE_IMPLEMENTATION.md`
- **Data Template**: `v2/data/competitor_template_data.php`
- **Helper Functions**: `v2/helpers/comparison_template_helpers.php`
- **Examples**: `v2/data/competitors/clockin_example.php`