¶ Custom CSS Loader
¶ Inhaltsverzeichnis
¶ Überblick
Das Custom CSS Loader Plugin lädt automatisch benutzerdefinierte CSS-Dateien aus assets/custom/css/ für osTickets Staff Panel und Client Portal basierend auf Dateinamen-Mustern.
Perfekt für Teams, die das Erscheinungsbild von osTicket anpassen möchten, ohne Core-Dateien zu modifizieren oder komplexe Theme-Systeme zu verwalten.
Was dieses Plugin unverzichtbar macht:
- ❌ Standard-osTicket hat begrenzte Styling-Optionen → Schwer, Corporate Branding umzusetzen
- ❌ Core-Datei-Modifikationen gehen bei Updates verloren
- ❌ Manuelle CSS-Einbindung erfordert PHP-Kenntnisse
- ✅ Plugin lädt CSS-Dateien automatisch → Einfach Dateien ablegen und sie funktionieren
¶ Hauptfunktionen
- ✅ Automatisches CSS-Laden - CSS-Dateien in
assets/custom/css/ablegen und sie werden automatisch geladen - ✅ Kontext-bewusst - Dateien mit
staffwerden im Admin Panel geladen, Dateien mitclientim Client Portal - ✅ Cache-Busting - Automatischer
?v=<timestamp>Parameter stellt sicher, dass Browser aktualisiertes CSS laden - ✅ Keine Konfiguration nötig - Einfach CSS-Dateien ablegen und sie funktionieren
- ✅ Demo-Dateien inklusive - Beispiel-CSS-Dateien zum Einstieg
- ✅ Keine Core-Modifikationen - Verwendet osTickets Output-Buffering für die Einbindung
- ✅ Security-gehärtet - Path-Traversal-Schutz, Dateinamen-Validierung, XSS-Schutz
¶ Anwendungsfälle
- Corporate Branding - osTickets Farben und Layout an das Design-System deines Unternehmens anpassen
- Breites Layout - Den Standard-960px-Container für moderne Breitbild-Monitore erweitern
- Benutzerdefinierte Farbschemata - Einheitliche Farben im Staff Panel oder Client Portal
- Barrierefreiheit - Kontrastreiche Stile oder größere Schriften hinzufügen
- Umgebungs-spezifisches Styling - Verschiedene Farben für Produktion vs. Staging-Server
¶ Anforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| osTicket | 1.17+ | Verwendet Output-Buffering für CSS-Einbindung |
| PHP | 8.1+ | Erforderlich für readonly-Klassen und modernes Type-System |
¶ Installation
¶ Schritt 1: Plugin-Dateien installieren
¶ Methode 1: ZIP-Download (Empfohlen)
- Neueste Version von Releases herunterladen
- ZIP-Datei entpacken
custom-css-loaderOrdner nach/include/plugins/auf deinem osTicket-Server hochladen
Finaler Pfad: /pfad/zu/osticket/include/plugins/custom-css-loader/
¶ Methode 2: Git Repository
cd /pfad/zu/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-custom-css-loader.git custom-css-loader
¶ Schritt 2: Plugin in osTicket aktivieren
- Im osTicket Admin Panel einloggen
- Navigiere zu: Admin Panel → Verwalten → Plugins
- Klicke auf Neues Plugin hinzufügen
- Wähle Custom CSS Loader und klicke Installieren
- Klicke Aktivieren
Das Plugin erstellt automatisch das CSS-Verzeichnis (assets/custom/css/) und kopiert Demo-Dateien beim ersten Aktivieren.
¶ Schritt 3: CSS-Dateien hinzufügen
- Navigiere zu
<osticket-root>/assets/custom/css/ - Erstelle oder kopiere CSS-Dateien mit passender Benennung:
- Dateien mit
staff→ Admin Panel - Dateien mit
client→ Client Portal
- Dateien mit
- osTicket neu laden - deine Styles sind aktiv!
¶ Konfiguration
¶ Verfügbare Einstellungen
Navigiere zu Admin Panel → Verwalten → Plugins → Custom CSS Loader → Konfigurieren
| Einstellung | Beschreibung | Standard |
|---|---|---|
| CSS-Laden aktivieren | CSS-Laden ein-/ausschalten | AN |
Das Plugin erfordert minimale Konfiguration - einfach aktivieren und CSS-Dateien hinzufügen.
¶ Verwendung
¶ Verzeichnisstruktur
Lege deine CSS-Dateien hier ab:
<osticket-root>/assets/custom/css/
¶ Dateinamen-Muster
| Muster | Wo es geladen wird | Beispiele |
|---|---|---|
*staff* |
Admin Panel (Staff) | custom-staff.css, wide-layout-staff.css |
*client* |
Client Portal | custom-client.css, branding-client.css |
Hinweis: Dateien ohne staff oder client im Namen werden ignoriert.
Sicherheitshinweis: Dateinamen dürfen nur alphanumerische Zeichen, Bindestriche und Unterstriche enthalten (z.B. my-staff-theme.css). Dateien mit Sonderzeichen werden aus Sicherheitsgründen blockiert.
¶ Demo-Dateien
Das Plugin enthält Demo-CSS-Dateien in assets/demo/ mit kommentierten Beispielen:
| Demo-Datei | Zweck |
|---|---|
custom-staff.css |
Grundlegende Admin Panel Styling-Beispiele |
custom-client.css |
Grundlegende Client Portal Styling-Beispiele |
wide-layout-staff.css |
Container auf 95% Breite erweitern (max 1800px) |
Kopiere die gewünschten Demo-Dateien nach <osticket-root>/assets/custom/css/ und passe sie an.
¶ Beispiel: Breites Layout für Staff Panel
Erstelle assets/custom/css/wide-layout-staff.css:
/* Container von 960px auf 95% Breite erweitern */
#container {
width: 95%;
max-width: 1800px;
margin: 0 auto 20px auto;
}
/* Blauer Header mit Corporate Branding */
#header {
background-color: #1E3A5F !important;
background-image: none !important;
}
/* Weißes Logo und Links */
#header a,
#header #info {
color: #FFFFFF !important;
}
¶ Beispiel: Benutzerdefinierte Farben für Client Portal
Erstelle assets/custom/css/branding-client.css:
/* Primäre Button-Farbe */
.btn-primary,
button.blue {
background-color: #3498db !important;
border-color: #3498db !important;
}
/* Link-Farbe */
a {
color: #2980b9 !important;
}
¶ Mehrere CSS-Dateien
Du kannst mehrere CSS-Dateien für jeden Kontext haben. Sie werden in alphabetischer Reihenfolge geladen:
assets/custom/css/
├── 01-variables-staff.css # Zuerst geladen (Staff Panel)
├── 02-layout-staff.css # Zweitens geladen (Staff Panel)
├── 03-branding-staff.css # Drittens geladen (Staff Panel)
├── custom-client.css # Client Portal
└── wide-layout-staff.css # Staff Panel
¶ Problembehandlung
¶ Problem: CSS wird nicht geladen
Symptome:
- Benutzerdefinierte Styles werden nicht angewendet
- Keine CSS-Link-Tags im Seitenquelltext
Prüfen:
-
Plugin aktiviert?
- Admin Panel → Verwalten → Plugins → "Custom CSS Loader" → Status: Aktiviert
-
Plugin konfiguriert?
- Klicke Konfigurieren → "CSS-Laden aktivieren": AN
-
Dateien im richtigen Verzeichnis?
ls -la /pfad/zu/osticket/assets/custom/css/ -
Dateiname enthält
staffoderclient?- ✅
custom-staff.css→ Wird im Admin Panel geladen - ✅
my-client-theme.css→ Wird im Client Portal geladen - ❌
custom.css→ Ignoriert (kein Muster-Match)
- ✅
-
Dateiname gültig?
- ✅
my-staff-theme.css→ Gültig (alphanumerisch, Bindestriche, Unterstriche) - ❌
staff theme.css→ Blockiert (enthält Leerzeichen) - ❌
.hidden-staff.css→ Blockiert (beginnt mit Punkt)
- ✅
-
Datei lesbar?
chmod 644 /pfad/zu/osticket/assets/custom/css/*.css
¶ Problem: CSS wird geladen, aber Styles werden nicht angewendet
Symptome:
- CSS-Datei wird geladen (sichtbar im Seitenquelltext)
- Styles sind nicht sichtbar
Prüfen:
-
CSS-Syntaxfehler?
- Browser-DevTools öffnen (F12) → Konsole-Tab
- Nach CSS-Parsing-Fehlern suchen
-
Spezifitätsprobleme?
- osTicket-Styles haben möglicherweise höhere Spezifität
!importantverwenden wo nötig:
#header { background-color: #1E3A5F !important; } -
Browser-Cache?
- Hard Refresh:
Strg+F5(Windows) oderCmd+Shift+R(Mac) - Das Plugin fügt
?v=<timestamp>für Cache-Busting hinzu, aber der Browser kann noch cachen
- Hard Refresh:
¶ Problem: CSS-Verzeichnis wird nicht erstellt
Symptome:
assets/custom/css/existiert nicht nach Plugin-Aktivierung
Lösung:
Manuell erstellen:
mkdir -p /pfad/zu/osticket/assets/custom/css
chmod 755 /pfad/zu/osticket/assets/custom/css
¶ Problem: Demo-Dateien werden nicht kopiert
Symptome:
assets/custom/css/existiert aber ist leer nach Plugin-Aktivierung
Prüfen:
- Demo-Dateien werden nur kopiert, wenn das Verzeichnis leer ist
- Wenn dort bereits Dateien sind, werden Demo-Dateien nicht kopiert
Lösung:
cp /pfad/zu/osticket/include/plugins/custom-css-loader/assets/demo/*.css \
/pfad/zu/osticket/assets/custom/css/
¶ Technische Details
¶ Architektur
Plugin-Struktur (v2.0.0+):
custom-css-loader/
├── plugin.php # Plugin-Metadaten
├── class.CustomCssLoaderPlugin.php # Haupt-Plugin-Klasse
├── config.php # Plugin-Konfiguration
├── src/ # Moderne PHP 8.1+ Architektur
│ ├── Context/ # Kontext-Erkennung (Staff/Client)
│ ├── Discovery/ # CSS-Datei-Erkennung
│ ├── Rendering/ # HTML-Link-Tag-Rendering
│ ├── Injection/ # Output-Buffer-Injection
│ └── CssLoaderOrchestrator.php # Haupt-Orchestrator
├── assets/demo/ # Demo-CSS-Dateien
└── tests/ # PHPUnit-Tests (73 Tests)
¶ Sicherheitsfunktionen
Das Plugin enthält umfassende Sicherheitsmaßnahmen:
- Path-Traversal-Schutz - Validiert kanonische Pfade via
realpath() - Symlink-Angriffs-Schutz - Blockiert Symlinks, die außerhalb des CSS-Verzeichnisses zeigen
- Dateinamen-Validierung - Allowlist-Pattern: nur alphanumerisch, Bindestriche, Unterstriche
- XSS-Schutz - Alle URLs werden mit
htmlspecialchars()escaped - Defense-in-Depth - Mehrere Validierungsebenen
¶ CSS-Einbindungsmethode
Das Plugin verwendet Output-Buffering für die CSS-Einbindung:
- Output-Buffer-Callback wird bei Plugin-Datei-Include registriert
- Buffer erfasst vollständigen HTML-Output
- CSS
<link>Tags werden vor</head>eingefügt - Keine Modifikation von osTicket Core-Dateien
¶ Kontext-Erkennung
| Kontext | Erkennungsmethode |
|---|---|
| Staff Panel | OSTSCPINC Konstante ODER /scp/ im URL-Pfad |
| Client Portal | OSTCLIENTINC Konstante ODER .php Datei (nicht /scp/ oder /api/) |
| API | /api/ im URL-Pfad → Kein CSS eingefügt |
| CLI | Kein SCRIPT_NAME → Kein CSS eingefügt |
¶ Cache-Busting
Jede CSS-Datei bekommt einen Versions-Parameter basierend auf der Datei-Änderungszeit:
<link rel="stylesheet" href="/assets/custom/css/wide-layout-staff.css?v=1702483200">
¶ FAQ
¶ Allgemeine Fragen
F: Modifiziert dieses Plugin osTicket Core-Dateien?
A: Nein! Das Plugin verwendet Output-Buffering für die CSS-Einbindung. Keine Core-Dateien werden modifiziert.
F: Kann ich das Plugin temporär deaktivieren ohne meine CSS-Dateien zu verlieren?
A: Ja! Einfach das Plugin im Admin Panel Deaktivieren. Deine CSS-Dateien bleiben in assets/custom/css/.
F: Funktioniert das mit osTicket 1.17 oder älter?
A: Ja, das Plugin ist für osTicket 1.17+ konzipiert. Es verwendet Output-Buffering, das mit älteren Versionen kompatibel ist.
F: Kann ich mehrere CSS-Dateien haben?
A: Ja! Alle CSS-Dateien, die dem Muster entsprechen (*staff* oder *client*), werden geladen. Sie werden in alphabetischer Reihenfolge geladen.
¶ Kompatibilität
F: Ist es mit PHP 8.x kompatibel?
A: Ja! Das Plugin erfordert PHP 8.1 oder höher. Es verwendet moderne PHP-Features wie readonly-Klassen und Union-Types.
F: Funktioniert das mit benutzerdefinierten osTicket-Themes?
A: Ja! Das Plugin fügt CSS-Dateien einfach nach dem Theme-CSS hinzu. Deine benutzerdefinierten Styles können Theme-Styles überschreiben.
F: Kann ich das mit anderen Plugins verwenden?
A: Ja! Das Plugin verwendet eine nicht-invasive Einbindungsmethode. Es sollte neben jedem anderen Plugin funktionieren.
¶ Verhalten
F: Was passiert, wenn ich eine Datei ohne staff oder client im Namen ablege?
A: Die Datei wird ignoriert. Nur Dateien, die den Mustern entsprechen, werden geladen.
F: Beeinflusst das API-Antworten?
A: Nein, CSS wird für API-Anfragen nicht eingefügt.
F: Warum werden meine Styles nicht angewendet?
A: Höchstwahrscheinlich ein CSS-Spezifitätsproblem. osTickets Standard-Styles könnten deine überschreiben. Verwende !important, um sicherzustellen, dass deine Styles Vorrang haben.
F: Wo soll ich das CSS-Verzeichnis anlegen?
A: CSS-Dateien kommen nach <osticket-root>/assets/custom/css/, nicht in den Plugin-Ordner. Das stellt sicher, dass dein benutzerdefiniertes CSS Plugin-Updates überlebt.
¶ Lizenz
Dieses Plugin ist unter der GNU General Public License v2 veröffentlicht, kompatibel mit osTicket Core.
Siehe LICENSE für Details.
¶ Support
Bei Fragen oder Problemen erstelle bitte ein Issue auf GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-custom-css-loader/issues
Bei Problemberichten bitte angeben:
- osTicket-Version (Admin Panel → Einstellungen → Über)
- PHP-Version (
php -v) - Plugin-Version
- Browser-Konsolen-Fehler (F12 → Konsole)
- CSS-Datei-Inhalt (wenn relevant)
¶ Mitwirken
Entwickelt von Markus Michalski
Beiträge willkommen!
- Repository forken
- Feature-Branch erstellen
- Pull Request einreichen
¶ Changelog
Siehe CHANGELOG.md für Versionshistorie.