¶ Priority Icons
¶ Table of Contents
- Overview
- Key Features
- Use Cases
- Requirements
- Installation
- Configuration
- How It Works
- Signal Hooks
- Troubleshooting
- Technical Details
- FAQ
- License
- Support
¶ Overview
The Priority Icons Plugin replaces priority text labels (Emergency, High, Normal, Low) in osTicket's Staff Panel with visual color-coded icons. The plugin works entirely client-side via DOM manipulation and requires no core file modifications.
Without this plugin: Priorities are displayed as plain text - in long ticket lists, agents must read each entry to identify urgent tickets.
With this plugin: Color-coded icons replace the text - emergency tickets pulse red, high-priority tickets glow orange. Priorities are recognizable at a glance.
¶ Key Features
- Color-coded icons - Each priority gets a distinct colored circle indicator
- Configurable colors - All priority colors adjustable via Admin Panel
- 3 icon styles - Filled circle, badge with text, or minimal dot
- PJAX support - Icons are automatically re-applied after dynamic navigation
- Emergency pulse animation - Pulsing glow effect for urgent tickets
- CSS-only tooltips - Priority name shown on hover
- WCAG accessibility - Screen-reader text,
prefers-reduced-motionsupport - Dark mode - Automatic tooltip color adaptation
- Print optimization - Colors preserved in print, animations disabled
- Multilingual - Supports English and German priority names
- No core modifications - Output buffer-based asset injection
¶ Use Cases
High-volume support teams:
Teams with hundreds of open tickets can instantly identify emergency and high-priority tickets visually, without reading the text labels.
Multilingual helpdesks:
The plugin recognizes both English (Emergency, High, Normal, Low) and German (Notfall, Hoch, Normal, Niedrig) priority names - ideal for teams with mixed language configurations.
Accessible work environments:
Screen-reader text is preserved, aria-label attributes inform assistive technologies. Animations are automatically disabled when prefers-reduced-motion is set.
Teams with color-coding standards:
Admin-configurable colors allow adaptation to corporate color schemes - for example when red for critical tickets is defined in a specific shade.
Multi-monitor / Dashboard setups:
On large screens or dashboard monitors, colored icons are significantly faster to recognize than text labels.
¶ Requirements
| Component | Version | Note |
|---|---|---|
| osTicket | 1.18.x | Tested with 1.18.x |
| PHP | 8.1+ | Strict types, union types |
| jQuery | Any | Included in osTicket (for PJAX support) |
| Browser | Modern | ES6+, CSS Custom Properties required |
¶ Installation
- Visit GitHub Releases
- Download the latest release ZIP
- Extract and upload the
priority-iconsfolder to/include/plugins/on your osTicket server
Final path: /path/to/osticket/include/plugins/priority-icons/
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-priority-icons.git priority-icons
¶ Enable Plugin
- Login to osTicket Admin Panel
- Navigate to: Admin Panel -> Manage -> Plugins
- Find "Priority Icons" in the plugin list
- Click "Enable"
The plugin automatically creates a singleton instance and starts working immediately.
Tip: No further configuration is needed after activation - the plugin works immediately with default color values.
¶ Configure (Optional)
- Click "Instances" next to "Priority Icons"
- Click the instance, then "Config"
- Adjust settings as needed (see Configuration)
¶ Configuration
¶ Available Settings
| Setting | Description | Default |
|---|---|---|
| Enable Priority Icons | Globally enable/disable the plugin | On |
| Show Tooltips | Display priority name on hover | On |
| Icon Style | Visual style: Filled Circle, Badge, Dot | Filled Circle |
| Emergency Color | Hex color for emergency priority | #dc3545 (Red) |
| High Color | Hex color for high priority | #fd7e14 (Orange) |
| Normal Color | Hex color for normal priority | #ffc107 (Yellow) |
| Low Color | Hex color for low priority | #28a745 (Green) |
¶ Default Color Scheme
The color scheme is Bootstrap-inspired and follows a traffic light principle:
| Priority | Color | Hex | Behavior |
|---|---|---|---|
| Emergency | Red | #dc3545 |
Pulsing glow animation |
| High | Orange | #fd7e14 |
Static circle |
| Normal | Yellow | #ffc107 |
Static circle |
| Low | Green | #28a745 |
Static circle |
¶ CSS Custom Properties
Icon rendering can also be overridden via CSS, without changing plugin configuration:
:root {
--priority-icon-size: 16px; /* Default: 12px */
--priority-icon-spacing: 0.375rem;
--priority-tooltip-bg: #212529;
--priority-tooltip-color: #fff;
--priority-transition-duration: 150ms;
}
¶ How It Works
¶ Architecture Diagram
¶ Icon Replacement
After page load, the plugin scans these specific areas for priority text labels:
- Ticket queue table (
table.list.queue.tickets) - Ticket detail info (
.ticket_info,.ticket-info) - Ticket status area (
#ticket-status) - PJAX container (
.pjax-container)
Matched text labels are replaced with color-coded icon elements. The original text is preserved as screen-reader accessible text.
¶ Supported Priority Names
| English | German |
|---|---|
| Emergency | Notfall |
| High | Hoch |
| Normal | Normal |
| Low | Niedrig |
¶ Icon Styles
Filled Circle (Default):
- 12px diameter
- Hover effect: 1.2x scale + glow
- Emergency: Pulsing animation
Badge:
- Colored background with white text
- Shows priority name as label
Dot:
- 8px minimal indicator
- No tooltip
¶ Signal Hooks
The plugin does not use osTicket Signals for asset injection (see Technical Details for the reasoning). Instead, it uses the output buffer callback approach.
| Mechanism | Method | Purpose |
|---|---|---|
ob_start() callback |
injectAssetsIntoOutput() |
Inject CSS + JS before </head> |
enable() override |
addInstance() |
Auto-create singleton instance |
bootstrap() override |
Start ob_start() |
Initialize asset injection |
Why no Signals? The osTicket signals
apps.scpandapps.adminonly fire on the Apps page, not on regular pages like the ticket list.$ost->addExtraHeader()also doesn't work becauseglobal $ostis stillNULLduringbootstrap().
¶ Troubleshooting
¶ Problem: Icons not appearing
Symptoms:
- Priority text labels remain unchanged
- No CSS/JS errors in browser console
Check:
-
Plugin enabled?
- Admin Panel -> Plugins -> Priority Icons must show "Enabled"
- An instance must exist and be active
-
Check page source:
- Ctrl+U -> Search for
data-plugin="priority-icons" - There must be
<style>and<script>tags with this attribute
- Ctrl+U -> Search for
-
Check browser console:
// Verify config is loaded: console.log(window.PriorityIconsConfig); -
Check error log:
tail -f /path/to/osticket/include/ost-errors.log
Fix:
If data-plugin="priority-icons" doesn't appear in the source, the plugin instance isn't active. Disable and re-enable the plugin - the singleton instance is created automatically.
¶ Problem: Assets not injected
Symptoms:
- No
data-plugin="priority-icons"in page source
Check:
- Admin Panel -> Plugins -> Priority Icons -> Instances
- Verify that an instance exists
Fix:
Disable and re-enable the plugin (automatically creates singleton instance).
¶ Problem: Icons appear but are not centered
Symptoms:
- Icons are top-aligned instead of vertically centered in table cells
Check:
Verify plugin version (must be >= 1.0.2).
Fix:
Update to plugin version 1.0.2+ which includes the CSS fix for vertical centering in table cells.
¶ Problem: Priority names not recognized
Symptoms:
- Certain priority names are not replaced with icons
Check:
- The plugin only matches exact strings: Emergency, High, Normal, Low, Notfall, Hoch, Niedrig
- The text must be the only content of the element
Fix:
Custom priority names require modifying the $priorityMap in class.PriorityIconsPlugin.php.
¶ Technical Details
¶ Plugin Structure
priority-icons/
+-- plugin.php # Plugin metadata (v1.0.3)
+-- class.PriorityIconsPlugin.php # Main plugin class
+-- config.php # Admin configuration
+-- composer.json # Dependencies and scripts
+-- phpunit.xml # PHPUnit configuration
+-- assets/
| +-- .htaccess # Security + caching
| +-- priority-icons.css # Icon styles + animations
| +-- priority-icons.js # DOM manipulation + PJAX
+-- tests/
| +-- bootstrap.php # Mock osTicket classes
| +-- Unit/
| +-- PriorityIconsPluginTest.php # 44 tests
| +-- PriorityIconsConfigTest.php # 53 tests
+-- docs/
+-- ARCHITECTURE.md # Technical architecture docs
+-- CODE_REVIEW.md # Professional code review (9.2/10)
¶ Asset Injection
The plugin uses output buffer injection (ob_start() callback) to inject inline CSS and JavaScript before </head>:
public function bootstrap(): void
{
if ($this->isAjaxRequest()) {
return;
}
ob_start([$this, 'injectAssetsIntoOutput']);
}
Why ob_start() instead of other methods?
| Method | Problem |
|---|---|
Signal..connect('apps.scp') |
Signal only fires in scp/apps/dispatcher.php (Apps tab), not on regular pages |
$ost->addExtraHeader() |
global $ost is NULL during bootstrap() because PluginManager..bootstrap() runs inside osTicket..start() |
| External CSS/JS files | include/.htaccess contains Deny from all, blocking HTTP access to plugin assets |
ob_start() callback |
Works reliably, proven pattern |
Injection order:
- Inline
<style>with CSS - Inline
<script>with PHP-to-JS configuration (window.PriorityIconsConfig) - Inline
<script>with JavaScript logic
¶ JavaScript Architecture
DOM Traversal:
- Uses
TreeWalkerAPI for efficient DOM walking - Scans only relevant containers (not the entire DOM)
- Quick check: Text length 3-10 characters before regex test
- Collects nodes before modification (avoids issues with DOM changes during walk)
PJAX Support:
- Registers
pjax:endevent handler via jQuery - MutationObserver as backup for dynamic content
- Debounced replacement (100ms) prevents excessive calls
Performance:
- Processed elements are marked with
data-priority-icon(no double processing) - No external HTTP requests for assets (everything inline)
deferattribute for non-blocking script load
¶ Security
-
XSS Protection:
- PHP-to-JS configuration uses
JSON_HEX_TAG | JSON_HEX_APOS(prevents</script>injection) - Icon elements are created via DOM API (not
innerHTML)
- PHP-to-JS configuration uses
-
Double-Injection Protection:
- Checks for
data-plugin="priority-icons"in output before injection
- Checks for
-
AJAX Skip:
- Skips AJAX requests (no complete HTML to inject into)
-
Asset Protection (.htaccess):
- PHP execution in
/assets/blocked - Browser caching: 1 week + gzip compression
- PHP execution in
¶ Accessibility (WCAG)
- Screen reader: Priority text preserved as
.sr-onlyelement aria-label: Each icon hasaria-label="Priority: {name}"cursor: help: Indicates tooltip availabilityprefers-reduced-motion: Disables pulse animation and transitions- Tooltip: CSS-only tooltip shows priority name on hover
- Dark mode: Automatic tooltip color adaptation
¶ Tests
97 tests (PHPUnit 11):
- 44 tests for the main plugin class (
PriorityIconsPluginTest) - 53 tests for admin configuration (
PriorityIconsConfigTest)
composer test # Run tests
composer analyse # PHPStan static analysis
¶ FAQ
¶ General Questions
Q: Does the plugin work in the Client Portal?
A: The plugin is designed for the Staff Panel. Priorities are typically not displayed in the Client Portal, so the plugin has no effect there.
Q: Can I use custom priority names?
A: Currently only the default priority names (Emergency, High, Normal, Low) and their German translations (Notfall, Hoch, Niedrig) are supported. Custom names require modifying the $priorityMap in class.PriorityIconsPlugin.php.
Q: What happens if I disable the plugin?
A: The original priority text labels are immediately displayed again. No data is modified - the plugin works entirely client-side.
Q: Is the plugin compatible with other osTicket plugins?
A: Yes. The plugin does not modify core files and uses its own namespace (data-plugin="priority-icons"). Conflicts are unlikely unless another plugin manipulates the same DOM elements.
¶ Technical Questions
Q: Why are assets loaded inline instead of as external files?
A: osTicket's include/.htaccess contains Deny from all, which blocks HTTP access to all files in the include/ directory. Inline injection bypasses this without modifying core files.
Q: Why does the plugin use ob_start() instead of Signal..connect()?
A: The osTicket signals apps.scp and apps.admin only fire on the Apps page - not on regular pages like the ticket list. $ost->addExtraHeader() also doesn't work because global $ost is still NULL during bootstrap(). ob_start() with a callback is the only reliable pattern.
Q: Does it work with NGINX?
A: Yes. Since all assets are injected inline, there are no external file requests that could be blocked by web server configurations.
Q: How do I change the icon size?
A: The icon size is controlled via CSS custom properties:
:root {
--priority-icon-size: 16px; /* Default: 12px */
}
¶ License
This plugin is released under the GNU General Public License v2, compatible with osTicket core.
See LICENSE for details.
¶ Support
For questions or issues, please create an issue on GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-priority-icons/issues
When reporting issues, please include:
- osTicket version (Admin Panel -> Settings -> About)
- PHP version (
php -v) - Plugin version (currently 1.0.3)
- Browser console errors (F12 -> Console)
- Page source excerpt (Ctrl+U -> search for "priority-icons")
¶ Contributing
Developed by Markus Michalski
Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
¶ Changelog
See CHANGELOG.md for version history.