¶ Priority Icons
¶ Inhaltsverzeichnis
- Überblick
- Hauptfunktionen
- Anwendungsfälle
- Systemanforderungen
- Installation
- Konfigurations-Optionen
- Funktionsweise
- Signal Hooks
- Fehlerbehebung
- Technische Details
- FAQ
- Lizenz
- Support
¶ Überblick
Ersetzt die Prioritäts-Textlabels (Emergency, High, Normal, Low) im osTicket Staff Panel durch visuelle farbcodierte Icons. Das Plugin arbeitet rein clientseitig per DOM-Manipulation und benötigt keine Änderungen an Core-Dateien.
Ohne dieses Plugin: Prioritäten werden als reiner Text angezeigt - in langen Ticket-Listen müssen Agents jeden Eintrag lesen, um dringende Tickets zu erkennen.
Mit diesem Plugin: Farbcodierte Icons ersetzen den Text - Emergency-Tickets pulsieren rot, High-Tickets leuchten orange. Prioritäten sind auf einen Blick erkennbar.
¶ Hauptfunktionen
- Farbcodierte Icons - Jede Priorität erhält einen eigenen farbigen Kreis-Indikator
- Konfigurierbare Farben - Alle Prioritätsfarben über Admin Panel anpassbar
- 3 Icon-Stile - Gefüllter Kreis, Badge mit Text oder minimaler Punkt
- PJAX-Unterstützung - Icons werden nach dynamischer Navigation automatisch neu angewandt
- Emergency-Pulse-Animation - Pulsierende Animation für dringende Tickets
- CSS-Tooltips - Prioritätsname wird beim Hover angezeigt
- WCAG-Barrierefreiheit - Screen-Reader-Text,
prefers-reduced-motionUnterstützung - Dark-Mode - Automatische Tooltip-Farbanpassung
- Druck-Optimierung - Farben bleiben im Druck erhalten, Animationen werden deaktiviert
- Mehrsprachig - Unterstützt englische und deutsche Prioritätsnamen
- Keine Core-Modifikationen - Output-Buffer-basierte Asset-Injection
¶ Anwendungsfälle
Support-Teams mit hohem Ticket-Aufkommen:
Teams mit hunderten offenen Tickets können Emergency- und High-Priority-Tickets sofort visuell identifizieren, ohne die Textlabels lesen zu müssen.
Mehrsprachige Helpdesks:
Das Plugin erkennt sowohl englische (Emergency, High, Normal, Low) als auch deutsche (Notfall, Hoch, Normal, Niedrig) Prioritätsnamen - ideal für Teams mit gemischter Sprach-Konfiguration.
Barrierefreie Arbeitsumgebungen:
Screen-Reader-Text bleibt erhalten, aria-label Attribute informieren assistive Technologien. Bei prefers-reduced-motion werden Animationen automatisch deaktiviert.
Teams mit Farbkodierungs-Standards:
Die Admin-konfigurierbaren Farben erlauben die Anpassung an firmeninterne Farbschemata - etwa wenn Rot für kritische Tickets in einer bestimmten Farbnuance definiert ist.
Multi-Monitor / Dashboard-Setups:
Auf großen Bildschirmen oder Dashboard-Monitoren sind farbige Icons deutlich schneller erkennbar als Textlabels.
¶ Systemanforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| osTicket | 1.18.x | Getestet mit 1.18.x |
| PHP | 8.1+ | Strict Types, Union Types |
| jQuery | Beliebig | In osTicket standardmäßig enthalten (für PJAX-Support) |
| Browser | Modern | ES6+, CSS Custom Properties erforderlich |
¶ Installation
- Lade das neueste Release von GitHub Releases herunter
- Entpacke die ZIP-Datei
- Lade den
priority-icons-Ordner nach/include/plugins/auf deinem osTicket-Server hoch
Finaler Pfad: /pfad/zu/osticket/include/plugins/priority-icons/
cd /pfad/zu/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-priority-icons.git priority-icons
¶ Plugin aktivieren
- Melde dich im osTicket Admin Panel an
- Navigiere zu: Admin Panel -> Verwalten -> Plugins
- Finde "Priority Icons" in der Liste
- Klicke auf "Aktivieren"
Das Plugin erstellt automatisch eine Singleton-Instanz und beginnt sofort zu arbeiten.
Tipp: Nach der Aktivierung ist keine weitere Konfiguration nötig - das Plugin funktioniert sofort mit den Standard-Farbwerten.
¶ Plugin konfigurieren (Optional)
- Klicke auf "Instances" neben "Priority Icons"
- Klicke auf die Instanz und dann auf "Config"
- Passe Einstellungen an (siehe Konfigurations-Optionen)
¶ Konfigurations-Optionen
| Einstellung | Beschreibung | Standard |
|---|---|---|
| Priority Icons aktivieren | Plugin global aktivieren/deaktivieren | An |
| Tooltips anzeigen | Prioritätsname beim Hover anzeigen | An |
| Icon-Stil | Visueller Stil: Gefüllter Kreis, Badge, Punkt | Gefüllter Kreis |
| Emergency-Farbe | Hex-Farbcode für Emergency-Priorität | #dc3545 (Rot) |
| High-Farbe | Hex-Farbcode für High-Priorität | #fd7e14 (Orange) |
| Normal-Farbe | Hex-Farbcode für Normal-Priorität | #ffc107 (Gelb) |
| Low-Farbe | Hex-Farbcode für Low-Priorität | #28a745 (Grün) |
¶ Standard-Farbschema
Das Farbschema ist Bootstrap-inspiriert und folgt dem Ampel-Prinzip:
| Priorität | Farbe | Hex | Verhalten |
|---|---|---|---|
| Emergency | Rot | #dc3545 |
Pulsierender Glow-Effekt |
| High | Orange | #fd7e14 |
Statischer Kreis |
| Normal | Gelb | #ffc107 |
Statischer Kreis |
| Low | Grün | #28a745 |
Statischer Kreis |
¶ CSS Custom Properties
Die Icon-Darstellung kann auch per CSS überschrieben werden, ohne die Plugin-Konfiguration zu ändern:
:root {
--priority-icon-size: 16px; /* Standard: 12px */
--priority-icon-spacing: 0.375rem;
--priority-tooltip-bg: #212529;
--priority-tooltip-color: #fff;
--priority-transition-duration: 150ms;
}
¶ Funktionsweise
¶ Architektur-Diagramm
¶ Icon-Ersetzung
Das Plugin scannt nach dem Laden der Seite gezielt folgende Bereiche nach Prioritäts-Textlabels:
- Ticket-Queue-Tabelle (
table.list.queue.tickets) - Ticket-Detail-Info (
.ticket_info,.ticket-info) - Ticket-Status-Bereich (
#ticket-status) - PJAX-Container (
.pjax-container)
Gefundene Textlabels werden durch farbcodierte Icons ersetzt. Der Original-Text bleibt als Screen-Reader-Text erhalten.
¶ Unterstützte Prioritätsnamen
| Englisch | Deutsch |
|---|---|
| Emergency | Notfall |
| High | Hoch |
| Normal | Normal |
| Low | Niedrig |
¶ Icon-Stile
Gefüllter Kreis (Standard):
- 12px Durchmesser
- Hover-Effekt: 1.2x Scale + Glow
- Emergency: Pulsierende Animation
Badge:
- Farbiger Hintergrund mit weißem Text
- Zeigt Prioritätsname als Label
Punkt:
- 8px minimaler Indikator
- Ohne Tooltip
¶ Signal Hooks
Das Plugin nutzt keine osTicket Signals für die Asset-Injection (siehe Technische Details für die Begründung). Stattdessen wird der Output-Buffer-Callback verwendet.
| Mechanismus | Methode | Zweck |
|---|---|---|
ob_start() Callback |
injectAssetsIntoOutput() |
CSS + JS vor </head> injizieren |
enable() Override |
addInstance() |
Singleton-Instanz automatisch erstellen |
bootstrap() Override |
ob_start() starten |
Asset-Injection initialisieren |
Warum keine Signals? Die osTicket-Signals
apps.scpundapps.adminfeuern nur auf der Apps-Seite, nicht auf regulären Seiten wie der Ticket-Liste.$ost->addExtraHeader()funktioniert ebenfalls nicht, daglobal $ostwährendbootstrap()nochNULList.
¶ Fehlerbehebung
¶ Problem: Icons werden nicht angezeigt
Symptome:
- Prioritäts-Textlabels bleiben unverändert
- Keine CSS/JS-Fehler in der Browser-Konsole
Prüfung:
-
Plugin aktiviert?
- Admin Panel -> Plugins -> Priority Icons muss "Enabled" zeigen
- Eine Instanz muss existieren und aktiv sein
-
Seitenquelltext prüfen:
- Strg+U -> Nach
data-plugin="priority-icons"suchen - Es müssen
<style>und<script>Tags mit diesem Attribut vorhanden sein
- Strg+U -> Nach
-
Browser-Konsole prüfen:
// Prüfen ob Config geladen wurde: console.log(window.PriorityIconsConfig); -
Error-Log prüfen:
tail -f /pfad/zu/osticket/include/ost-errors.log
Lösung:
Wenn data-plugin="priority-icons" nicht im Quelltext erscheint, ist die Plugin-Instanz nicht aktiv. Plugin deaktivieren und erneut aktivieren - die Singleton-Instanz wird automatisch erstellt.
¶ Problem: Assets werden nicht injiziert
Symptome:
- Kein
data-plugin="priority-icons"im Seitenquelltext
Prüfung:
- Admin Panel -> Plugins -> Priority Icons -> Instances
- Prüfen, ob eine Instanz existiert
Lösung:
Plugin deaktivieren und erneut aktivieren (erstellt automatisch Singleton-Instanz).
¶ Problem: Icons erscheinen, aber nicht zentriert
Symptome:
- Icons sind oben statt mittig in der Tabellenzelle ausgerichtet
Prüfung:
Plugin-Version prüfen (muss >= 1.0.2 sein).
Lösung:
Plugin auf Version 1.0.2+ aktualisieren - enthält CSS-Fix für vertikale Zentrierung in Tabellenzellen.
¶ Problem: Prioritätsnamen werden nicht erkannt
Symptome:
- Bestimmte Prioritätsnamen werden nicht durch Icons ersetzt
Prüfung:
- Das Plugin erkennt nur exakte Übereinstimmungen: Emergency, High, Normal, Low, Notfall, Hoch, Niedrig
- Der Text muss der einzige Inhalt des Elements sein
Lösung:
Benutzerdefinierte Prioritätsnamen erfordern eine Anpassung der $priorityMap in class.PriorityIconsPlugin.php.
¶ Technische Details
¶ Plugin-Struktur
priority-icons/
+-- plugin.php # Plugin-Metadaten (v1.0.3)
+-- class.PriorityIconsPlugin.php # Haupt-Plugin-Klasse
+-- config.php # Admin-Konfiguration
+-- composer.json # Abhängigkeiten und Scripts
+-- phpunit.xml # PHPUnit-Konfiguration
+-- assets/
| +-- .htaccess # Security + Caching
| +-- priority-icons.css # Icon-Styles + Animationen
| +-- priority-icons.js # DOM-Manipulation + PJAX
+-- tests/
| +-- bootstrap.php # Mock osTicket Classes
| +-- Unit/
| +-- PriorityIconsPluginTest.php # 44 Tests
| +-- PriorityIconsConfigTest.php # 53 Tests
+-- docs/
+-- ARCHITECTURE.md # Technische Architektur-Dokumentation
+-- CODE_REVIEW.md # Professionelle Code-Review (9.2/10)
¶ Asset-Injection
Das Plugin nutzt Output-Buffer-Injection (ob_start() Callback), um CSS und JavaScript inline vor </head> zu injizieren:
public function bootstrap(): void
{
if ($this->isAjaxRequest()) {
return;
}
ob_start([$this, 'injectAssetsIntoOutput']);
}
Warum ob_start() statt anderer Methoden?
| Methode | Problem |
|---|---|
Signal..connect('apps.scp') |
Signal feuert nur in scp/apps/dispatcher.php (Apps-Tab), nicht auf normalen Seiten |
$ost->addExtraHeader() |
global $ost ist NULL während bootstrap(), weil PluginManager..bootstrap() innerhalb von osTicket..start() läuft |
| Externe CSS/JS-Dateien | include/.htaccess enthält Deny from all, blockiert HTTP-Zugriff auf Plugin-Assets |
ob_start() Callback |
Funktioniert zuverlässig, bewährtes Pattern |
Injection-Reihenfolge:
- Inline
<style>mit CSS - Inline
<script>mit PHP-zu-JS Konfiguration (window.PriorityIconsConfig) - Inline
<script>mit JavaScript-Logik
¶ JavaScript-Architektur
DOM-Traversal:
- Nutzt
TreeWalkerAPI für effizientes Durchlaufen des DOM - Scannt nur relevante Container (nicht den gesamten DOM)
- Quick-Check: Textlänge 3-10 Zeichen vor Regex-Prüfung
- Sammelt Knoten vor der Modifikation (vermeidet Probleme bei DOM-Änderung während Walk)
PJAX-Unterstützung:
- Registriert
pjax:endEvent-Handler via jQuery - MutationObserver als Backup für dynamische Inhalte
- Debounced Replacement (100ms) verhindert übermäßige Aufrufe
Performance:
- Verarbeitete Elemente werden mit
data-priority-iconmarkiert (keine Doppelverarbeitung) - Kein externer HTTP-Request für Assets (alles inline)
deferAttribut für non-blocking Script-Load
¶ Sicherheit
-
XSS-Schutz:
- PHP-zu-JS Konfiguration nutzt
JSON_HEX_TAG | JSON_HEX_APOS(verhindert</script>-Injection) - Icon-Elemente werden per DOM-API erstellt (nicht per
innerHTML)
- PHP-zu-JS Konfiguration nutzt
-
Double-Injection-Schutz:
- Prüft auf
data-plugin="priority-icons"im Output bevor Injection
- Prüft auf
-
AJAX-Skip:
- Überspringt AJAX-Requests (kein vollständiges HTML zum Injizieren)
-
Asset-Schutz (.htaccess):
- PHP-Ausführung in
/assets/blockiert - Browser-Caching: 1 Woche + gzip-Kompression
- PHP-Ausführung in
¶ Barrierefreiheit (WCAG)
- Screen-Reader: Prioritätstext bleibt als
.sr-onlyElement erhalten aria-label: Jedes Icon hat einaria-label="Priority: {name}"Attributcursor: help: Zeigt an, dass Tooltip verfügbar istprefers-reduced-motion: Deaktiviert Pulse-Animation und Transitions- Tooltip: CSS-only Tooltip zeigt Prioritätsname beim Hover
- Dark Mode: Automatische Tooltip-Farbanpassung
¶ Tests
97 Tests (PHPUnit 11):
- 44 Tests für die Plugin-Hauptklasse (
PriorityIconsPluginTest) - 53 Tests für die Admin-Konfiguration (
PriorityIconsConfigTest)
composer test # Tests ausführen
composer analyse # PHPStan Static Analysis
¶ FAQ
¶ Allgemeine Fragen
F: Funktioniert das Plugin im Client-Portal?
A: Das Plugin ist für das Staff Panel konzipiert. Im Client-Portal werden Prioritäten in der Regel nicht angezeigt, daher hat das Plugin dort keinen Effekt.
F: Kann ich benutzerdefinierte Prioritätsnamen verwenden?
A: Aktuell werden nur die Standard-Prioritätsnamen (Emergency, High, Normal, Low) sowie deren deutsche Übersetzungen (Notfall, Hoch, Niedrig) unterstützt. Benutzerdefinierte Namen erfordern eine Anpassung der $priorityMap in class.PriorityIconsPlugin.php.
F: Was passiert, wenn ich das Plugin deaktiviere?
A: Die originalen Prioritäts-Textlabels werden sofort wieder angezeigt. Keine Daten werden verändert - das Plugin arbeitet rein clientseitig.
F: Ist das Plugin kompatibel mit anderen osTicket-Plugins?
A: Ja. Das Plugin modifiziert keine Core-Dateien und nutzt einen eigenen Namespace (data-plugin="priority-icons"). Konflikte sind unwahrscheinlich, solange kein anderes Plugin die gleichen DOM-Elemente manipuliert.
¶ Technische Fragen
F: Warum werden Assets inline statt als externe Dateien geladen?
A: osTickets include/.htaccess enthält Deny from all, was HTTP-Zugriff auf alle Dateien im include/-Verzeichnis blockiert. Inline-Injection umgeht dieses Problem, ohne Core-Dateien zu ändern.
F: Warum nutzt das Plugin ob_start() statt Signal..connect()?
A: Die osTicket-Signals apps.scp und apps.admin feuern nur auf der Apps-Seite - nicht auf normalen Seiten wie der Ticket-Liste. $ost->addExtraHeader() funktioniert ebenfalls nicht, da global $ost während bootstrap() noch NULL ist. ob_start() mit Callback ist das einzige zuverlässige Pattern.
F: Funktioniert das Plugin mit NGINX?
A: Ja. Da alle Assets inline injiziert werden, gibt es keine externen Datei-Requests die von Webserver-Konfigurationen blockiert werden könnten.
F: Wie ändere ich die Icon-Größe?
A: Die Icon-Größe wird über CSS Custom Properties gesteuert:
:root {
--priority-icon-size: 16px; /* Standard: 12px */
}
¶ Lizenz
Dieses Plugin wird unter der GNU General Public License v2 veröffentlicht, kompatibel mit osTicket Core.
Details siehe LICENSE.
¶ Support
Für Fragen oder Probleme erstelle bitte ein Issue auf GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-priority-icons/issues
Beim Melden von Problemen bitte angeben:
- osTicket-Version (Admin Panel -> Einstellungen -> Über)
- PHP-Version (
php -v) - Plugin-Version (derzeit 1.0.3)
- Browser-Konsolen-Fehler (F12 -> Console)
- Seitenquelltext-Auszug (Strg+U -> nach "priority-icons" suchen)
¶ Mitwirken
Entwickelt von Markus Michalski
Beiträge willkommen!
- Repository forken
- Feature-Branch erstellen
- Pull Request einreichen
¶ Changelog
Siehe CHANGELOG.md für Versionshistorie.