Projektarbeit-MYP/backend/app/docs/UI_COMPONENTS.md

UI-Komponenten Dokumentation - MYP Platform

Diese Dokumentation beschreibt alle verfügbaren UI-Komponenten und Template-Helper der MYP Platform.

Übersicht

Die MYP Platform bietet ein umfassendes UI-Komponenten-System basierend auf:

• Tailwind CSS für das Styling
• Jinja2 Template-Helper für einfache Verwendung in Templates
• JavaScript-Utilities für interaktive Funktionen

Template-Helper

Buttons

ui_button(text, type, size, classes, icon, onclick, disabled, **attrs)

Erstellt styled Buttons mit verschiedenen Varianten.

Parameter:

• text (str): Button-Text
• type (str): Button-Typ - "primary", "secondary", "danger", "success"
• size (str): Button-Größe - "sm", "md", "lg"
• classes (str): Zusätzliche CSS-Klassen
• icon (str): SVG-Icon-Code
• onclick (str): JavaScript-Code für onclick
• disabled (bool): Button deaktiviert
• **attrs: Zusätzliche HTML-Attribute

Beispiele:

{{ ui_button("Speichern", "primary", "md") }}
{{ ui_button("Löschen", "danger", "sm", icon=icons.trash) }}
{{ ui_button("Bearbeiten", "secondary", onclick="editItem(123)") }}
{{ ui_button("Deaktiviert", "primary", disabled=true) }}

Badges

ui_badge(text, type, classes)

Erstellt kleine Label/Tags für Status-Anzeigen.

Parameter:

• text (str): Badge-Text
• type (str): Badge-Typ - "blue", "green", "red", "yellow", "purple"
• classes (str): Zusätzliche CSS-Klassen

Beispiele:

{{ ui_badge("Neu", "blue") }}
{{ ui_badge("Aktiv", "green") }}
{{ ui_badge("Fehler", "red") }}

ui_status_badge(status, type)

Erstellt spezielle Status-Badges für Jobs und Drucker.

Parameter:

• status (str): Status-Wert
• type (str): Typ - "job" oder "printer"

Job-Status:

• queued → "In Warteschlange"
• printing → "Wird gedruckt"
• completed → "Abgeschlossen"
• failed → "Fehlgeschlagen"
• cancelled → "Abgebrochen"
• paused → "Pausiert"

Drucker-Status:

• ready → "Bereit"
• busy → "Beschäftigt"
• error → "Fehler"
• offline → "Offline"
• maintenance → "Wartung"

Beispiele:

{{ ui_status_badge("printing", "job") }}
{{ ui_status_badge("ready", "printer") }}

Cards

ui_card(title, content, footer, classes, hover)

Erstellt Container-Karten für Inhalte.

Parameter:

• title (str): Karten-Titel
• content (str): Karten-Inhalt (HTML möglich)
• footer (str): Karten-Footer (HTML möglich)
• classes (str): Zusätzliche CSS-Klassen
• hover (bool): Hover-Effekt aktivieren

Beispiele:

{{ ui_card(
    title="Drucker Status",
    content="<p>Ultimaker S3 ist bereit</p>",
    footer=ui_button("Details", "primary", "sm"),
    hover=true
) }}

Alerts

ui_alert(message, type, dismissible)

Erstellt Benachrichtigungen und Warnungen.

Parameter:

• message (str): Alert-Nachricht
• type (str): Alert-Typ - "info", "success", "warning", "error"
• dismissible (bool): Schließbar machen

Beispiele:

{{ ui_alert("Job erfolgreich erstellt!", "success", dismissible=true) }}
{{ ui_alert("Warnung: Drucker offline", "warning") }}

Modals

ui_modal(modal_id, title, content, footer, size)

Erstellt Modal-Dialoge.

Parameter:

• modal_id (str): Eindeutige Modal-ID
• title (str): Modal-Titel
• content (str): Modal-Inhalt (HTML möglich)
• footer (str): Modal-Footer (HTML möglich)
• size (str): Modal-Größe - "sm", "md", "lg", "xl"

Beispiele:

{{ ui_modal(
    "confirm-delete",
    "Löschen bestätigen",
    "<p>Möchten Sie diesen Job wirklich löschen?</p>",
    ui_button("Abbrechen", "secondary", onclick="MYP.Modal.close('confirm-delete')") + " " + ui_button("Löschen", "danger"),
    "sm"
) }}

Tabellen

ui_table(headers, rows, classes, striped)

Erstellt styled Tabellen.

Parameter:

• headers (List[str]): Tabellen-Kopfzeilen
• rows (List[List[str]]): Tabellen-Zeilen
• classes (str): Zusätzliche CSS-Klassen
• striped (bool): Zebra-Streifen aktivieren

Beispiele:

{% set headers = ["Name", "Status", "Aktionen"] %}
{% set rows = [
    ["Job 1", ui_status_badge("printing", "job"), ui_button("Details", "secondary", "sm")],
    ["Job 2", ui_status_badge("queued", "job"), ui_button("Details", "secondary", "sm")]
] %}
{{ ui_table(headers, rows, striped=true) }}

Template-Filter

Datum & Zeit

german_datetime

Formatiert Datetime-Objekte für deutsche Anzeige.

Beispiele:

{{ job.created_at|german_datetime }}  <!-- 15.03.2024 14:30 -->
{{ job.created_at|german_datetime("%d.%m.%Y") }}  <!-- 15.03.2024 -->
{{ job.created_at|german_datetime("%H:%M") }}  <!-- 14:30 -->

duration

Formatiert Dauer in Minuten zu lesbarem Format.

Beispiele:

{{ 30|duration }}   <!-- 30 Min -->
{{ 90|duration }}   <!-- 1 Std 30 Min -->
{{ 120|duration }}  <!-- 2 Std -->

json

Enkodiert Python-Daten als JSON für JavaScript.

Beispiele:

<script>
const jobData = {{ job_dict|json|safe }};
</script>

Globale Variablen

Icons

Verfügbare SVG-Icons über icons.*:

• icons.check - Häkchen
• icons.x - X/Schließen
• icons.plus - Plus/Hinzufügen
• icons.edit - Bearbeiten
• icons.trash - Löschen
• icons.printer - Drucker
• icons.dashboard - Dashboard

Beispiele:

{{ ui_button("Hinzufügen", "primary", icon=icons.plus) }}
{{ ui_button("Löschen", "danger", icon=icons.trash) }}

Weitere Globale Variablen

• current_year - Aktuelles Jahr

JavaScript-Utilities

Toast-Nachrichten

// Toast anzeigen
MYP.Toast.show('Nachricht', 'success');  // success, error, warning, info

// Toast ausblenden
MYP.Toast.hide();

Modal-Steuerung

// Modal öffnen
MYP.Modal.open('modal-id');

// Modal schließen
MYP.Modal.close('modal-id');

Dropdown-Steuerung

// Dropdown umschalten
MYP.Dropdown.toggle('dropdown-id');

// Dropdown schließen
MYP.Dropdown.close('dropdown-id');

Loading-Anzeige

// Loading anzeigen
MYP.Loading.show();

// Loading ausblenden
MYP.Loading.hide();

Status-Helper

// CSS-Klassen für Status abrufen
const jobClass = MYP.Status.getJobStatusClass('printing');
const printerClass = MYP.Status.getPrinterStatusClass('ready');

// Status-Text formatieren
const jobText = MYP.Status.formatJobStatus('printing');
const printerText = MYP.Status.formatPrinterStatus('ready');

CSS-Klassen

Button-Klassen

• .btn - Basis-Button-Klasse
• .btn-primary - Primärer Button (blau)
• .btn-secondary - Sekundärer Button (grau)
• .btn-danger - Gefahr-Button (rot)
• .btn-success - Erfolg-Button (grün)
• .btn-sm - Kleiner Button
• .btn-lg - Großer Button

Badge-Klassen

• .badge - Basis-Badge-Klasse
• .badge-blue, .badge-green, .badge-red, .badge-yellow, .badge-purple

Status-Klassen

Job-Status:

• .job-status - Basis-Klasse
• .job-queued, .job-printing, .job-completed, .job-failed, .job-cancelled, .job-paused

Drucker-Status:

• .printer-status - Basis-Klasse
• .printer-ready, .printer-busy, .printer-error, .printer-offline, .printer-maintenance

Card-Klassen

• .card - Basis-Card-Klasse
• .card-hover - Card mit Hover-Effekt

Alert-Klassen

• .alert - Basis-Alert-Klasse
• .alert-info, .alert-success, .alert-warning, .alert-error

Tabellen-Klassen

• .table-container - Tabellen-Container
• .table-styled - Styled Tabelle

Verwendung in Templates

Basis-Template erweitern

{% extends "base.html" %}

{% block content %}
<div class="container mx-auto px-4 py-8">
    <h1 class="text-2xl font-bold mb-6">Meine Seite</h1>
    
    <!-- UI-Komponenten verwenden -->
    {{ ui_alert("Willkommen!", "info") }}
    
    {{ ui_card(
        title="Beispiel-Karte",
        content="<p>Hier ist der Inhalt der Karte.</p>",
        footer=ui_button("Aktion", "primary")
    ) }}
</div>
{% endblock %}

{% block scripts %}
<script src="{{ url_for('static', filename='js/ui-components.js') }}"></script>
<script>
    // Eigene JavaScript-Funktionen
</script>
{% endblock %}

Formulare mit UI-Komponenten

<form>
    <div class="space-y-4">
        <div>
            <label class="block text-sm font-medium mb-2">Job Name</label>
            <input type="text" class="w-full px-3 py-2 border rounded-md">
        </div>
        
        <div class="flex space-x-2">
            {{ ui_button("Abbrechen", "secondary") }}
            {{ ui_button("Speichern", "primary", icon=icons.check) }}
        </div>
    </div>
</form>

Demo-Seite

Eine vollständige Demo aller UI-Komponenten ist verfügbar unter /demo (nur für angemeldete Benutzer).

Anpassungen

Eigene CSS-Klassen hinzufügen

{{ ui_button("Custom Button", "primary", classes="my-custom-class") }}

Eigene HTML-Attribute

{{ ui_button("Button", "primary", data_id="123", aria_label="Speichern") }}

Eigene Icons verwenden

{% set custom_icon = '<svg>...</svg>' %}
{{ ui_button("Custom", "primary", icon=custom_icon) }}

Best Practices

1. Konsistenz: Verwenden Sie die UI-Komponenten für einheitliches Design
2. Accessibility: Nutzen Sie aria_label und andere Accessibility-Attribute
3. Performance: Laden Sie JavaScript-Utilities nur bei Bedarf
4. Responsive: Alle Komponenten sind responsive-ready
5. Dark Mode: Alle Komponenten unterstützen automatisch Dark/Light Mode

Troubleshooting

Komponenten werden nicht angezeigt

• Prüfen Sie, ob register_template_helpers(app) in init_app() aufgerufen wird
• Stellen Sie sicher, dass Tailwind CSS kompiliert wurde

JavaScript-Funktionen nicht verfügbar

• Laden Sie ui-components.js in Ihrem Template
• Prüfen Sie die Browser-Konsole auf Fehler

Styling-Probleme

• Stellen Sie sicher, dass die CSS-Datei geladen wird
• Prüfen Sie, ob Custom-CSS die Komponenten überschreibt