michaelschiemer/docs/components/migration-guide.md

Component Migration Guide

Anleitung zur Migration von Templates auf die neue Component-Syntax.

Übersicht

Dieser Guide hilft dabei, bestehende Templates von direkter CSS-Klassen-Verwendung auf die neue <x-*> Component-Syntax zu migrieren.

Schritt-für-Schritt Migration

Schritt 1: Template analysieren

Verwende den Linter um Probleme zu finden:

php console.php design:lint-templates src/Application/Admin/templates/admin-index.view.php

Schritt 2: Button-Migration

Pattern 1: Einfacher Button

<!-- Vorher -->
<button class="btn btn--primary">Save</button>

<!-- Nachher -->
<x-button variant="primary">Save</x-button>

Pattern 2: Button als Link

<!-- Vorher -->
<a href="/admin" class="btn btn--secondary">Back</a>

<!-- Nachher -->
<x-button variant="secondary" href="/admin">Back</x-button>

Pattern 3: Button mit Größe

<!-- Vorher -->
<button class="btn btn--primary btn--sm">Small Button</button>

<!-- Nachher -->
<x-button variant="primary" size="sm">Small Button</x-button>

Pattern 4: Disabled Button

<!-- Vorher -->
<button class="btn btn--primary" disabled>Processing</button>

<!-- Nachher -->
<x-button variant="primary" disabled>Processing</x-button>

Pattern 5: Admin-Button

<!-- Vorher -->
<button class="admin-btn admin-btn--secondary">Click</button>

<!-- Nachher -->
<x-button variant="secondary">Click</x-button>

Schritt 3: Card-Migration

Pattern 1: Einfache Card

<!-- Vorher -->
<div class="card">
    <p>Content</p>
</div>

<!-- Nachher -->
<x-card>
    <p>Content</p>
</x-card>

Pattern 2: Card mit Header

<!-- Vorher -->
<div class="admin-card">
    <div class="admin-card__header">
        <h2 class="admin-card__title">Title</h2>
    </div>
    <div class="admin-card__body">
        <p>Content</p>
    </div>
</div>

<!-- Nachher -->
<x-card title="Title">
    <p>Content</p>
</x-card>

Pattern 3: Card mit Variante

<!-- Vorher -->
<div class="admin-card admin-card--success">
    <p>Success message</p>
</div>

<!-- Nachher -->
<x-card variant="success">
    <p>Success message</p>
</x-card>

Schritt 4: Badge-Migration

Pattern 1: Einfache Badge

<!-- Vorher -->
<span class="badge badge--success">Active</span>

<!-- Nachher -->
<x-badge variant="success">Active</x-badge>

Pattern 2: Admin-Badge

<!-- Vorher -->
<span class="admin-badge admin-badge--error">Error</span>

<!-- Nachher -->
<x-badge variant="error">Error</x-badge>

Pattern 3: Pill Badge

<!-- Vorher -->
<span class="badge badge--info badge--pill">Beta</span>

<!-- Nachher -->
<x-badge variant="info" pill>Beta</x-badge>

Häufige Patterns

In Loops

<!-- Vorher -->
<for items="{{$actions}}" as="action">
    <a href="{{$action['url']}}" class="btn btn--primary">
        {{$action['label']}}
    </a>
</for>

<!-- Nachher -->
<for items="{{$actions}}" as="action">
    <x-button variant="primary" href="{{$action['url']}}">
        {{$action['label']}}
    </x-button>
</for>

Mit Bedingungen

<!-- Vorher -->
<button class="btn btn--primary" if="{{can_edit}}">Edit</button>

<!-- Nachher -->
<x-button variant="primary" if="{{can_edit}}">Edit</x-button>

Mit zusätzlichen Attributen

<!-- Vorher -->
<button class="btn btn--secondary" data-toggle="modal" aria-label="Open">
    Open Modal
</button>

<!-- Nachher -->
<x-button variant="secondary" data-toggle="modal" aria-label="Open">
    Open Modal
</x-button>

Troubleshooting

Problem: Component wird nicht gerendert

Lösung: Stelle sicher, dass die Component registriert ist:

• Component-Klasse existiert in src/Framework/View/Components/
• Component hat #[ComponentName('...')] Attribut
• Component implementiert StaticComponent Interface

Problem: Attribute werden nicht übernommen

Lösung:

• Prüfe ob das Attribut in der Component-Klasse unterstützt wird
• Verwende class Attribut für zusätzliche CSS-Klassen falls nötig

Problem: Alte Syntax funktioniert noch

Lösung:

• Die alte <component name="..."> Syntax wird noch unterstützt, sollte aber migriert werden
• Verwende den Linter um alte Syntax zu finden

Migration-Checkliste

• Template mit Linter analysiert
• Alle Buttons migriert
• Alle Cards migriert
• Alle Badges migriert
• Template getestet
• Keine Linter-Fehler mehr

Automatische Migration (Zukünftig)

Ein --fix Flag für automatische Migration ist geplant, aber noch nicht implementiert. Bitte migriere Templates manuell nach diesem Guide.