FreeScout Extra JS Module

A minimal FreeScout module that allows administrators to inject custom JavaScript code into all FreeScout pages.

Features

• Settings page to enter custom JavaScript code
• Automatic injection of custom JS into all non-settings pages
• Simple textarea interface for code management
• No external dependencies

Requirements

• FreeScout 1.8+
• PHP 8.3+

Installation

1. Copy the module to FreeScout

   Copy the ExtraJS directory into your FreeScout installation's Modules directory:

   cp -r ExtraJS /path/to/freescout/Modules/

   Or via SFTP:

   scp -r ExtraJS root@your-server:/path/to/freescout/Modules/

2. Set permissions

   Ensure the module has the correct ownership:

   chown -R www-data:www-data /path/to/freescout/Modules/ExtraJS/

3. Activate the module

   • Log in to FreeScout as an administrator
   • Navigate to Manage > Modules
   • Find Extra JS in the list
   • Click Activate

Usage

1. Navigate to the settings page at /app-settings/extrajs
2. Enter your custom JavaScript code in the textarea
3. Click Save

The JavaScript code will be automatically injected into all pages except settings pages and the modules page.

Example Usage

// Add a custom notification
console.log("Extra JS module is active");

// Modify page elements with jQuery
$(document).ready(function () {
  $('[title="Reply"]').css("background-color", "yellow");
});

// Add warnings to UI elements
$('[title="New Conversation"]').attr(
  "title",
  "New Conversation - Note: Custom warning here",
);

How It Works

The module uses FreeScout's Eventy action/filter system to inject JavaScript:

1. Custom JS code is stored in the options table via \Option::set('extrajs.custom_code', $code)
2. The ServiceProvider hooks into the layout.body_bottom action
3. On page load, the hook checks if the current path is not a settings page
4. If valid, it echoes the stored custom JS inside its own <script> tag and adds FreeScout's CSP nonce to keep the output compliant

File Structure

ExtraJS/
├── Config/
│   └── config.php              # Module configuration
├── Providers/
│   └── ExtraJSServiceProvider.php # Main service provider
├── Resources/
│   └── views/
│       └── settings.blade.php  # Settings page template
├── composer.json               # Composer autoload configuration
└── module.json                 # Module metadata

Troubleshooting

1. Module not appearing: Clear FreeScout cache and ensure proper file permissions
2. Settings page not accessible: Verify you're logged in as an admin
3. JS not injecting: Check that the module is activated and the code is saved
4. Permission errors: Run chown -R www-data:www-data /path/to/freescout/Modules/ExtraJS/

Security Considerations

• Only administrators can access the settings page
• Be cautious with the JavaScript code you inject
• Test thoroughly before using in production
• Consider using Content Security Policy (CSP) headers if needed

Author

Carlo Zottmann, carlo@zottmann.dev, https://c.zottmann.dev, https://github.com/czottmann.

This project is neither affiliated with nor endorsed by FreeScout. I'm just a happy customer.

Tip

I make Shortcuts-related macOS & iOS productivity apps like Actions For Obsidian, Browser Actions (which adds Shortcuts support for several major browsers), and BarCuts (a surprisingly useful contextual Shortcuts launcher). Check them out!

License

MIT