TDX Feedback Gem

A Rails engine that provides a seamless, modal-based feedback system for any Rails application. Users can submit feedback without leaving your main application, and the system can integrate with the TDX API for ticket creation when enabled.

• Modal-based feedback system - No page navigation required
• Seamless integration - Drop into any Rails application
• TDX API integration - Optionally creates support tickets (when enabled)
• Responsive design - Works on all device sizes
• Customizable styling - Easy to match your app's design
• Authentication support - Optional user authentication requirement
• Stimulus-powered - Modern JavaScript framework integration
• Generator-wired assets - Installer adds the JavaScript and CSS for you
• Automatic Importmap pinning - Controller auto-pinned (can be disabled)
• Optional runtime SCSS copy (dev/test) - Avoids mutating production builds

Add to your Gemfile:

gem 'tdx_feedback_gem', '~> 0.1.3'

bundle install
rails generate tdx_feedback_gem:install
rails db:migrate

Add the engine to your host app routes (recommended mount path shown):

# config/routes.rb
mount TdxFeedbackGem::Engine => '/tdx_feedback_gem'

Recompile your assets:

bundle exec rake assets:clobber && bundle exec rake dartsass:build
bundle exec rake assets:precompile

That's it! The gem automatically:

• ✅ Creates the necessary database migration
• ✅ Sets up the initializer with default configuration
• ✅ Copies the Stimulus controller to your app
• ✅ Includes the CSS styles in your asset pipeline
• ✅ Registers the helper methods globally
• ✅ Validates configuration at boot and logs non-fatal warnings (missing IDs, unsafe flags, missing importmap)

If your app uses Importmap the engine will automatically attempt to pin its Stimulus controller when auto_pin_importmap is enabled (default). The engine only adds its app/javascript path to Importmap when an importmap.json file is present (avoids mutating frozen configs in some setups).

Disable auto pinning (manual control):

export TDX_FEEDBACK_GEM_AUTO_PIN=false

Then ensure you have a manual pin in config/importmap.rb:

pin_all_from 'app/javascript/controllers', under: 'controllers'

Edit config/initializers/tdx_feedback_gem.rb if you need custom settings:

TdxFeedbackGem.configure do |config|
  config.require_authentication = true
  config.enable_ticket_creation = false
  config.oauth_scope = 'tdxticket'
  config.title_prefix = '[Feedback]'
  # Front-end behavior toggles
  # Auto-pin Stimulus controller for Importmap (credentials/env/initializer overrideable)
  config.auto_pin_importmap = true
  # Allow runtime SCSS partial copy (dev/test convenience). Disable in immutable prod builds.
  config.runtime_scss_copy = Rails.env.development?

  # TDX API credentials (use Rails credentials or environment variables)
  config.app_id = 31
  config.type_id = 12
  config.status_id = 77
  config.source_id = 8
  config.service_id = 67
  config.responsible_group_id = 631
end

Add to your layout or views:

<%= feedback_system(trigger: :link, text: 'Feedback', class: 'tdx-feedback-footer-link') %>
<%= feedback_system(trigger: :button, text: 'Send Feedback') %>
<%= feedback_footer_link %>
<%= feedback_header_button %>

If you mount the engine at a different path than /tdx_feedback_gem, either:

• Pass custom URLs via Stimulus values on your trigger element:
  • data-tdx-feedback-new-url-value="/feedback/feedbacks/new"
  • data-tdx-feedback-submit-url-value="/feedback/feedbacks"
• Or mount at /tdx_feedback_gem to use the controller defaults.

The gem automatically resolves configuration from:

1. Rails Encrypted Credentials (recommended)
2. Environment Variables
3. Built-in defaults

Enable/disable TDX ticket creation without redeploying:

export TDX_ENABLE_TICKET_CREATION=true

Disable automatic Importmap pinning (if you prefer manual control):

export TDX_FEEDBACK_GEM_AUTO_PIN=false

Disable runtime SCSS copying (normally already false in production):

export TDX_FEEDBACK_GEM_RUNTIME_SCSS_COPY=false

Update assets (after gem upgrade) to refresh the SCSS partial & controller:

rails g tdx_feedback_gem:update_assets

After bumping the gem version:

1. Run bundle install
2. (Optional) Re-run the installer if you want newly added initializer comments: rails g tdx_feedback_gem:install
3. Refresh front-end assets (controller / SCSS) if desired: rails g tdx_feedback_gem:update_assets
4. Review the CHANGELOG for behavioral changes
5. Check application logs on boot for any tdx_feedback_gem configuration warning messages

• 📚 Wiki - Complete documentation, examples, and guides
• 🚀 Getting Started - Quick overview and setup details
• ⚙️ Configuration Guide - Credentials, env vars, and defaults
• 🔧 Integration Examples - Rails 5/6/7, authentication systems
• 🎨 Styling and Theming - Customization and theming
• 🧪 Testing Guide - Test setup and coverage
• 🩺 Troubleshooting - Common issues and fixes
• 📊 API Schemas - TDX API specifications
• 🧰 Helper Methods Reference - All view helpers and options
• ⚡ Stimulus API Reference - Controller events and targets

git clone https://github.com/lsa-mis/tdx-feedback_gem.git
cd tdx-feedback_gem
bundle install
bundle exec rspec

Bug reports and pull requests are welcome on GitHub.

The gem is available as open source under the terms of the MIT License.