# Template CTA Section Implementation Guide

**Last Updated:** 2026-02-15

## Overview

The Template CTA Section is a conversion-optimized call-to-action component that appears on all template pages. It connects template use cases to Ordio product features with highly tailored messaging per template.

## Quick Start

### For Template Developers

The CTA section is **automatically included** on all template pages. No code changes needed unless you want to customize messaging.

### Customizing CTA Content

1. **Open** `v2/data/template-cta-messages.json`
2. **Add/Edit** template-specific override in `template_overrides` section
3. **Save** - Changes take effect immediately

Example:

```json
{
  "template_overrides": {
    "your-template-id": {
      "headline": "Your custom headline",
      "subheadline": "Your custom subheadline",
      "benefits": [
        {
          "icon": "clock",
          "title": "Benefit title",
          "description": "Benefit description"
        }
      ],
      "features": [
        {
          "name": "Feature Name",
          "url": "/feature-url",
          "benefit": "What user gains"
        }
      ]
    }
  }
}
```

## Layout Structure

### Desktop Layout

The CTA section uses a **single-column flow** with three main sections:

1. **Benefits Grid (2x2)**: Four benefit cards displayed in a 2x2 grid, centered with `max-w-4xl`
2. **"Mit Ordio" Feature Cards**: 2-4 feature cards displayed in a responsive grid (2-4 columns on desktop, 2 on tablet, 1 on mobile)
3. **CTA Buttons**: Centered CTA buttons with optimized sizing (`max-w-md`)

### Mobile Layout

On mobile devices, the same content appears in a **stacked single-column** layout:

1. **Benefits**: Stacked vertically (single column)
2. **"Mit Ordio"**: Stacked feature cards (single column)
3. **CTA Buttons**: Full-width buttons at the end

### Responsive CTA Text

The CTA section displays different text on mobile vs desktop:

- **Desktop**: "Jetzt kostenlos testen" with full subtext
- **Mobile**: "Kostenlos starten" with shorter, punchier subtext

## Architecture

### File Structure

```
v2/
├── components/
│   └── template-cta.php              # Main CTA component
├── config/
│   └── template-cta-config.php        # Configuration loader
├── data/
│   └── template-cta-messages.json      # Template-specific messages
└── css/
    └── templates-pages.css            # CTA styles (appended)
```

### Data Flow

```
templates_template.php
  ↓
load_template_cta_config($templateId)
  ↓
template-cta-config.php
  ↓
template-cta-messages.json
  ↓
template-cta.php (renders)
```

## Configuration System

### Priority Order

1. **Template-specific override** (`template_overrides[templateId]`)
2. **Category-based default** (`category_defaults[category]`)
3. **Generic "other" category** (`category_defaults["other"]`)
4. **Hardcoded default** (if JSON fails)

### Category Mapping

Templates inherit category defaults based on their `category` field in `template-registry.json`:

- `shift_planning` → Schichtplanung features
- `time_tracking` → Zeiterfassung features
- `payroll` → Lohnabrechnung features
- `employee_management` → Personalakte/Verfügbarkeiten features
- `compliance` → Compliance/ArbZG features
- `vacation_leave` → Urlaubsplanung features
- `termination` → Kündigung features
- `training` → Schulung features
- `recruitment` → Recruiting features
- `other` → Generic fallback

### Template-to-Product Mapping

When adding features to a template CTA, use the mapping below. Always use canonical URLs (see `docs/development/CANONICAL_URLS_AND_LINKING.md`).

| Template Category | Recommended Product Pages | Rationale |
|------------------|---------------------------|-----------|
| shift_planning | Schichtplan, Zeiterfassung, Mitarbeiter-App, Nano AI | KI benefit → Nano AI; Mobile App benefit → Mitarbeiter-App |
| time_tracking | Zeiterfassung, Payroll, Schichtplan, Mitarbeiter-App | "Mobile Stempeluhr" benefit → Mitarbeiter-App |
| vacation_leave | Verfügbarkeiten, Schichtplan, Digitale Personalakte, Mitarbeiter-App | "Übersicht für alle" benefit → Mitarbeiter-App |
| payroll | Payroll, Zeiterfassung | No change |
| other | Generic fallback | No change |

**When to include Mitarbeiter-App:** Template mentions mobile app, employee self-service, plans in real-time, availability, or stamping.

**When to include Nano AI:** Template mentions KI, AI, automation, or intelligent planning.

**Canonical URLs for product pages:** `/mitarbeiter-app`, `/nano-ai` – use as-is (do not use redirect paths like `/mobile-app`).

## JSON Schema

### Root Structure

```json
{
  "version": "1.0.0",
  "last_updated": "YYYY-MM-DD",
  "category_defaults": {
    "category_name": { ... }
  },
  "template_overrides": {
    "template-id": { ... }
  }
}
```

### CTA Configuration Object

```json
{
  "headline": "string (required)",
  "subheadline": "string (required)",
  "benefits": [
    {
      "icon": "string (required - see icon list)",
      "title": "string (required)",
      "description": "string (required)"
    }
  ],
  "features": [
    {
      "name": "string (required)",
      "url": "string (required - relative URL)",
      "benefit": "string (required)"
    }
  ]
}
```

### Required Fields

- `headline`: Main headline (h2)
- `subheadline`: Supporting text below headline
- `benefits`: Array of 3-4 benefit objects
- `features`: Array of 2-4 feature objects

### Optional Fields

- None - all fields are required for a complete CTA

### Icon Names

Available icons (use exact name):

- `clock` - Time/clock
- `shield-check` - Security/compliance
- `chart-line` - Analytics/optimization
- `mobile` - Mobile app
- `sync` - Integration/sync
- `chart-bar` - Reporting
- `check-circle` - Success/approval
- `folder` - Documents/files
- `calendar` - Calendar/scheduling
- `check-square` - Checklist/tasks
- `lock` - Security/privacy
- `file-check` - Documentation
- `alert-triangle` - Warning/alerts
- `users` - Team/people
- `file-text` - Text/document
- `zap` - Speed/efficiency (default fallback)

## Content Guidelines

### Headlines

**Format:** "Automatisiere deine [Template Type] mit Ordio"

**Guidelines:**

- Direct and benefit-focused
- Template-specific when possible
- Action-oriented verbs (Automatisiere, Digitalisiere, Spare)
- Maximum 60 characters

**Examples:**

- ✅ "Automatisiere deine Wochenplanung mit Ordio"
- ✅ "Digitalisiere deine Zeiterfassung mit Ordio"
- ❌ "Ordio ist eine Software für..." (too generic)

### Subheadlines

**Format:** "[Specific benefit] spart dir [metric]"

**Guidelines:**

- Include specific metrics ("50% weniger Zeit", "10 Stunden pro Woche")
- Connect template pain point to Ordio solution
- One sentence, maximum 80 characters
- Use "du" tone

**Examples:**

- ✅ "Spare Zeit bei der wöchentlichen Planung und reduziere Fehler um bis zu 95%"
- ✅ "Automatische DATEV-Übertragung spart dir 10 Stunden pro Woche"
- ❌ "Ordio ist die beste Lösung" (no specific benefit)

### Benefits

**Structure:** 3-4 benefits per template

**Guidelines:**

- Concrete and measurable ("50% weniger Planungszeit")
- Template-relevant (match to template use case)
- Icon selection matches benefit meaning
- Short descriptions (1-2 sentences)

**Example:**

```json
{
  "icon": "clock",
  "title": "50% weniger Planungszeit",
  "description": "Automatische Wochenplanung mit KI-Unterstützung spart dir wertvolle Zeit"
}
```

### Features

**Structure:** 2-4 features per template

**Format:** "Mit Ordio [Feature] → [Benefit]"

**Guidelines:**

- Deep links to product pages (`/schichtplan`, `/arbeitszeiterfassung`, `/mitarbeiter-app`, `/nano-ai`)
- Only include features that solve template problems
- Benefit should be specific and measurable

**Example:**

```json
{
  "name": "Schichtplan",
  "url": "/schichtplan",
  "benefit": "Erstelle optimierte Wochenpläne in Minuten statt Stunden"
}
```

## Copywriting Best Practices

### Tone

- **Use "du" throughout**: Informal German (duzen)
- **Direct and straight to the point**: No fluff or marketing speak
- **Benefit-driven**: Focus on what user gains, not features

### Ordio Mentions

- **Mention Ordio naturally**: Once per major section is sufficient
- **Don't force**: Integrate naturally into copy
- **Product names**: Use specific product names (Schichtplan, Zeiterfassung, Payroll)

### Metrics

- **Use specific numbers**: "50% weniger Zeit", "95% weniger Fehler"
- **Be realistic**: Don't overpromise
- **Support claims**: Metrics should be believable

### Action-Oriented Language

- **Use strong verbs**: "Automatisiere", "Digitalisiere", "Spare", "Reduziere"
- **Focus on outcomes**: What user achieves, not what software does
- **Remove friction**: "Keine Kreditkarte erforderlich", "Jederzeit kündbar"

## Examples

### Wochenplan Template

```json
{
  "wochenplan-vorlage": {
    "headline": "Automatisiere deine Wochenplanung mit Ordio",
    "subheadline": "Spare Zeit bei der wöchentlichen Planung und reduziere Fehler um bis zu 95%",
    "benefits": [
      {
        "icon": "clock",
        "title": "50% weniger Planungszeit",
        "description": "Automatische Wochenplanung mit KI-Unterstützung spart dir wertvolle Zeit"
      },
      {
        "icon": "shield-check",
        "title": "Automatische ArbZG-Prüfung",
        "description": "Compliance-Checks sorgen für rechtssichere Wochenpläne ohne manuelle Prüfung"
      },
      {
        "icon": "sync",
        "title": "Direkte Zeiterfassung",
        "description": "Wochenplan wird automatisch mit der Zeiterfassung verknüpft"
      },
      {
        "icon": "mobile",
        "title": "Mobile App für alle",
        "description": "Mitarbeiter sehen ihren Wochenplan in Echtzeit in der App"
      }
    ],
    "features": [
      {
        "name": "Schichtplan",
        "url": "/schichtplan",
        "benefit": "Erstelle optimierte Wochenpläne in Minuten statt Stunden"
      },
      {
        "name": "Zeiterfassung",
        "url": "/arbeitszeiterfassung",
        "benefit": "Automatische Übertragung von Plan zu Ist-Zeiten"
      }
    ]
  }
}
```

### Stundenzettel Template

```json
{
  "stundenzettel-excel-vorlage": {
    "headline": "Digitalisiere deine Zeiterfassung mit Ordio",
    "subheadline": "Automatische DATEV-Übertragung spart dir 10 Stunden pro Woche",
    "benefits": [
      {
        "icon": "sync",
        "title": "Automatische DATEV-Übertragung",
        "description": "Zeiten werden direkt in deine Lohnbuchhaltung übertragen – keine manuelle Eingabe"
      },
      {
        "icon": "mobile",
        "title": "Mobile Stempeluhr",
        "description": "Mitarbeiter stempeln per App ein und aus – auch offline verfügbar"
      },
      {
        "icon": "shield-check",
        "title": "Gesetzeskonforme Erfassung",
        "description": "Automatische Einhaltung von ArbZG, Mindestlohn und Arbeitszeitgesetzen"
      },
      {
        "icon": "chart-bar",
        "title": "Echtzeit-Reporting",
        "description": "Sieh sofort, wer wie viele Stunden gearbeitet hat und wo Überstunden anfallen"
      }
    ],
    "features": [
      {
        "name": "Zeiterfassung",
        "url": "/arbeitszeiterfassung",
        "benefit": "Digitale Stempeluhr mit automatischer DATEV-Integration"
      },
      {
        "name": "Payroll",
        "url": "/payroll",
        "benefit": "Nahtlose Übertragung in die Lohnabrechnung"
      }
    ]
  }
}
```

## Layout & Responsive Design

### Desktop Layout (1024px+)

The CTA section uses a two-column grid layout optimized for desktop screens:

- **Left Column (Benefits)**: Flexible width, contains benefit cards and feature links
- **Right Column (CTA Card)**: Fixed width (420px at 1024px, 480px at 1280px, 520px at 1536px+), sticky positioned

**Grid Column Ratios:**

- **1024px - 1279px**: `minmax(0, 1fr) 420px` - Left column flexible, right column 420px
- **1280px - 1535px**: `minmax(0, 1fr) 480px` - Left column flexible, right column 480px
- **1536px+**: `minmax(600px, 1fr) 520px` - Left column minimum 600px, right column 520px

**Sticky Positioning:**

- CTA card uses `position: sticky` with `top: 6rem` on desktop
- Max height: `calc(100vh - 8rem)` to prevent overflow
- Automatically becomes relative positioning on mobile/tablet

### Mobile Layout (< 1024px)

- Single column layout
- CTA card appears first (order-1), then benefits (order-2)
- Full width cards and buttons
- No sticky positioning

### Responsive Breakpoints

- **Mobile**: < 640px - Single column, stacked layout
- **Tablet**: 641px - 1023px - Single column, improved spacing
- **Desktop**: 1024px - 1279px - Two columns, sticky CTA
- **Large Desktop**: 1280px - 1535px - Two columns, wider CTA card
- **XL Desktop**: 1536px+ - Two columns, optimal proportions

### Text Overflow Prevention

All text elements use:

- `overflow-wrap: break-word`
- `word-wrap: break-word`
- `min-width: 0` on flex items
- Proper `box-sizing: border-box`

## Troubleshooting

### CTA Section Not Appearing

**Symptoms:** CTA section doesn't render on template page

**Solutions:**

1. Check `$ctaConfig` is loaded: Add `var_dump($ctaConfig);` before include
2. Verify JSON file exists: Check `v2/data/template-cta-messages.json`
3. Check JSON syntax: Use JSON validator (jsonlint.com)
4. Verify template ID: Check `$templateId` matches JSON key
5. Check PHP errors: Enable error reporting, check logs

### Wrong Content Displaying

**Symptoms:** CTA shows wrong template content or category default

**Solutions:**

1. Check template override exists: Verify key in `template_overrides`
2. Verify category mapping: Check template category in `template-registry.json`
3. Clear PHP opcache: `opcache_reset()` if using opcache
4. Check fallback order: Template → Category → Other → Hardcoded

### Buttons Not Working

**Symptoms:** CTA buttons don't open modals or callback doesn't work

**Solutions:**

1. Verify Alpine.js loaded: Check browser console for errors
2. Check modal store initialized: Verify `$store.modal` exists
3. Verify callback popup script: Check `lead-capture-popup.php` included
4. Check button parameters: Verify `$ctaButtonsLight`, `$showCallbackButton` set correctly

### Icons Not Displaying

**Symptoms:** Benefit cards show no icons or wrong icons

**Solutions:**

1. Check icon name spelling: Must match exact name from icon list
2. Verify `get_icon_svg()` function: Check `template-cta-config.php`
3. Check icon exists: Verify icon name in function
4. Use fallback: Default icon is `zap` if name not found

## Testing

### Manual Testing Checklist

- [ ] CTA section renders on template page
- [ ] Template-specific content displays correctly
- [ ] Category fallbacks work for unmapped templates
- [ ] CTA buttons open modals correctly
- [ ] Callback button triggers lead capture
- [ ] Feature links navigate to correct pages
- [ ] Mobile layout stacks correctly
- [ ] Desktop layout uses two columns
- [ ] Sticky positioning works on desktop
- [ ] Text is readable on all screen sizes

### Automated Testing

```bash
# Test config loader
php -r "require 'v2/config/template-cta-config.php'; \$config = load_template_cta_config('wochenplan-vorlage'); var_dump(\$config);"

# Test category fallback
php -r "require 'v2/config/template-cta-config.php'; \$config = load_template_cta_config('shift-planning-basic'); echo \$config['headline'];"

# Validate JSON syntax
php -r "json_decode(file_get_contents('v2/data/template-cta-messages.json')); echo json_last_error() === JSON_ERROR_NONE ? 'Valid JSON' : json_last_error_msg();"
```

## Performance Considerations

### Optimization

- **Minimal impact**: CTA section adds minimal page weight
- **No lazy loading needed**: Appears above fold after content blocks
- **CSS optimization**: Styles included in minified templates-pages.css
- **No additional JS**: Uses existing Alpine.js and AOS

### Monitoring

- Track CTA button clicks via GTM
- Track callback button clicks
- Track feature link clicks
- Monitor conversion rates per template
- A/B test different headlines (future)

## Related Documentation

- Cursor Rules: `.cursor/rules/templates-cta.mdc`
- Template Pages Rules: `.cursor/rules/templates-pages.mdc`
- Template Configuration: `v2/config/template-page-config.php`
- CTA Component: `v2/components/template-cta.php`
- Config Loader: `v2/config/template-cta-config.php`