¶ Custom CSS Loader
¶ Table of Contents
¶ Overview
The Custom CSS Loader Plugin automatically loads custom CSS files from assets/custom/css/ for osTicket's Staff Panel and Client Portal based on filename patterns.
Perfect for teams that want to customize osTicket's appearance without modifying core files or managing complex theme systems.
What makes this plugin essential:
- ❌ Default osTicket has limited styling options → Hard to match corporate branding
- ❌ Core file modifications get lost during updates
- ❌ Manual CSS injection requires PHP knowledge
- ✅ Plugin automatically loads CSS files → Just drop files and they work
¶ Key Features
- ✅ Automatic CSS Loading - Place CSS files in
assets/custom/css/and they're loaded automatically - ✅ Context-Aware - Files with
staffload in Admin Panel, files withclientload in Client Portal - ✅ Cache-Busting - Automatic
?v=<timestamp>parameter ensures browsers load updated CSS - ✅ Zero Configuration - Just drop your CSS files and they work
- ✅ Demo Files Included - Example CSS files to get you started
- ✅ No Core Modifications - Uses osTicket's output buffering for injection
- ✅ Security Hardened - Path traversal prevention, filename validation, XSS protection
¶ Use Cases
- Corporate Branding - Match osTicket's colors and layout to your company's design system
- Wide Layout - Expand the default 960px container for modern widescreen monitors
- Custom Color Schemes - Apply consistent colors across Staff Panel or Client Portal
- Accessibility Improvements - Add high-contrast styles or larger fonts
- Per-Environment Styling - Different colors for production vs. staging servers
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| osTicket | 1.17+ | Uses output buffering for CSS injection |
| PHP | 8.1+ | Required for readonly classes and modern type system |
¶ Installation
¶ Step 1: Install Plugin Files
¶ Method 1: ZIP Download (Recommended)
- Download latest release from Releases
- Extract ZIP file
- Upload
custom-css-loaderfolder to/include/plugins/on your osTicket server
Final path: /path/to/osticket/include/plugins/custom-css-loader/
¶ Method 2: Git Repository
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-custom-css-loader.git custom-css-loader
¶ Step 2: Enable Plugin in osTicket
- Login to osTicket Admin Panel
- Navigate to: Admin Panel → Manage → Plugins
- Click Add New Plugin
- Select Custom CSS Loader and click Install
- Click Enable
The plugin automatically creates the CSS directory (assets/custom/css/) and copies demo files on first enable.
¶ Step 3: Add Your CSS Files
- Navigate to
<osticket-root>/assets/custom/css/ - Create or copy CSS files with appropriate naming:
- Files with
staff→ Admin Panel - Files with
client→ Client Portal
- Files with
- Refresh osTicket - your styles are active!
¶ Configuration
¶ Available Settings
Navigate to Admin Panel → Manage → Plugins → Custom CSS Loader → Configure
| Setting | Description | Default |
|---|---|---|
| Enable CSS Loading | Toggle CSS loading on/off | ON |
The plugin requires minimal configuration - simply enable it and add your CSS files.
¶ Usage
¶ Directory Structure
Place your CSS files in:
<osticket-root>/assets/custom/css/
¶ Filename Patterns
| Pattern | Where it loads | Examples |
|---|---|---|
*staff* |
Admin Panel (Staff) | custom-staff.css, wide-layout-staff.css |
*client* |
Client Portal | custom-client.css, branding-client.css |
Note: Files without staff or client in the name are ignored.
Security Note: Filenames must contain only alphanumeric characters, hyphens, and underscores (e.g., my-staff-theme.css). Files with special characters are blocked for security reasons.
¶ Demo Files
The plugin includes demo CSS files in assets/demo/ with commented examples:
| Demo File | Purpose |
|---|---|
custom-staff.css |
Basic Admin Panel styling examples |
custom-client.css |
Basic Client Portal styling examples |
wide-layout-staff.css |
Expand container to 95% width (max 1800px) |
Copy the demo files you want to <osticket-root>/assets/custom/css/ and customize them.
¶ Example: Wide Layout for Staff Panel
Create assets/custom/css/wide-layout-staff.css:
/* Expand container from 960px to 95% width */
#container {
width: 95%;
max-width: 1800px;
margin: 0 auto 20px auto;
}
/* Blue header with corporate branding */
#header {
background-color: #1E3A5F !important;
background-image: none !important;
}
/* White logo and links */
#header a,
#header #info {
color: #FFFFFF !important;
}
¶ Example: Custom Colors for Client Portal
Create assets/custom/css/branding-client.css:
/* Primary button color */
.btn-primary,
button.blue {
background-color: #3498db !important;
border-color: #3498db !important;
}
/* Link color */
a {
color: #2980b9 !important;
}
¶ Multiple CSS Files
You can have multiple CSS files for each context. They are loaded in alphabetical order:
assets/custom/css/
├── 01-variables-staff.css # Loaded first (Staff Panel)
├── 02-layout-staff.css # Loaded second (Staff Panel)
├── 03-branding-staff.css # Loaded third (Staff Panel)
├── custom-client.css # Client Portal
└── wide-layout-staff.css # Staff Panel
¶ Troubleshooting
¶ Problem: CSS not loading
Symptoms:
- Custom styles are not applied
- No CSS link tags in page source
Check:
-
Plugin enabled?
- Admin Panel → Manage → Plugins → "Custom CSS Loader" → Status: Enabled
-
Plugin configured?
- Click Configure → "Enable CSS Loading": ON
-
Files in correct directory?
ls -la /path/to/osticket/assets/custom/css/ -
Filename contains
stafforclient?- ✅
custom-staff.css→ Loads in Admin Panel - ✅
my-client-theme.css→ Loads in Client Portal - ❌
custom.css→ Ignored (no pattern match)
- ✅
-
Filename valid?
- ✅
my-staff-theme.css→ Valid (alphanumeric, hyphens, underscores) - ❌
staff theme.css→ Blocked (contains space) - ❌
.hidden-staff.css→ Blocked (starts with dot)
- ✅
-
File readable?
chmod 644 /path/to/osticket/assets/custom/css/*.css
¶ Problem: CSS loads but styles don't apply
Symptoms:
- CSS file is loaded (visible in page source)
- Styles are not visible
Check:
-
CSS syntax errors?
- Open browser DevTools (F12) → Console tab
- Look for CSS parsing errors
-
Specificity issues?
- osTicket styles may have higher specificity
- Use
!importantwhere needed:
#header { background-color: #1E3A5F !important; } -
Browser cache?
- Hard refresh:
Ctrl+F5(Windows) orCmd+Shift+R(Mac) - The plugin adds
?v=<timestamp>for cache-busting, but browser may still cache
- Hard refresh:
¶ Problem: CSS directory not created
Symptoms:
assets/custom/css/doesn't exist after enabling plugin
Solution:
Create manually:
mkdir -p /path/to/osticket/assets/custom/css
chmod 755 /path/to/osticket/assets/custom/css
¶ Problem: Demo files not copied
Symptoms:
assets/custom/css/exists but is empty after enabling plugin
Check:
- Demo files only copy if directory is empty
- If you already have files there, demo files are not copied
Solution:
cp /path/to/osticket/include/plugins/custom-css-loader/assets/demo/*.css \
/path/to/osticket/assets/custom/css/
¶ Technical Details
¶ Architecture
Plugin Structure (v2.0.0+):
custom-css-loader/
├── plugin.php # Plugin metadata
├── class.CustomCssLoaderPlugin.php # Main plugin class
├── config.php # Plugin configuration
├── src/ # Modern PHP 8.1+ architecture
│ ├── Context/ # Context detection (Staff/Client)
│ ├── Discovery/ # CSS file discovery
│ ├── Rendering/ # HTML link tag rendering
│ ├── Injection/ # Output buffer injection
│ └── CssLoaderOrchestrator.php # Main orchestrator
├── assets/demo/ # Demo CSS files
└── tests/ # PHPUnit tests (73 tests)
¶ Security Features
The plugin includes comprehensive security measures:
- Path Traversal Prevention - Validates canonical paths via
realpath() - Symlink Attack Prevention - Blocks symlinks pointing outside CSS directory
- Filename Validation - Allowlist pattern: alphanumeric, hyphens, underscores only
- XSS Prevention - All URLs escaped with
htmlspecialchars() - Defense-in-Depth - Multiple validation layers
¶ CSS Injection Method
The plugin uses output buffering to inject CSS:
- Output buffer callback registered at plugin file include time
- Buffer captures full HTML output
- CSS
<link>tags injected before</head> - No modification of osTicket core files
¶ Context Detection
| Context | Detection Method |
|---|---|
| Staff Panel | OSTSCPINC constant OR /scp/ in URL path |
| Client Portal | OSTCLIENTINC constant OR .php file (not /scp/ or /api/) |
| API | /api/ in URL path → No CSS injected |
| CLI | No SCRIPT_NAME → No CSS injected |
¶ Cache-Busting
Each CSS file gets a version parameter based on file modification time:
<link rel="stylesheet" href="/assets/custom/css/wide-layout-staff.css?v=1702483200">
¶ FAQ
¶ General Questions
Q: Does this plugin modify osTicket core files?
A: No! The plugin uses output buffering to inject CSS. No core files are modified.
Q: Can I disable the plugin temporarily without losing my CSS files?
A: Yes! Simply Disable the plugin in Admin Panel. Your CSS files remain in assets/custom/css/.
Q: Does this work with osTicket 1.17 or older?
A: Yes, the plugin is designed for osTicket 1.17+. It uses output buffering which is compatible with older versions.
Q: Can I have multiple CSS files?
A: Yes! All CSS files matching the pattern (*staff* or *client*) are loaded. They load in alphabetical order.
¶ Compatibility
Q: Is it compatible with PHP 8.x?
A: Yes! The plugin requires PHP 8.1 or higher. It uses modern PHP features like readonly classes and union types.
Q: Does this work with custom osTicket themes?
A: Yes! The plugin simply adds CSS files after the theme's CSS. Your custom styles can override theme styles.
Q: Can I use this with other plugins?
A: Yes! The plugin uses a non-invasive injection method. It should work alongside any other plugin.
¶ Behavior
Q: What happens if I put a file without staff or client in the name?
A: The file is ignored. Only files matching the patterns are loaded.
Q: Does this affect API responses?
A: No, CSS is not injected for API requests.
Q: Why are my styles not applying?
A: Most likely a CSS specificity issue. osTicket's default styles may override yours. Use !important to ensure your styles take precedence.
Q: Where should I put the CSS directory?
A: CSS files go in <osticket-root>/assets/custom/css/, not in the plugin folder. This ensures your custom CSS survives plugin updates.
¶ 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-custom-css-loader/issues
When reporting issues, please include:
- osTicket version (Admin Panel → Settings → About)
- PHP version (
php -v) - Plugin version
- Browser console errors (F12 → Console)
- CSS file content (if relevant)
¶ 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.