# comparison-pages-core Full Instructions ## Comparison Page Purpose Position Ordio against competitors (67 pages: Planday, Timetac, Papershift, etc.) with data-driven comparisons while maintaining consistent structure and performance. **Dark `section-3`:** Use `v2/sections/partials/compare-reporting-insights-lanxess.php` inside `
` (reporting insights + Lanxess)—homepage parity. Do not place `three-card-testimonials` in that slot (`verify-compare-pages-reporting-section.php`). **Current Design:** Card-based OMR-style comparison grid (newer pages: compare_awork.php, compare_askdante.php, compare_7shifts.php, compare_clockin.php, compare_clockify.php) **Legacy Design:** Table-based layout (older pages: compare_flairhr.php - being migrated) ## Template Files Two template files are used for creating new comparison pages: - **`compare_template_details.php`** - Use when competitor has detailed features/integrations to showcase (expandable Details section with features, integrations, special characteristics) - **`compare_template_nodetails.php`** - Use when competitor is well-known or doesn't need detailed feature breakdown (uses invisible placeholder for height alignment) **Template Selection Criteria:** - **Details template**: Competitor has notable features/integrations (e.g., Clockin with DATEV integrations, digital forms) - **No Details template**: Competitor is well-known or details less relevant (e.g., Personio - well-known HR software) **Key Difference:** - Details template: Expandable section (lines ~938-1030+) with competitor features/integrations - No Details template: Invisible placeholder div (lines ~920-923) for height alignment only ## Unique Requirements ### Hero Section **For new template (`compare_template_v2.php`):** The hero section uses a reusable component: ```php ``` **Component:** `v2/components/comparison/hero.php` **Required Variables:** - `$competitor` - Array with `name`, `category`, `focus` keys - `$generator` - `ComparisonPageGenerator` instance **Component Features:** - Auto-generates H1: `{Competitor} Alternativen: Vergleich & Bewertung 2026` - Includes competitor-specific description - Displays Ordio Schichtplanung illustration (SVG) - Includes CTA buttons - Responsive design - Fallback values for missing data **Hero Illustration:** - Path: `/v2/img/svg/comparison/hero-schichtplanung-card.svg` - Dimensions: 214x262px - Optimization: `fetchpriority="high"`, `loading="eager"` **For legacy templates (`compare_template_details.php`, `compare_template_nodetails.php`):** **Logo Image Requirements:** ```html {Competitor} ``` **Preload Tag (in ``):** ```html ``` **Critical:** Logo is typically the LCP (Largest Contentful Paint) element—preload it for performance. ### Headline Pattern ```html

{Competitor} Alternativen: Vergleich & Bewertung 2026

``` Include current year (check with `date +%Y` - currently 2026) and highlight key words with `.text-ordio-blue`. ### CTA Button Pattern (Hero Section) **CRITICAL:** Use proper wrapper div that doesn't conflict with CTA component's internal alignment. ```php

Vergleichst du Tools für Schichtplanung, Zeiterfassung oder Personalverwaltung? Dann bist du hier richtig. Wir zeigen dir, warum Ordio die bessere Alternative zu {Competitor} sein könnte – effizient, intuitiv und speziell für Schichtbetriebe.

``` **Key Points:** - ❌ **NEVER use:** `
` - conflicts with CTA component - ✅ **ALWAYS use:** `
` - provides mobile padding without conflicts - CTA component handles its own alignment via `justify-center mx-auto` when `ctaPositionLeft = 'false'` - Use `px-4 lg:px-0` for left-aligned CTAs in hero sections ### CTA Button Pattern (Centered - Testimonial Sections) For centered CTA buttons in testimonial sections (after "In bester Gesellschaft"): ```php

Wir haben Ordio mit mehr als 13 Jahren Erfahrung in der eigenen Gastronomie gegründet und gemeinsam mit Unternehmern anderer Branchen für jeden Betrieb mit flexiblen Schichten optimiert.

``` **Key Points:** - Paragraph padding: `px-4 sm:px-6` (not `px-6`) - CTA wrapper: `px-4 sm:px-6 lg:px-0` for centered buttons - `ctaPositionLeft = 'false'` triggers component's `justify-center mx-auto` alignment ### Modal Button Pattern (Comparison Table & "Ordio: Spezialisiert auf Schichtbetrieb" Section) **CRITICAL:** Always use Alpine.js store for modal buttons, never local `x-data` variables. **✅ CORRECT Pattern:** ```html ``` **❌ NEVER Use:** ```html ``` **Key Points:** - **Always use `$store.modal.open(title, button)`** - The modal system uses Alpine.js store defined in `v2/base/head.php` - The modal store provides `open()`, `close()`, and `toggleMobileNav()` methods - Always include `data-event-type` and `data-event-name` attributes for tracking - For "Kostenlos testen" buttons: `$store.modal.open('Jetzt kostenlos testen', 'Kostenlos und unverbindlich testen')` - For "Demo vereinbaren" buttons: `$store.modal.open('Unverbindliche Demo vereinbaren', 'Unverbindliche Demo vereinbaren')` ### Comparison Grid Structure (New Design) Use card-based grid layout (NOT table): ```php
``` **Key Features:** - Two side-by-side cards (Ordio | Competitor) - Height synchronization via Alpine.js - Expandable details sections - Star ratings with distribution charts - Pricing cards - CTA buttons in Ordio column **Legacy:** Older pages use `` with `comparison-table` class - migrate to new design. ### Competitor Positioning Copy See `.cursor/rules/shared-patterns.mdc` for universal copy guidelines (competitor language: neutral/factual, never praise). **Comparison-Specific Guidance:** - Position Ordio as the **smarter, more suitable choice** - Focus on Ordio's unique strengths relevant to the comparison - Example: "Während {Competitor} auf [X] fokussiert, bietet Ordio [Y + Z]" ### Required Includes **For new template (`compare_template_v2.php`):** ```php generateFAQ(); ?> ``` **For legacy templates (`compare_template_details.php`, `compare_template_nodetails.php`):** ```php ``` ### Shared CSS ```php ``` **⚠️ NEVER edit comparison-pages.css without explicit approval—it affects all 67 comparison pages.** ### Available CSS Classes From comparison-pages.css (use these, don't create inline styles): - `.rating-bar-container`, `.rating-bar-bg`, `.rating-bar-fill` – Rating bars - `.comparison-grid`, `.comparison-card` – Comparison grid layout - `.star-svg`, `.star-svg-empty` – Star icons - Touch target sizing auto-applied to main content links/buttons --- ## Image Assets Required Before creating a comparison page, generate responsive variants: **Source images:** - `{competitor}-vergleich-logo.webp` (320x64px recommended, ~5:1 aspect ratio) - `{competitor}-logo.webp` (160x160px square for carousel/cards) **Generate variants:** ```bash node scripts/generate_responsive_logos.js ``` This creates: - `{competitor}-vergleich-logo-160w.webp` (hero, mobile) - `{competitor}-vergleich-logo-320w.webp` (hero, desktop) - `{competitor}-logo-64w.webp` through `160w.webp` (carousel) **All images must be in:** `v2/img/alternativen/` --- ## Editing Workflow (Comparison-Specific) ### When Creating New Comparison Page 1. **Prepare images first** (see Image Assets above) 2. **Choose the appropriate template**: - **`compare_template_details.php`** - Use when competitor has detailed features/integrations to showcase (expandable Details section with features, integrations, special characteristics) - **`compare_template_nodetails.php`** - Use when competitor is well-known or doesn't need detailed feature breakdown (uses invisible placeholder for height alignment) 3. **Copy the selected template:** ```bash cp v2/pages/compare_template_details.php v2/pages/compare_{new_competitor}.php # OR cp v2/pages/compare_template_nodetails.php v2/pages/compare_{new_competitor}.php ``` 4. **Update meta tags** (title, description, keywords, canonical) 5. **Update image paths** (change `template_details-vergleich-logo-160w.webp` or `template_nodetails-vergleich-logo-160w.webp` to `{competitor}-vergleich-logo-160w.webp`) 6. **Update hero** (competitor name, logo image paths, description) 7. **Update competitor column**: - Product description - If using Details template: Update Details section (features, integrations, special characteristics, button text) - Star rating distribution - Ratings section - Pricing section 8. **Update schemas** (Table, Product for competitor, URLs) 9. **Update FAQ** (competitor-specific questions/answers) 10. **Test locally:** `http://localhost:8003/v2/pages/compare_{new_competitor}.php` 11. **Validate schema:** Google Rich Results Test 12. **Check performance:** PageSpeed Insights (target LCP < 2.5s) ### When Updating Existing Comparison Page **For single-page updates:** - Use targeted edits for specific sections (hero, table row, FAQ item) - Preserve logo preload tag and image attributes (width, height, srcset) - Maintain comparison table structure **For multi-page updates (affecting 5+ comparison pages):** - Use Multi-Edit or scripted approach across files - Example: "Update pricing in all comparison pages from €89 to €99" (if pricing changes) - Test on 3-5 sample pages before applying to all 67 pages ### Preserving Critical Elements **NEVER remove or modify without explicit request:** - Logo preload tag (performance critical) - Image srcset and sizes attributes (responsive images) - Width/height attributes on images (prevent CLS) - Comparison carousel include (navigation to other alternatives) - comparison-pages.css link (shared styling) --- ## Common Comparison Page Patterns ### Neutral Competitor Intro "[Competitor] ist eine [Category]-Software für [Primary Use Case]. Viele Unternehmen suchen nach [Competitor] Alternativen, die [Additional Need X] und [Additional Need Y] bieten." ### Ordio Differentiation "Ordio bietet [Unique Value Prop] und richtet sich speziell an [Target Audience]. Mit [Feature X], [Feature Y] und [Feature Z] löst du [Problem] effizienter." ### Feature Comparison "Während [Competitor] [X] bietet, geht Ordio weiter: [Y + Z]. Das bedeutet für dich: [Benefit]." ### FAQ Answers - Start with direct answer to the question - Mention competitor neutrally (e.g., "Ja, [Competitor] bietet [X]") - Transition to Ordio's approach (e.g., "Ordio hingegen fokussiert auf [Y], weil [Reason]") - End with benefit (e.g., "So kannst du [Outcome] ohne [Pain Point]") --- ## Unified Template System (NEW - 2025) **RECOMMENDED APPROACH**: Use the unified template system for all new comparison pages. ### Overview The unified template system consolidates the two legacy templates (`compare_template_details.php` and `compare_template_nodetails.php`) into a single data-driven approach. **Key Benefits:** - Single template to maintain - Data-driven (changes to data don't require template edits) - Built-in validation - Consistent output across all pages - Faster page creation (5 minutes vs. 30+ minutes) ### Core Files **Data Structure:** - `v2/data/competitor_template_data.php` - Template structure and validation functions - `v2/data/competitors/{slug}.php` - Individual competitor data files **Helper Functions:** - `v2/helpers/comparison_template_helpers.php` - Rendering functions **Template:** - `v2/pages/compare_template_unified.php` - Unified template (documented in implementation guide) **Scripts:** - `scripts/generate_comparison_page.php` - Generate page from data - `scripts/validate_competitor_data.php` - Validate competitor data - `scripts/data/extract_to_unified_format.php` - Extract data from existing pages **Documentation:** - `docs/guides/comparison-pages/COMPARISON_PAGES_UNIFIED_TEMPLATE.md` - Full usage guide - `docs/guides/comparison-pages/COMPARISON_PAGES_QUICK_START.md` - 5-minute quick start - `docs/guides/UNIFIED_TEMPLATE_IMPLEMENTATION.md` - Technical implementation details - `docs/guides/comparison-pages/COMPARISON_PAGES_TEMPLATE_ANALYSIS.md` - Analysis of existing templates ### Creating a New Page (Quick Reference) **Step 1: Create Data File** ```bash cp v2/data/competitors/clockin_example.php v2/data/competitors/SLUG.php ``` Fill in all required fields (see data structure reference in usage guide). **Step 2: Validate Data** ```bash php scripts/validate_competitor_data.php v2/data/competitors/SLUG.php ``` **Step 3: Generate Page** ```bash php scripts/generate_comparison_page.php SLUG ``` **Step 4: Test** Visit: `http://localhost:8003/v2/pages/compare_SLUG.php` ### Data Structure (Essential Fields) **Basic Info:** - `name`, `slug`, `category`, `focus`, `target` **Logo:** - `logo.alt`, `logo.class`, `logo.paths.vergleich_160w`, `logo.paths.vergleich_320w` **Ratings:** - `rating.overall`, `rating.review_count` - `rating.distribution` (5 levels: 5★, 4★, 3★, 2★, 1★) - `rating.category_ratings` (4 ratings: benutzerfreundlichkeit, erfuellung, kundensupport, einrichtung) **Content:** - `description`, `description_heading` (optional) **Pricing:** - `pricing.starting_price`, `pricing.currency`, `pricing.unit` - `pricing.plans` (array of plans) **Details Section:** - `has_details` (true/false) - Controls conditional rendering - `details.button_text`, `details.features`, `details.integrations`, `details.special` **FAQ:** - `faq.title` (optional, auto-generated if empty) - `faq.items` (array of question/answer pairs) **Schema:** - `schema.name`, `schema.description` ### Conditional Details Section The unified template uses `has_details` flag for conditional rendering: **If `has_details = true`:** - Renders expandable Details section with features, integrations, special characteristics - Use for competitors with notable features to showcase **If `has_details = false`:** - Renders invisible placeholder div for height alignment - Use for well-known competitors or when details are less relevant ### Helper Functions Reference **Rendering Functions:** - `renderStarRating($rating, $size)` - Star icons with partial fill - `renderRatingDistribution($competitorData)` - Rating bars - `renderCategoryRatings($competitorData)` - Category rating circles - `renderPricingPlans($competitorData)` - Pricing cards - `renderDetailsSection($competitorData)` - Conditional Details section - `renderFAQItems($competitorData)` - FAQ items **Meta/Schema Functions:** - `generateMetaTags($competitorData)` - Meta tags - `generateOGTags($competitorData)` - Open Graph tags - `generateSchema($competitorData, $publishedDate)` - JSON-LD schema **Utility Functions:** - `validateCompetitorData($data)` - Validate data structure - `applyDefaultValues($data)` - Apply default values - `calculatePartialStarFill($rating)` - Calculate star fill percentage - `calculateCircularProgress($score)` - Calculate circular progress dasharray - `formatPrice($price, $currency)` - Format price with symbol - `sanitizeOutput($text)` - Sanitize HTML output ### Validation Checklist (Unified Template) **Data Validation:** - [ ] Data file validated with `scripts/validate_competitor_data.php` - [ ] All required fields present - [ ] Rating distribution sums correctly (count and percentage) - [ ] Logo paths correct - [ ] Pricing plans complete **Page Generation:** - [ ] Page generated without errors - [ ] Data file path correct in generated page - [ ] All sections render correctly **Content Quality:** - [ ] Competitor description clear and accurate - [ ] Ratings match source data - [ ] Pricing current and complete - [ ] FAQ provides value (to be optimized based on SEO reports) - [ ] Schema name/description accurate **Technical:** - [ ] Schema validates with Google Rich Results Test - [ ] Logo preloaded for LCP optimization - [ ] No console errors - [ ] Responsive design works - [ ] Alpine.js interactions functional (if has_details = true) ### Migration Strategy **For New Pages:** Use unified template exclusively **For Existing Pages:** Migrate gradually 1. Phase 1: Test with 2-3 pages 2. Phase 2: Migrate 5 more pages 3. Phase 3: Bulk migrate remaining pages **Migration Process:** 1. Extract data using `scripts/data/extract_to_unified_format.php` 2. Create data file 3. Validate data 4. Generate new page 5. Compare old vs. new output 6. Deploy when verified ### Legacy Templates (Deprecated) The following templates are deprecated but maintained for compatibility: - `compare_template_details_legacy.php` (formerly `compare_template_details.php`) - `compare_template_nodetails_legacy.php` (formerly `compare_template_nodetails.php`) **Do not use for new pages.** Existing pages using these templates will continue to work. ### Key Differences from Legacy Templates **Legacy Approach:** - Two separate templates - Hardcoded placeholders (`{COMPETITOR}`, `{competitor-slug}`, etc.) - Manual find/replace for each new page - ~40+ placeholders to replace - Prone to human error **Unified Approach:** - Single template - Data-driven (PHP arrays) - Automated page generation - Built-in validation - Helper functions for consistency - Conditional rendering for Details section ### Common Patterns **Competitor WITH Details:** ```php 'has_details' => true, 'details' => [ 'button_text' => 'Clockin Details', 'features' => ['Feature 1', 'Feature 2'], 'integrations' => ['DATEV Lohnimport', 'Lexware Office'], 'special' => ['Einfache Bedienung', 'Schnelle Einrichtung'] ] ``` **Competitor WITHOUT Details:** ```php 'has_details' => false, 'details' => [ 'button_text' => '', 'features' => [], 'integrations' => [], 'special' => [] ] ``` **On-Request Pricing:** ```php 'pricing' => [ 'starting_price' => '0.00', 'unit' => 'auf Anfrage', 'plans' => [ ['name' => 'Professional', 'description' => 'For teams', 'price' => 'Auf Anfrage', 'unit' => ''] ] ] ``` ### Troubleshooting **Error: "Invalid Competitor Data"** → Run `php scripts/validate_competitor_data.php` to see specific errors **Page not displaying correctly** → Check that data file path is correct in page file (line ~20) **Details section not expanding** → Verify Alpine.js is loaded and check browser console **Schema validation fails** → Check schema name/description match competitor data exactly ### Resources - **Quick Start:** `docs/guides/comparison-pages/COMPARISON_PAGES_QUICK_START.md` (5-minute guide) - **Full Guide:** `docs/guides/comparison-pages/COMPARISON_PAGES_UNIFIED_TEMPLATE.md` (comprehensive) - **Implementation:** `docs/guides/UNIFIED_TEMPLATE_IMPLEMENTATION.md` (technical details) - **Examples:** `v2/data/competitors/clockin_example.php`, `personio_example.php` --- ## Edge Cases & Gotchas ## Related Documentation See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping. **Key Documentation:** - [docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md](../../docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md) - `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md` - Step-by-step creation guide - [docs/guides/comparison-pages/COMPARISON_PAGES_STRUCTURE.md](../../docs/guides/comparison-pages/COMPARISON_PAGES_STRUCTURE.md) - `docs/guides/comparison-pages/COMPARISON_PAGES_STRUCTURE.md` - Page structure documentation - [docs/guides/comparison-pages/COMPARISON_PAGES_TEMPLATE_ANALYSIS.md](../../docs/guides/comparison-pages/COMPARISON_PAGES_TEMPLATE_ANALYSIS.md) - `docs/guides/comparison-pages/COMPARISON_PAGES_TEMPLATE_ANALYSIS.md` - Template analysis - [docs/content/pages/comparison-pages/COMPARISON_PAGES_INVENTORY.md](../../docs/content/pages/comparison-pages/COMPARISON_PAGES_INVENTORY.md) - `docs/content/pages/comparison-pages/COMPARISON_PAGES_INVENTORY.md` - Complete page list - [docs/content/pages/comparison-pages/SEO_ONLY_COMPARISON_PAGES.md](../../docs/content/pages/comparison-pages/SEO_ONLY_COMPARISON_PAGES.md) - `docs/content/pages/comparison-pages/SEO_ONLY_COMPARISON_PAGES.md` - SEO-only pages - [docs/content/competitors/COMPETITORS_VS_COMPARISON_PAGES.md](../../docs/content/competitors/COMPETITORS_VS_COMPARISON_PAGES.md) - `docs/content/competitors/COMPETITORS_VS_COMPARISON_PAGES.md` - Critical distinction guide - [docs/content/competitors/COMPETITORS_INVENTORY.md](../../docs/content/competitors/COMPETITORS_INVENTORY.md) - `docs/content/competitors/COMPETITORS_INVENTORY.md` - Competitor data