# templates-cta Full Instructions

## Overview

The Template CTA Section is a highly tailored, conversion-optimized call-to-action component that appears on all template pages after content blocks but before the templates carousel. It connects template use cases to Ordio product features with template-specific messaging.

## Layout Structure

### Desktop Layout (Single-Column Flow)

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

### Mobile Layout (Stacked)

1. **Benefits**: Single column, stacked vertically
2. **"Mit Ordio"**: Single column, stacked feature cards
3. **CTA Buttons**: Full-width at end, mobile-optimized text

### Responsive CTA Text

- **Desktop**: "Jetzt kostenlos testen" + full subtext
- **Mobile**: "Kostenlos starten" + shorter subtext (CSS `lg:hidden` / `hidden lg:block`)

## Component Structure

### Files

- **Component**: `v2/components/template-cta.php` - Main CTA component
- **Config Loader**: `v2/config/template-cta-config.php` - Configuration loader with category fallbacks
- **Data File**: `v2/data/template-cta-messages.json` - Template-specific messaging data
- **Styles**: `v2/css/templates-pages.css` - CTA section styles (appended to existing file)

### Integration

The CTA section is automatically included in `v2/pages/templates_template.php`:

```php
// Load CTA configuration
$ctaConfig = load_template_cta_config($templateId);
if (!empty($ctaConfig) && (!empty($ctaConfig['benefits']) || !empty($ctaConfig['features']))) {
    include __DIR__ . '/../components/template-cta.php';
}
```

## Configuration System

### Priority Order

1. **Template-specific override** from `template_overrides` in JSON
2. **Category-based default** from `category_defaults` in JSON
3. **Generic "other" category** fallback
4. **Hardcoded default** (if JSON fails to load)

### Configuration Format

```json
{
  "category_defaults": {
    "shift_planning": {
      "headline": "Automatisiere deine Schichtplanung mit Ordio",
      "subheadline": "Spare Zeit bei der Planung und reduziere Fehler um bis zu 95%",
      "benefits": [
        {
          "icon": "clock",
          "title": "50% weniger Planungszeit",
          "description": "Automatische Schichtplanung mit KI-Unterstützung spart dir wertvolle Zeit"
        }
      ],
      "features": [
        {
          "name": "Schichtplan",
          "url": "/schichtplan",
          "benefit": "Erstelle optimierte Pläne in Minuten statt Stunden"
        }
      ]
    }
  },
  "template_overrides": {
    "wochenplan-vorlage": {
      // Template-specific override
    }
  }
}
```

## Customization Process

### Adding Template-Specific CTA

1. **Edit** `v2/data/template-cta-messages.json`
2. **Add** entry to `template_overrides` section:
   ```json
   "template-id": {
     "headline": "Custom headline",
     "subheadline": "Custom subheadline",
     "benefits": [...],
     "features": [...]
   }
   ```
3. **Save** - Changes take effect immediately (no cache)

### Adding Category Default

1. **Edit** `v2/data/template-cta-messages.json`
2. **Add/Update** entry in `category_defaults` section
3. **All templates** in that category will use this default (unless overridden)

## Component Parameters

The component accepts these variables (set automatically):

- `$ctaConfig` - Configuration array from `load_template_cta_config()`
- `$ctaButtonsLight` - Set to `'yes'` for light button style
- `$ctaPositionLeft` - Set to `'false'` for centered buttons
- `$showCallbackButton` - Set to `'yes'` to show callback option
- `$ctaButtonsAOS` - Set to `'fade-up'` for AOS animation

## Icon System

Icons are defined in `get_icon_svg()` function in `template-cta-config.php`:

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

## Best Practices

### Headlines

- **Direct and benefit-focused**: "Automatisiere deine Schichtplanung mit Ordio"
- **Template-specific**: Reference the template type when relevant
- **Action-oriented**: Use verbs like "Automatisiere", "Digitalisiere", "Spare"

### Subheadlines

- **Specific metrics**: "Spare Zeit bei der Planung und reduziere Fehler um bis zu 95%"
- **Clear value proposition**: Connect template pain point to Ordio solution
- **Concise**: One sentence, maximum two

### Benefits

- **3-4 benefits per template**: Not too many, not too few
- **Concrete and measurable**: "50% weniger Planungszeit", "10 Stunden pro Woche sparen"
- **Template-relevant**: Match benefits to template use case
- **Icon selection**: Choose icons that match benefit meaning

### Features

- **4 features per template (always)**: For visual consistency, every template must show exactly 4 related products/features under "Mit Ordio:". Focus on most relevant Ordio features.
- **Deep links**: Link to specific product pages (`/schichtplan`, `/arbeitszeiterfassung`, `/mitarbeiter-app`, `/nano-ai`). Use canonical URLs only (see `docs/development/CANONICAL_URLS_AND_LINKING.md`).
- **Format**: "Mit Ordio [Feature] → [Benefit]"
- **Relevance**: Only include features that solve template problems
- **Mapping guidance**: Include **Mitarbeiter-App** when template mentions mobile app, employee self-service, plans in real-time, availability, or stamping. Include **Nano AI** when template mentions KI, AI, automation, or intelligent planning.

## Content Guidelines

### Tone

- **Use "du" throughout**: Informal German (duzen)
- **Direct and straight to the point**: No fluff
- **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

## Layout Structure (Updated 2026-01-05)

### Desktop (>1024px)

- **Single-column flow**: Benefits → "Mit Ordio" → CTA buttons
- **Benefits Grid (2x2)**: Four benefit cards in 2x2 grid, centered (`max-w-4xl`)
- **"Mit Ordio" Cards**: 4 feature cards in 2x2 grid
- **CTA Buttons**: Centered with `max-w-md`, optimized sizing
- **No sticky positioning**: Removed for better flow

### Tablet (640-1024px)

- **Single-column flow**: Same order as desktop
- **Benefits Grid**: 2x2 grid maintained
- **"Mit Ordio" Cards**: 2-column grid
- **CTA Buttons**: Centered

### Mobile (<640px)

- **Single column**: Stacked vertically
- **Benefits**: Single column, stacked
- **"Mit Ordio"**: Single column, stacked feature cards
- **CTA Buttons**: Full-width at end, mobile-optimized text

## Accessibility

### Requirements

- **WCAG AA compliance**: Color contrast ratios meet standards
- **Semantic HTML**: Proper heading hierarchy (h2, h3)
- **ARIA labels**: Feature links have descriptive text
- **Focus indicators**: Visible focus states on interactive elements
- **Keyboard navigation**: All elements keyboard accessible

### Implementation

- Use semantic HTML (`<section>`, `<h2>`, `<h3>`)
- Add `aria-label` to icon-only elements
- Ensure focus states are visible
- Test with screen readers

## Performance

### 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

## Testing Checklist

### Template Download Modal UX

- **Spacing:** `mb-5` on consent checkbox, `mt-4` between button and disclaimer. See `lead-gen-forms-ux.mdc`.
- **Exit behavior:** ESC key and click-outside must close the modal. See `lead-gen-forms-ux.mdc`.

### Functionality

- [ ] 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

### Responsive Design

- [ ] Mobile layout stacks correctly (Benefits → "Mit Ordio" → CTA)
- [ ] Tablet layout displays properly (2x2 benefits grid)
- [ ] Desktop layout uses 2x2 benefits grid
- [ ] "Mit Ordio" cards display correctly (2x2 grid desktop/tablet, 1 column mobile)
- [ ] CTA buttons are centered and properly sized
- [ ] Responsive CTA text displays correctly (different on mobile vs desktop)
- [ ] Text is readable on all screen sizes

### Content Quality

- [ ] Headlines are template-specific
- [ ] Benefits match template use case
- [ ] Features link to relevant product pages
- [ ] Copy uses "du" tone
- [ ] Metrics are realistic and specific
- [ ] No typos or grammar errors

## Troubleshooting

### CTA Section Not Appearing

1. Check `$ctaConfig` is loaded: `var_dump($ctaConfig);`
2. Verify JSON file exists: `v2/data/template-cta-messages.json`
3. Check JSON syntax: Use JSON validator
4. Verify template ID matches: Check `$templateId` value

### Wrong Content Displaying

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

### Buttons Not Working

1. Verify Alpine.js is loaded
2. Check modal store is initialized
3. Verify callback popup script is loaded
4. Check browser console for errors

## 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"
      }
    ],
    "features": [
      {
        "name": "Schichtplan",
        "url": "/schichtplan",
        "benefit": "Erstelle optimierte Wochenpläne in Minuten statt Stunden"
      }
    ]
  }
}
```

### 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"
      }
    ],
    "features": [
      {
        "name": "Zeiterfassung",
        "url": "/arbeitszeiterfassung",
        "benefit": "Digitale Stempeluhr mit automatischer DATEV-Integration"
      }
    ]
  }
}
```

## Related Documentation

- Template Pages Guide: `.cursor/rules/templates-pages.mdc`
- Template CTA Implementation Guide: `docs/guides/templates/TEMPLATE_CTA_GUIDE.md`
- Template Configuration: `v2/config/template-page-config.php`