¶ Tab Swap
¶ Table of Contents
¶ Overview
The Tab Swap Plugin swaps the order of Reply and Internal Note tabs in the osTicket ticket detail view, making Internal Note the default active tab instead of Reply.
Perfect for teams that primarily use internal notes for collaboration and want to reduce accidental customer-facing replies.
What makes this plugin essential:
- ❌ Default osTicket shows Reply tab first → Risk of accidental customer replies
- ❌ Teams using internal notes more frequently have to switch tabs constantly
- ✅ Plugin makes Internal Note the default active tab → Faster workflow, fewer accidents
¶ Key Features
- ✅ Automatic Tab Swap - Internal Note becomes default active tab
- ✅ PJAX-Compatible - Works seamlessly with osTicket's dynamic navigation
- ✅ Permission-Aware - Handles users with/without reply permissions correctly
- ✅ Auto-Update Support - Version tracking built-in
- ✅ Mobile-Friendly - Works with responsive design
- ✅ No Core Modifications - Uses osTicket's Signal API
¶ Use Cases
- Internal Collaboration Teams - Teams that use internal notes more frequently than customer replies
- Reduce Accidental Replies - Prevent agents from accidentally sending replies to customers
- Faster Workflow - Agents who primarily work with internal notes save time
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| osTicket | 1.18.x | Plugin uses osTicket's Signal API |
| PHP | 7.4+ | Recommended: PHP 8.1+ for best performance |
| jQuery | Any | Included in osTicket by default |
¶ Installation
¶ Step 1: Install Plugin Files
¶ Method 1: ZIP Download (Recommended)
- Download latest release from Releases
- Extract ZIP file
- Upload
tab-swapfolder to/include/plugins/on your osTicket server
Final path: /path/to/osticket/include/plugins/tab-swap/
¶ Method 2: Git Repository
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-tab-swap.git tab-swap
¶ Step 2: Enable Plugin in osTicket
- Login to osTicket Admin Panel
- Navigate to: Admin Panel → Manage → Plugins
- Find "Tab Swap" in the plugin list
- Click Enable
The plugin automatically installs and updates /include/.htaccess to allow JavaScript files.
¶ Step 3: Configure Plugin
- After enabling, click Configure (gear icon)
- Toggle "Enable Tab Swap": ON
- Click Save Changes
¶ Configuration
¶ Available Settings
| Setting | Description | Default | Use When |
|---|---|---|---|
| Enable Tab Swap | Toggle tab swapping on/off | ON | You want to temporarily disable tab swap without uninstalling |
The plugin requires minimal configuration - simply enable it and it works out of the box.
¶ Usage
Once enabled, the plugin automatically swaps tabs in ticket view:
¶ Before (Default osTicket)
[Reply (active)] [Internal Note]
¶ After (With Plugin)
[Internal Note (active)] [Reply]
¶ Behavior
- Default active tab: Internal Note
- Tab order: Internal Note appears first (left)
- Form visibility: Internal Note form is visible, Reply form is hidden
- PJAX navigation: Works seamlessly when navigating between tickets
¶ Edge Cases Handled
| Scenario | Behavior |
|---|---|
| User has NO reply permission | Only Note tab exists → no swap performed |
| Ticket is closed | No forms present → no swap performed |
| Mobile view | Tab swap works (responsive design compatible) |
| PJAX navigation | Tab swap re-applied on dynamic load |
¶ Troubleshooting
¶ Problem: Tab swap doesn't work
Symptoms:
- Tabs are still in default order (Reply first)
- Internal Note is not the active tab
Check:
-
Plugin enabled?
- Admin Panel → Manage → Plugins → "Tab Swap" → Status: Enabled
-
Plugin configured?
- Click Configure (gear icon) → "Enable Tab Swap": ON
-
User has reply permission?
- If agent has NO reply permission, only Note tab exists (nothing to swap)
- Admin Panel → Agents → Staff → [Agent Name] → Permissions → Check "Reply to Tickets"
-
JavaScript errors?
- Open browser console (F12)
- Check for errors related to
tab-swap.js
-
Browser cache?
- Hard refresh:
Ctrl+F5(Windows) orCmd+Shift+R(Mac)
- Hard refresh:
¶ Problem: Works on first load, but breaks after PJAX navigation
Symptoms:
- Tab swap works when loading a ticket directly
- Stops working when navigating to another ticket
Solution:
- Check browser console for
[Tab-Swap] PJAX reload detectedmessage - Update plugin to latest version (older versions may not handle PJAX correctly)
- Verify osTicket version is 1.18.x (older versions may not support PJAX)
¶ Problem: JavaScript/CSS not loading (404 errors)
Symptoms:
- Plugin is enabled but JavaScript doesn't load
- Browser shows 404 error for
tab-swap.js
Cause: /include/.htaccess wasn't updated to allow static assets
Manual fix (Apache):
Edit /include/.htaccess and add this before the Deny from all line:
# Allow static assets for plugins (JavaScript, CSS, images, fonts)
<FilesMatch "\.(js|css|map|json|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|otf)$">
<IfModule mod_authz_core.c>
Require all granted
</IfModule>
<IfModule !mod_authz_core.c>
Order allow,deny
Allow from all
</IfModule>
</FilesMatch>
For NGINX:
location ~ ^/include/plugins/.+\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$ {
allow all;
access_log off;
expires 7d;
}
location ~ ^/include/ {
deny all;
}
¶ Technical Details
¶ Architecture
Plugin Structure:
tab-swap/
├── plugin.php # Plugin metadata
├── class.TabSwapPlugin.php # Main plugin class
├── config.php # Plugin configuration
└── js/
└── tab-swap.js # Frontend JavaScript
¶ Signal Hooks
The plugin connects to osTicket's Signal API:
| Signal | Handler | Purpose |
|---|---|---|
object.view |
onTicketView() |
Detects when a Ticket is viewed |
Implementation:
Signal::connect('object.view', function(Ticket $ticket) {
if ($user->hasPerm(PERM_REPLY)) {
// Inject JavaScript to swap tabs
}
});
¶ Frontend Implementation
JavaScript Workflow:
- Wait for DOM ready
- Find Reply (
#post-reply-tab) and Internal Note (#post-note-tab) tabs - Swap DOM order (move Note tab before Reply tab)
- Switch active state (deactivate Reply, activate Note)
- Toggle form visibility (hide Reply form, show Note form)
PJAX Support:
$(document).on('pjax:success', function() {
TabSwapPlugin.reset();
TabSwapPlugin.init();
});
¶ Permission Handling
| User Permission | Behavior |
|---|---|
Has PERM_REPLY |
✅ JavaScript injected, tabs swapped |
No PERM_REPLY |
❌ No injection (user sees only Note tab) |
¶ FAQ
¶ General Questions
Q: Does this plugin modify osTicket core files?
A: No! The plugin uses osTicket's official Signal API (object.view). No core files are modified.
Q: Can I disable the plugin temporarily without losing configuration?
A: Yes! Simply Disable the plugin in Admin Panel. Your configuration is saved in the database.
Q: Does this work with osTicket 1.17 or older?
A: No. The plugin is designed for osTicket 1.18.x only. Older versions may have different DOM structure.
¶ Compatibility
Q: Is it compatible with PHP 8.x?
A: Yes! The plugin is tested with PHP 7.4, 8.0, 8.1, 8.2, and 8.3.
Q: Does this work with custom osTicket themes?
A: Mostly yes, but custom themes may have different DOM structure. The plugin relies on standard element IDs (#post-reply-tab, #post-note-tab).
Q: Can I use this with other plugins?
A: Yes, but test for conflicts. Plugins that modify the same DOM elements may interfere.
¶ Behavior
Q: What happens if a user has no reply permission?
A: The plugin detects this and does not inject JavaScript. Users without reply permission only see the Note tab (nothing to swap).
Q: Does this affect API ticket creation?
A: No, this is a frontend-only plugin. API operations are unaffected.
Q: Why do canned responses still insert into Reply form?
A: This is osTicket core behavior, not controllable by plugins. After selecting a canned response, manually switch to the Reply tab or copy content to Note form.
¶ 📄 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-tab-swap/issues
When reporting issues, please include:
- osTicket version (Admin Panel → Settings → About)
- PHP version (
php -v) - Plugin version
- Browser console errors (F12 → Console)
- Steps to reproduce
¶ 🤝 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.