421 lines
9.9 KiB
Markdown
421 lines
9.9 KiB
Markdown
# 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:**
|
|
```jinja2
|
|
{{ 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:**
|
|
```jinja2
|
|
{{ 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:**
|
|
```jinja2
|
|
{{ 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:**
|
|
```jinja2
|
|
{{ 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:**
|
|
```jinja2
|
|
{{ 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:**
|
|
```jinja2
|
|
{{ 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:**
|
|
```jinja2
|
|
{% 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:**
|
|
```jinja2
|
|
{{ 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:**
|
|
```jinja2
|
|
{{ 30|duration }} <!-- 30 Min -->
|
|
{{ 90|duration }} <!-- 1 Std 30 Min -->
|
|
{{ 120|duration }} <!-- 2 Std -->
|
|
```
|
|
|
|
#### `json`
|
|
|
|
Enkodiert Python-Daten als JSON für JavaScript.
|
|
|
|
**Beispiele:**
|
|
```jinja2
|
|
<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:**
|
|
```jinja2
|
|
{{ 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
|
|
|
|
```javascript
|
|
// Toast anzeigen
|
|
MYP.Toast.show('Nachricht', 'success'); // success, error, warning, info
|
|
|
|
// Toast ausblenden
|
|
MYP.Toast.hide();
|
|
```
|
|
|
|
### Modal-Steuerung
|
|
|
|
```javascript
|
|
// Modal öffnen
|
|
MYP.Modal.open('modal-id');
|
|
|
|
// Modal schließen
|
|
MYP.Modal.close('modal-id');
|
|
```
|
|
|
|
### Dropdown-Steuerung
|
|
|
|
```javascript
|
|
// Dropdown umschalten
|
|
MYP.Dropdown.toggle('dropdown-id');
|
|
|
|
// Dropdown schließen
|
|
MYP.Dropdown.close('dropdown-id');
|
|
```
|
|
|
|
### Loading-Anzeige
|
|
|
|
```javascript
|
|
// Loading anzeigen
|
|
MYP.Loading.show();
|
|
|
|
// Loading ausblenden
|
|
MYP.Loading.hide();
|
|
```
|
|
|
|
### Status-Helper
|
|
|
|
```javascript
|
|
// 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
|
|
|
|
```jinja2
|
|
{% 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
|
|
|
|
```jinja2
|
|
<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
|
|
|
|
```jinja2
|
|
{{ ui_button("Custom Button", "primary", classes="my-custom-class") }}
|
|
```
|
|
|
|
### Eigene HTML-Attribute
|
|
|
|
```jinja2
|
|
{{ ui_button("Button", "primary", data_id="123", aria_label="Speichern") }}
|
|
```
|
|
|
|
### Eigene Icons verwenden
|
|
|
|
```jinja2
|
|
{% 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 |