# templates-pages-core Full Instructions

## Labor Law Values – Annual Update Checklist

**CRITICAL:** Template pages display Mindestlohn, Minijob-Grenze, and Midijob-Bereich. These values change yearly (typically 01.01.). Use `docs/content/LABOR_LAW_VALUES_2026.md` as the single source of truth.

**When updating labor law values (e.g. each January):**

1. Verify new values on [BMAS](https://www.bmas.de/DE/Arbeit/Arbeitsrecht/Mindestlohn/mindestlohn.html) and [Minijob-Zentrale](https://www.minijob-zentrale.de/)
2. Update `v2/systems/excel-template-generator/data/template-formulas/public-data.json`
3. Update all templates_*.php pages: meta tags, schema, FAQ, cost cards, export hints, minWage in Alpine.js
4. Update template definition JSON files if formulas reference hardcoded values
5. Update `docs/content/LABOR_LAW_VALUES_2026.md`

**Affected files:** templates_template.php, templates_index.php, public-data.json, template-faqs.json (dienstplan/schichtplan FAQs). Dienstplan and Schichtplan are now served by templates_template.php (generator-driven); dedicated PHP files deprecated 2026-02.

## Content Writing Best Practices

**See:** `.cursor/rules/content-writing.mdc` for comprehensive content writing guidelines.

### Natural Language Writing

When creating or updating template page content:

- ✅ **Human-first content:** Write for humans first, optimize for search engines second
- ✅ **Natural language:** Use conversational tone, vary sentence structures
- ✅ **AI content avoidance:** Avoid AI content tells (overly formal language, repetitive structures)
- ✅ **Specific examples:** Include concrete examples, usage scenarios, and use cases
- ✅ **E-E-A-T:** Demonstrate Experience, Expertise, Authoritativeness, Trustworthiness

**Key Resources:**

- `docs/content/CONTENT_WRITING_BEST_PRACTICES_2026.md` - Comprehensive content writing guide
- `docs/content/AI_CONTENT_AVOIDANCE_GUIDE.md` - AI content avoidance guide
- `docs/content/META_TAGS_OPTIMIZATION_GUIDE.md` - Meta tags optimization guide

## Templates Page Purpose

Provide downloadable Excel/PDF templates (Dienstplan, Schichtplan, and other registry templates) with HubSpot form integration for lead capture. Dienstplan and Schichtplan are generator-driven (templates_template.php); pre-generated .xlsx served via `/v2/api/download-template.php`. Template download functionality is active; customizer functionality is currently disabled (buttons show "Bald verfügbar").

**CTA Section:** All template pages include a highly tailored CTA section after content blocks (before carousel) that connects template use cases to Ordio product features. See `.cursor/rules/templates-cta.mdc` for complete CTA section documentation.

**Dynamic Content Generation:** All template pages now use dynamic generation for meta tags, schema markup, FAQs, and Alpine.js components. Content is automatically loaded from template registry and definition files.

## Current State

**Note:** Customizer functionality is currently disabled on template pages. The customizer buttons display "Bald verfügbar" (Coming Soon). Only template download functionality is active.

## Unique Requirements

### Template Download Form Pattern

**Current implementation:**

- HubSpot form integration for lead capture
- Simple form with firstName, lastName, email, phone fields
- **Dual format selection:** Excel (.xlsx) download or Google Sheets copy link
- Format selection always visible (segmented control pattern)
- Google Sheets option disabled when unavailable
- Form submission triggers template download/copy based on selected format
- Uses `/v2/api/submit-template.php` endpoint

**Alpine.js Component Structure:**

```javascript
function createTemplateData() {
    return {
        showHubSpotForm: false,
        templateForm: {
            fullName: '',
            email: '',
            phone: ''
        },
        isSubmittingTemplate: false,
        selectedFormat: 'excel', // 'excel' or 'google_sheets'
        googleSheetsAvailable: false,
        googleSheetsCopyUrl: null,

        openHubSpotForm() { ... },
        async checkGoogleSheetsAvailability() { ... },
        async submitTemplateDownloadForm() { ... },
        async downloadStandardTemplate() { ... },
        async openGoogleSheetsCopy() { ... },
        async syncWithHubSpot() { ... },
        showTemplateDownloadSuccess(type) { ... }
    };
}
```

**Format Selection:**

- Segmented control UI (always visible)
- Excel option always enabled
- Google Sheets option enabled/disabled based on availability
- Sends `template_type` parameter ('Excel' or 'Google Sheets') to API
- HubSpot property `template_type__c` set based on format selection

### Customizer UI Patterns (DISABLED - For Future Reference)

**Common customizer inputs:**

- **Time pickers:** Opening/closing hours, shift start/end times
- **Role/position inputs:** Add/remove dynamically (e.g., "Servicekraft", "Koch", "Barista")
- **Break duration inputs:** Min/max breaks, auto-calculation
- **Cost calculation inputs:** Hourly rates per role
- **Color pickers:** Template styling (optional, for advanced customization)

**Example structure:**

```html
<div class="customizer-section">
  <h3>Öffnungszeiten</h3>
  <input type="time" id="opening_time" value="08:00" />
  <input type="time" id="closing_time" value="22:00" />
</div>

<div class="customizer-section">
  <h3>Rollen hinzufügen</h3>
  <div id="roles-container">
    <input type="text" placeholder="z.B. Servicekraft" />
    <button class="add-role">+ Hinzufügen</button>
  </div>
</div>
```

### State Management Pattern

**JavaScript object holds customizer state:**

```javascript
const templateState = {
  openingHours: { start: "08:00", end: "22:00" },
  roles: ["Servicekraft", "Koch"],
  breaks: { min: 30, max: 60 },
  costs: { servicekraft: 15.0, koch: 18.0 },
};
```

**Real-time updates to preview:**

```javascript
function updatePreview() {
  // Regenerate preview based on templateState
  renderTemplate(templateState);
}

// Trigger on any customizer change
document.querySelectorAll(".customizer-input").forEach((input) => {
  input.addEventListener("change", updatePreview);
});
```

**Validation before export:**

```javascript
function validateState() {
  if (templateState.roles.length === 0) {
    alert("Bitte mindestens eine Rolle hinzufügen");
    return false;
  }
  // More validation...
  return true;
}
```

### Real-Time Preview Pattern

**Preview section:**

- Display template preview (HTML table or canvas)
- Update immediately when customizer changes
- Visual distinction (border, shadow, background)

**Preview should show:**

- Populated template with customizer values
- Realistic sample data (not "Lorem Ipsum")
- Formatting as it will appear in export


## Validation Checklist (Templates-Specific)

See `.cursor/rules/shared-patterns.mdc` for universal validation checklist.

**Templates-Specific:**

- [ ] Template download form works (HubSpot integration functional)
- [ ] Format selection UI always visible (Excel and Google Sheets options)
- [ ] Google Sheets option disabled when unavailable (visual indicator, tooltip)
- [ ] Format selection validation prevents submission if Google Sheets selected but unavailable
- [ ] Form submission sends `template_type` parameter ('Excel' or 'Google Sheets')
- [ ] HubSpot receives correct `template_type__c` value based on format selection
- [ ] Form submission values are correct (industry: 'gastronomie', company_size: '', content_type: '[Template] Vorlage - Template')
- [ ] hubspotutk cookie extraction works (fallback from cookies if not in UTM data)
- [ ] Excel export follows Ordio branding (no purple, proper column widths, no header borders)
- [ ] PDF export includes Ordio logo and clean layout (if applicable)
- [ ] CSV export format compatible with Ordio import (if applicable)
- [ ] Customizer buttons are disabled with "Bald verfügbar" text (if customizer UI present)
- [ ] DigitalDocument schema includes all export formats
- [ ] No references to active customizer functionality in meta tags or schema (only disabled state)
- [ ] HowTo schema walks through customizer usage
- [ ] Validation prevents invalid exports (e.g., no roles added)
- [ ] Filename includes template name and date
- [ ] No console errors


## Edge Cases & Gotchas

### Dynamic Role Management

User can add/remove roles dynamically:

- Track roles in array: `roles: ['Servicekraft', 'Koch']`
- Generate preview rows for each role
- Export includes all roles user added
- Handle empty roles array (validation error)

### Break Calculations

If template includes break auto-calculation:

- ArbZG: >6h work requires 30min break, >9h requires 45min
- Apply automatically based on shift length
- User can override if needed

### Cost Calculations

If template includes cost calculation:

- Track hourly rates per role
- Calculate: `total_hours × hourly_rate`
- Display in preview
- Include in export with formulas

### Ordio-CSV Format

Ordio expects specific column order:

- Check Ordio import documentation
- Include required columns (date, role, start_time, end_time, etc.)
- Optional columns (notes, breaks, costs)
- Test import in Ordio after export


## Reference Documentation

For detailed workflows:

- `docs/guides/PAGE_TYPE_GUIDES.md` – Quick reference for template pages
- `docs/ai/cursor-playbook.md` – Cursor-specific prompting patterns

For similar page types:

- Tools pages (tools-pages-core.mdc, tools-pages-patterns-gated.mdc, tools-pages-patterns-export.mdc) – Similar form and export patterns
- Download pages (download-pages.mdc) – Similar file delivery patterns

## Related Documentation

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping.

**Key Documentation:**

- [docs/guides/PAGE_TYPE_GUIDES.md](../../docs/guides/PAGE_TYPE_GUIDES.md) - `docs/guides/PAGE_TYPE_GUIDES.md` - Page type quick reference
- [docs/content/pages/templates-pages/](../../docs/content/pages/templates-pages/) - `docs/content/pages/templates-pages/` - Template pages documentation (if exists)


## Excel Visual Component

The Excel visual component (`v2/components/excel-visual.php`) is a modular, template-type-aware system that automatically extracts and visualizes data from template JSON definitions.

### Automatic Extraction

The visual component automatically:

- Extracts data from template JSON definitions via `load_excel_visual_data()`
- Detects data structure (table, key-value, list)
- Applies template-category-specific formatting
- Handles edge cases with graceful fallbacks

### Visual Strategies

Different template categories use different visual strategies:

- **shift_planning**: Table layout with time formatting
- **time_tracking**: Table layout with time/numeric formatting
- **payroll**: Table layout with currency formatting
- **employee_management**: Key-value or table layouts
- **compliance**: List or table layouts

### Customization

Template-specific overrides can be added in `apply_template_visual_overrides()` function in `template-page-config.php`.

**Testing:**

- Run `php v2/systems/excel-template-generator/scripts/test-visual-extraction.php` to test all templates
- Check `v2/systems/excel-template-generator/reports/visual-extraction-test-results.json` for results

See `docs/templates/EXCEL_VISUAL_GUIDE.md` for complete documentation.


## Export Functionality (Templates-Specific)

### Excel Export

Follow Ordio branding [[memory:8147019]]:

- **No purple:** Use relevant brand colors (blues, neutrals)
- **Consistent styling:** Ordio colors across sheets
- **Proper column widths:** Based on header length and content
- **No header borders:** Cleaner look

**Include in export:**

- Customized template (with user's roles, times, etc.)
- Pre-filled formulas where applicable (e.g., sum of hours)
- Proper formatting (dates, times, currency)
- Ordio branding (subtle, not obtrusive)

**Filename:** `[template-name]-[date].xlsx`  
Example: `dienstplan-2025-11-10.xlsx`

### PDF Export

- **Ordio logo:** Top of document
- **Clean layout:** Matching Excel structure
- **Ordio branding:** Colors, fonts
- **Filename:** `[template-name]-[date].pdf`

### Ordio-CSV Export

**Format compatible with Ordio import:**

- Specific column order expected by Ordio
- Proper encoding (UTF-8)
- Include all customized fields
- **Filename:** `[template-name]-ordio-[date].csv`

description: 'Template page patterns - Content Blocks: SEO content block structure,
  block types, keyword integration from SISTRIX, content file paths, sync workflow.'
globs:
- v2/pages/templates_template.php
- v2/components/template-content-blocks.php
- docs/systems/templates/template-data/**/content-blocks.json
- docs/systems/templates/template-data/**/content/*.md
alwaysApply: false
relatedRules:
- templates-pages.mdc
- templates-pages-seo.mdc
- shared-patterns.mdc
relatedDocs:
- docs/systems/templates/TEMPLATE_CONTENT_WORKFLOW.md
- docs/systems/templates/TEMPLATE_SKYSCRAPER_GUIDE.md
- docs/content/blog/CONTENT_FORMAT_PATTERNS.md
- docs/systems/templates/TEMPLATE_CONTENT_BLOCKS_GUIDE.md
- docs/systems/templates/TEMPLATE_CONTENT_EDIT_WORKFLOW.md
- docs/systems/templates/TEMPLATE_CONTENT_DEPTH_GUIDELINES.md
- docs/systems/templates/KEYWORD_MAPPING.md
- docs/systems/templates/TEMPLATE_DATA_COLLECTION_GUIDE.md
- docs/content/blog/ANTI_FLUFF_CHECKLIST.md

description: "Template page patterns - Core: Content writing, purpose, requirements, and dynamic content generation. Part of templates pages system."
globs:
  - v2/pages/templates_*.php
  - v2/css/templates-pages.css
alwaysApply: false
relatedRules:
  - templates-pages-components.mdc
  - templates-pages-seo.mdc
  - templates-pages-patterns.mdc
  - templates-cta.mdc
  - shared-patterns.mdc
relatedDocs:
  - docs/guides/templates/TEMPLATE_CTA_GUIDE.md
  - docs/guides/PAGE_TYPE_GUIDES.md
  - docs/content/LABOR_LAW_VALUES_2026.md
description: 'Template page patterns - FAQ: FAQ structure, 8-12 count, 40-80 words,
  PAA/GSC sources, schema compatibility.'
globs:
- v2/systems/excel-template-generator/data/template-faqs.json
- v2/scripts/templates/*faq*.php
- docs/systems/templates/template-data/**/faq-*.json
alwaysApply: false
relatedRules:
- templates-pages.mdc
- templates-pages-seo.mdc
- shared-patterns.mdc
relatedDocs:
- docs/systems/templates/TEMPLATE_FAQ_WORKFLOW.md
- docs/content/FAQ_WEBSITE_STANDARD.md
- docs/content/FAQ_REWORK_DECISION_TREE.md
description: 'Template page patterns - Improvement Process: When to run pipeline,
  phase gates, validation.'
globs:
- v2/scripts/templates/*.php
- docs/systems/templates/template-data/**
- docs/systems/templates/TEMPLATE_*.md
alwaysApply: false
relatedRules:
- templates-pages-content-blocks.mdc
- templates-pages-faq.mdc
- templates-pages.mdc
- templates-content-creation-gate.mdc
relatedDocs:
- docs/systems/templates/TEMPLATE_SYSTEM_OVERVIEW.md
- docs/systems/templates/TEMPLATE_CONTENT_WORKFLOW.md
- docs/systems/templates/TEMPLATE_DATA_COLLECTION_GUIDE.md
- docs/systems/templates/TEMPLATE_SERP_ANALYSIS_WORKFLOW.md
- docs/systems/templates/TEMPLATE_CONTENT_CREATION_WORKFLOW.md

description: "Template page patterns - Patterns: Copy patterns, validation checklist, common pitfalls, edge cases, and Alpine.js initialization. Part of templates pages system."
globs:
  - v2/pages/templates_*.php
  - v2/css/templates-pages.css
alwaysApply: false
relatedRules:
  - templates-pages-core.mdc
  - templates-pages-components.mdc
  - templates-pages-seo.mdc
  - templates-cta.mdc
  - shared-patterns.mdc
relatedDocs:
  - docs/guides/templates/TEMPLATE_CTA_GUIDE.md
  - docs/guides/PAGE_TYPE_GUIDES.md

description: "Template page patterns - SEO: Schema requirements, CSS guidelines, and meta tags. Part of templates pages system."
globs:
  - v2/pages/templates_*.php
  - v2/css/templates-pages.css
alwaysApply: false
relatedRules:
  - templates-pages-core.mdc
  - templates-pages-components.mdc
  - templates-pages-patterns.mdc
  - templates-cta.mdc
  - shared-patterns.mdc
relatedDocs:
  - docs/guides/templates/TEMPLATE_CTA_GUIDE.md
  - docs/guides/PAGE_TYPE_GUIDES.md
  - docs/reference/schemas/
  - docs/systems/templates/TEMPLATE_SEO_META_WORKFLOW.md
  - docs/systems/templates/TEMPLATE_INVENTORY_KEYWORD_WORKFLOW.md
  - docs/content/META_TAGS_OPTIMIZATION_GUIDE.md

## CSS Guidelines (Templates-Specific)

### Shared CSS File

```php
<link rel="stylesheet" href="/v2/css/templates-pages.css?v=<?php echo filemtime($_SERVER['DOCUMENT_ROOT'] . '/v2/css/templates-pages.css'); ?>">
```

### Customizer UI Styling

**Customizer should:**

- Be visually distinct from preview (sidebar or top section)
- Use form styling consistent with tools-pages.css (reuse patterns)
- Have clear section headings
- Stack on mobile (single column)

**Preview should:**

- Be visually distinct (border, shadow, background)
- Responsive (scale down on mobile, horizontal scroll if needed)
- Update in real-time (no "refresh preview" button needed)



## Overview

**This rule has been split into focused files for better maintainability:**

- **`templates-pages-core.mdc`** - Content writing, purpose, requirements, dynamic content generation
- **`templates-pages-components.mdc`** - Excel visual component, CTA section, export functionality
- **`templates-pages-seo.mdc`** - Schema requirements, CSS guidelines, meta tags
- **`templates-pages-patterns.mdc`** - Copy patterns, validation checklist, common pitfalls, edge cases, Alpine.js initialization
- **`templates-pages-content-blocks.mdc`** - Content block structure, keyword integration, SISTRIX
- **`templates-pages-faq.mdc`** - FAQ structure, 8-12 count, PAA/GSC sources
- **`templates-pages-improvement-process.mdc`** - Pipeline phases, when to run, validation

Template pages provide downloadable Excel/PDF templates (Dienstplan, Schichtplan, Arbeitszeugnis) with HubSpot form integration for lead capture.

## Template Publication

**When publishing a new template:** Run through [TEMPLATE_PUBLICATION_CHECKLIST.md](../../docs/systems/templates/TEMPLATE_PUBLICATION_CHECKLIST.md) to ensure full discoverability (sitemap, llms, index), blog carousel inclusion, and internal linking from relevant posts.

**See the split files above for detailed documentation.**