# Comparison Pages Template Usage Guide


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

## Overview

Two template files provide the structure for creating new comparison pages:
- `v2/pages/compare_template_details.php` - For pages with competitor Details section
- `v2/pages/compare_template_nodetails.php` - For pages without competitor Details section

This guide explains how to choose the right template and complete it with competitor-specific content.

## Template Selection

### When to Use `compare_template_details.php`

Use this template when the competitor has notable features, integrations, or special characteristics worth highlighting:

- Competitor has detailed features/integrations to showcase
- Competitor has special characteristics or differentiators
- You want to showcase competitor capabilities in detail
- **Example competitors**: Clockin (has integrations like DATEV, features like digital forms)

**Key Feature**: Contains an expandable "Details" section (lines ~938-1030+) with:
- "Dazu zählen" (Features list)
- "Schnittstellen" (Integrations list)  
- "Das macht [Competitor] besonders" (Special characteristics)

### When to Use `compare_template_nodetails.php`

Use this template when the competitor is well-known or doesn't need a detailed feature breakdown:

- Competitor is well-known and doesn't need feature breakdown
- Competitor details are less relevant to the comparison
- You want simpler, cleaner competitor column
- **Example competitors**: Personio (well-known HR software)

**Key Feature**: Contains an invisible placeholder div (lines ~920-923) that maintains height alignment with Ordio Details section but shows no competitor details.

## Quick Start

1. **Choose the appropriate template** based on criteria above

2. **Copy the selected template**:
   ```bash
   # For pages with Details section:
   cp v2/pages/compare_template_details.php v2/pages/compare_{competitor}.php
   
   # OR for pages without Details section:
   cp v2/pages/compare_template_nodetails.php v2/pages/compare_{competitor}.php
   ```

2. **Replace all placeholders**:
   - Use Find & Replace to replace `{COMPETITOR}`, `{competitor}`, `{competitor-slug}` throughout
   - Replace ratings: `{COMPETITOR_RATING}`, `{COMPETITOR_REVIEWS}`
   - Replace content: `{COMPETITOR_DESCRIPTION}`, `{COMPETITOR_CATEGORY}`, `{COMPETITOR_FOCUS}`
   - Replace image paths: Update preload link and image tags from `template_details-vergleich-logo-160w.webp` or `template_nodetails-vergleich-logo-160w.webp` to `{competitor}-vergleich-logo-160w.webp`
   - Replace pricing: `{COMPETITOR_PRICE_STARTING}`, `{COMPETITOR_PRICE_UNIT}`, `{COMPETITOR_PRICING_PLANS}`
   - Replace FAQ: `{COMPETITOR_FAQ_TITLE}`, `{COMPETITOR_FAQ_ITEMS}`, `{COMPETITOR_FAQ_SCHEMA_ITEMS}`
   - Replace schema: `{COMPETITOR_SCHEMA_NAME}`, `{COMPETITOR_SCHEMA_DESCRIPTION}`, `{COMPETITOR_SCHEMA_URL}`
   - See [Placeholder Reference](COMPARISON_PAGES_TEMPLATE_PLACEHOLDERS.md) for complete list

3. **If using Details template**, replace Details placeholders:
   - `{COMPETITOR_DETAILS_BUTTON}` → Button text (e.g., "Clockin Details")
   - `{COMPETITOR_FEATURES}` → Features list HTML ("Dazu zählen" section)
   - `{COMPETITOR_INTEGRATIONS}` → Integrations list HTML ("Schnittstellen" section)
   - `{COMPETITOR_SPECIAL}` → Special characteristics HTML ("Das macht [competitor] besonders" section)

4. **Replace FAQ placeholders** (minimum 5-7 items):
   - `{COMPETITOR_FAQ_TITLE}` → FAQ section title
   - `{COMPETITOR_FAQ_ITEMS}` → Complete FAQ HTML structure
   - `{COMPETITOR_FAQ_SCHEMA_ITEMS}` → FAQ schema JSON array
   - **Important**: FAQ items in HTML must match FAQPage schema items exactly

5. **Generate image variants**:
   ```bash
   node scripts/generate_responsive_logos.js
   ```

6. **Test locally**: `http://localhost:8003/v2/pages/compare_{competitor}.php`

## Placeholder System

Both templates use a standardized placeholder system with placeholders in the format `{PLACEHOLDER}`. This makes it easy to find and replace all competitor-specific content.

### Quick Reference

See [COMPARISON_PAGES_TEMPLATE_PLACEHOLDERS.md](COMPARISON_PAGES_TEMPLATE_PLACEHOLDERS.md) for complete placeholder reference with examples and usage notes.

### Placeholder Replacement Workflow

**Step 1: Basic Information (Use Find & Replace)**
1. `{COMPETITOR}` → Competitor display name (e.g., "Clockin", "Personio")
2. `{competitor}` → Lowercase slug (e.g., "clockin", "personio")
3. `{competitor-slug}` → URL slug (e.g., "clockin", "personio")

**Step 2: Ratings & Reviews**
- `{COMPETITOR_RATING}` → Rating value (e.g., "4.9", "4.3")
- `{COMPETITOR_REVIEWS}` → Review count (e.g., "329", "368")

**Step 3: Content**
- `{COMPETITOR_DESCRIPTION}` → Full product description paragraph
- `{COMPETITOR_CATEGORY}` → Category (e.g., "Zeiterfassung", "HR-Software")
- `{COMPETITOR_FOCUS}` → Focus/use case (e.g., "Schichtplanung, Zeiterfassung & Personalmanagement")

**Step 4: Images**
- `{COMPETITOR_LOGO_ALT}` → Logo alt text (e.g., "clockin", "Personio")
- `{COMPETITOR_LOGO_CLASS}` → CSS classes (e.g., "" or "brightness-0 invert")
- Update image paths: `{competitor}-vergleich-logo-160w.webp`

**Step 5: Pricing**
- `{COMPETITOR_PRICE_STARTING}` → Starting price (e.g., "3.19", "0.00")
- `{COMPETITOR_PRICE_UNIT}` → Price unit (e.g., "pro User pro Monat", "auf Anfrage")
- `{COMPETITOR_PRICING_PLANS}` → Complete pricing HTML structure

**Step 6: FAQ**
- `{COMPETITOR_FAQ_TITLE}` → FAQ section title
- `{COMPETITOR_FAQ_ITEMS}` → Complete FAQ HTML structure
- `{COMPETITOR_FAQ_SCHEMA_ITEMS}` → FAQ schema JSON array

**Step 7: Details (Details Template Only)**
- `{COMPETITOR_DETAILS_BUTTON}` → Button text (e.g., "Clockin Details")
- `{COMPETITOR_FEATURES}` → Features list HTML
- `{COMPETITOR_INTEGRATIONS}` → Integrations list HTML
- `{COMPETITOR_SPECIAL}` → Special characteristics HTML

**Step 8: Schema**
- `{COMPETITOR_SCHEMA_NAME}` → Schema name (may differ from display name)
- `{COMPETITOR_SCHEMA_DESCRIPTION}` → Schema description
- `{COMPETITOR_SCHEMA_URL}` → Schema URL slug

### Find & Replace Tips

1. **Use Find & Replace carefully**: Some placeholders appear multiple times
2. **Replace in order**: Start with basic info, then content, then complex sections
3. **Verify context**: Check each replacement to ensure it's correct
4. **Use TODO comments**: Templates include TODO comments indicating what needs replacement

### Common Mistakes to Avoid

- **Don't forget image paths**: Update both preload link AND actual image tags
- **Don't skip schema**: All schema placeholders must be replaced
- **Don't forget FAQ schema**: FAQ items in HTML must match FAQPage schema
- **Don't leave placeholders**: Use Find & Replace to catch all instances
- **Don't forget OMR link**: Update OMR Reviews URL to match competitor

### Placeholder Reference

For complete placeholder documentation, see:
- [COMPARISON_PAGES_TEMPLATE_PLACEHOLDERS.md](COMPARISON_PAGES_TEMPLATE_PLACEHOLDERS.md) - Complete reference with examples

## Sections to Copy from Existing Pages

### 1. Star Rating SVGs
**Location**: Lines ~697-700 in `compare_awork.php`

Copy the star rating SVG structure for both Ordio (4.9/5) and competitor columns. Update competitor rating as needed.

### 2. Star Rating Distribution
**Location**: Lines ~750-800 in `compare_awork.php`

Copy the rating distribution bars showing percentage breakdown (5-star, 4-star, etc.) for both columns.

### 3. Ratings Section
**Location**: Lines ~800-900 in `compare_awork.php`

Copy the detailed ratings section (Benutzerfreundlichkeit, Erfüllung der Anforderungen, etc.) with percentage bars.

### 4. Pricing Section
**Location**: Lines ~900-1100 in `compare_awork.php`

Copy the pricing cards structure. Update competitor pricing plans with actual data.

### 5. Competitor Details Section (Details Template Only)
**Location**: Lines ~938-1030+ in `compare_template_details.php`

The Details template includes an expandable section with competitor features, integrations, and special characteristics. Update:
- Features list ("Dazu zählen")
- Integrations list ("Schnittstellen")
- Special characteristics ("Das macht [Competitor] besonders")
- Button text (change "Clockin Details" to "{Competitor} Details")

**Note**: The No Details template uses an invisible placeholder instead (lines ~920-923) to maintain height alignment.

### 6. FAQ Items
**Location**: Lines ~2000-2300 in `compare_awork.php`

Copy FAQ structure and update questions/answers to be competitor-specific. Ensure all FAQ items are included in the FAQPage schema.

### 7. Hero Visual Elements
**Location**: Lines ~300-600 in `compare_awork.php`

The template includes placeholder for hero visual elements. Copy the visual elements section if needed, or create competitor-specific visuals.

## Schema Updates Required

After copying content, update the JSON-LD schema:

1. **WebPage schema**: Update `@id`, `url`, `name`, `description`
2. **Article schema**: Update `headline`, `description`, `datePublished`
3. **Table schema**: Update competitor Product information
4. **SoftwareApplication schema**: Update competitor details
5. **BreadcrumbList**: Update competitor name
6. **FAQPage**: Ensure all FAQ items are included

## Image Requirements

Before testing, ensure these images exist:

1. **Comparison logo**: `/v2/img/alternativen/{competitor}-vergleich-logo.webp`
   - Generate variants: 160w, 320w
   - **Important**: Update preload link in `<head>` from `template_details-vergleich-logo-160w.webp` or `template_nodetails-vergleich-logo-160w.webp` to `{competitor}-vergleich-logo-160w.webp`
   
2. **Regular logo**: `/v2/img/alternativen/{competitor}-logo.webp`
   - Generate variants: 64w, 80w, 128w, 160w

Run `node scripts/generate_responsive_logos.js` after adding source images.

## Validation Checklist

After completing the template:

- [ ] All placeholders replaced (use Find & Replace to verify)
- [ ] Basic info: `{COMPETITOR}`, `{competitor}`, `{competitor-slug}` replaced
- [ ] Ratings: `{COMPETITOR_RATING}`, `{COMPETITOR_REVIEWS}` replaced
- [ ] Content: `{COMPETITOR_DESCRIPTION}`, `{COMPETITOR_CATEGORY}`, `{COMPETITOR_FOCUS}` replaced
- [ ] Images: Paths updated, `{COMPETITOR_LOGO_ALT}`, `{COMPETITOR_LOGO_CLASS}` replaced
- [ ] Pricing: `{COMPETITOR_PRICE_STARTING}`, `{COMPETITOR_PRICE_UNIT}`, `{COMPETITOR_PRICING_PLANS}` replaced
- [ ] FAQ: `{COMPETITOR_FAQ_TITLE}`, `{COMPETITOR_FAQ_ITEMS}`, `{COMPETITOR_FAQ_SCHEMA_ITEMS}` replaced
- [ ] Schema: `{COMPETITOR_SCHEMA_NAME}`, `{COMPETITOR_SCHEMA_DESCRIPTION}`, `{COMPETITOR_SCHEMA_URL}` replaced
- [ ] Details (if Details template): `{COMPETITOR_DETAILS_BUTTON}`, `{COMPETITOR_FEATURES}`, `{COMPETITOR_INTEGRATIONS}`, `{COMPETITOR_SPECIAL}` replaced
- [ ] Images generated and paths correct
- [ ] Meta tags updated
- [ ] Canonical URL correct
- [ ] OMR Reviews URL updated
- [ ] Test locally at `http://localhost:8003/v2/pages/compare_{competitor}.php`
- [ ] Schema validates (Google Rich Results Test)
- [ ] No console errors
- [ ] Responsive design works (mobile, tablet, desktop)
- [ ] All TODO comments addressed

## Common Issues

### Missing Alpine.js Functionality
If expandable sections don't work, ensure Alpine.js is loaded via `head.php` and `x-data`, `x-show`, `@click` attributes are correct.

### Height Synchronization Issues
Ensure `@height-changed` event listeners are set up correctly in the comparison grid and expandable sections dispatch height events.

### Schema Validation Errors
Check JSON syntax, ensure all required fields present, verify URLs are absolute and correct.

## Structural Differences Between Templates

### Details Template (`compare_template_details.php`)

**Competitor Column Structure**:
1. Product Description
2. **Expandable Details Section** (lines ~938-1030+):
   - Button: "{Competitor} Details"
   - Alpine.js `x-data="{ open: false }"` for expand/collapse
   - Features list ("Dazu zählen")
   - Integrations list ("Schnittstellen")
   - Special characteristics ("Das macht [Competitor] besonders")
   - Dispatches height changes for column synchronization
3. Star Rating Distribution
4. Ratings Section
5. Pricing Section

### No Details Template (`compare_template_nodetails.php`)

**Competitor Column Structure**:
1. Product Description
2. **Invisible Placeholder** (lines ~920-923):
   ```html
   <div class="hidden lg:block mb-6 transition-all duration-300 ease-in-out" 
        :style="{ height: ordioDetailsHeight + 'px' }">
       <!-- Invisible space that expands/collapses with Ordio Details -->
   </div>
   ```
   - Maintains height alignment with Ordio Details section
   - No competitor details shown
3. Star Rating Distribution
4. Ratings Section
5. Pricing Section

## Reference Files

- **Templates**: 
  - `v2/pages/compare_template_details.php` - With Details section
  - `v2/pages/compare_template_nodetails.php` - Without Details section
- **Examples**: 
  - `v2/pages/compare_clockin.php` - Uses Details template pattern
  - `v2/pages/compare_personio.php` - Uses No Details template pattern
- **Components**: `v2/components/ordio_comparison_content.php`
- **Carousel**: `v2/base/compare_carousel.php`
- **CSS**: `v2/css/comparison-pages.css`
- **Data**: `v2/data/tools_data.php`, `v2/data/ordio_comparison_data.php`

## Next Steps

1. Complete the template following this guide
2. Test locally
3. Validate schema
4. Review content for accuracy
5. Deploy to production