Troubleshooting

Troubleshooting Guide

Common issues and their solutions.

Widget Not Appearing

Problem

The accessibility button doesn't appear on the page.

Solutions

1. Check File Loading

   • Open browser developer tools (F12)
   • Go to Network tab
   • Reload the page
   • Verify all files are loading (no 404 errors)

2. Check File Order

   • Ensure files are loaded in correct order:
     1. Boxicons CSS
     2. Plugin CSS
     3. Config JS (optional)
     4. Plugin JS (must be last)

3. Check Console for Errors

   • Open browser console (F12 → Console)
   • Look for JavaScript errors
   • Fix any errors before the plugin can load

4. Verify Boxicons is Loaded

   • Boxicons CSS must be loaded before plugin CSS
   • Check that Boxicons URL is correct

5. Check for Conflicts

   • Temporarily disable other scripts
   • Check if widget appears
   • Re-enable scripts one by one to find conflict

Text-to-Speech Not Working

Problem

TTS doesn't speak or shows an error.

Solutions

1. Check Browser Support

   • TTS works best in Chrome, Edge, and Safari
   • Firefox has limited TTS support
   • Check browser console for errors

2. Check Permissions

   • Some browsers require user interaction before TTS
   • Try clicking a button first, then using TTS
   • Check browser settings for speech permissions

3. Enable TTS in Panel

   • Open accessibility panel
   • Ensure TTS is enabled
   • Check TTS settings (rate, pitch, volume)

4. Check Text Selection

   • For "Read Selected Text", ensure text is selected
   • Try selecting text first, then clicking button

5. Browser Console Errors

   • Check console for Web Speech API errors
   • Some browsers block TTS in certain contexts

Settings Not Persisting

Problem

Settings reset when page reloads.

Solutions

1. Check localStorage

   • Open browser console
   • Type: localStorage.getItem('accessibilitySettings')
   • Should return a JSON string
   • If null, localStorage may be disabled

2. Check Browser Settings

   • Ensure cookies/localStorage aren't blocked
   • Check browser privacy settings
   • Try in incognito/private mode

3. Check Domain

   • Settings are per-domain
   • localhost and 127.0.0.1 are different domains
   • Use consistent domain for testing

4. Clear and Reset

   • Clear browser cache
   • Clear localStorage
   • Reload page and test again

Color Blindness Filter Issues

Problem

Color blindness filter doesn't apply or causes issues.

Solutions

1. Check Browser Support

   • Modern browsers required
   • SVG filters must be supported
   • Check browser compatibility

2. Check for CSS Conflicts

   • Other CSS may override filters
   • Check for conflicting styles
   • Use browser inspector to debug

3. Performance Issues

   • Filters may slow down very large pages
   • Consider disabling on pages with many images
   • Optimize images for better performance

4. Widget Disappears

   • This is fixed in recent versions
   • Ensure you're using latest version
   • Check custom CSS isn't interfering

Performance Issues

Problem

Page becomes slow with plugin enabled.

Solutions

1. Disable Unused Features

   • Disable color blindness filters if not needed
   • Turn off reading tools if not used
   • Minimize active features

2. Use CDN Version

   • CDN provides better caching
   • Reduces server load
   • Faster loading times

3. Check for Conflicts

   • Other scripts may conflict
   • Disable other scripts to test
   • Check browser performance profiler

4. Optimize Images

   • Large images slow down filters
   • Optimize images for web
   • Use appropriate image formats

Styling Issues

Problem

Widget looks broken or doesn't match site design.

Solutions

1. Check CSS Loading

   • Ensure plugin CSS is loaded
   • Check for CSS conflicts
   • Verify Boxicons CSS is loaded

2. Check Custom CSS

   • Your site's CSS may override plugin styles
   • Use more specific selectors
   • Check CSS specificity

3. Customize Appearance

   • See Customization Guide
   • Override CSS as needed
   • Match your site's design

4. Check Z-Index

   • Widget may be behind other elements
   • Adjust z-index if needed
   • Check for overlapping elements

Console Errors

Problem

JavaScript errors in browser console.

Solutions

1. Check File Paths

   • Verify all file paths are correct
   • Check for typos in file names
   • Ensure files exist at specified paths

2. Check File Order

   • Files must load in correct order
   • Plugin JS must load last
   • Check script tags

3. Check for Conflicts

   • Other scripts may conflict
   • Check error messages
   • Isolate conflicting code

4. Check Browser Compatibility

   • Some features require modern browsers
   • Check browser version
   • Update browser if needed

Configuration Not Working

Problem

Configuration changes don't take effect.

Solutions

1. Check File Loading

   • Ensure config file is loaded
   • Check browser console for errors
   • Verify file path is correct

2. Check File Order

   • Config must load before plugin JS
   • Check script tag order
   • Verify no errors before plugin loads

3. Clear Cache

   • Clear browser cache
   • Hard refresh (Ctrl+F5 or Cmd+Shift+R)
   • Try in incognito mode

4. Check Syntax

   • Verify JavaScript syntax is correct
   • Check for missing commas, brackets
   • Validate JSON structure

Mobile Issues

Problem

Widget doesn't work properly on mobile.

Solutions

1. Check Viewport Meta Tag

   • Ensure viewport meta tag is present
   • <meta name="viewport" content="width=device-width, initial-scale=1.0">

2. Check Touch Events

   • Widget should work with touch
   • Test on actual device, not just emulator
   • Check for touch event conflicts

3. Check Mobile Browser

   • Test on actual mobile device
   • Different browsers behave differently
   • Check mobile-specific issues

4. Check Screen Size

   • Widget may need adjustment for small screens
   • Check responsive CSS
   • Test various screen sizes

Still Having Issues?

1. Check Browser Console

   • Open developer tools (F12)
   • Look for error messages
   • Note any warnings

2. Test in Different Browser

   • Try Chrome, Firefox, Safari
   • Isolate browser-specific issues
   • Check compatibility

3. Check Documentation

   • Review Installation Guide
   • Check Configuration Guide
   • Read API Documentation

4. Get Help

   • Search GitHub Issues
   • Open a new issue with details
   • Email: support@airforcerp.com

Reporting Issues

When reporting an issue, please include:

1. Browser and Version

   • e.g., Chrome 120, Firefox 121, Safari 17

2. Steps to Reproduce

   • What you did
   • What happened
   • What you expected

3. Console Errors

   • Screenshot of console
   • Error messages
   • Warnings

4. Environment

   • Operating system
   • Device type (desktop/mobile)
   • Website URL (if public)

5. Screenshots

   • Visual issues
   • Error messages
   • Unexpected behavior