SPA Navigation Guide

SPA Navigation Enhancement Guide

Overview

This implementation enhances the Gaseous Games application with proper Single Page Application (SPA) behavior when navigating between the home and library pages, including proper page unloading and cleanup mechanisms.

Key Features

1. Enhanced SPA Navigation

• Seamless transitions between home and library pages without full page reloads
• Page unloading - old page content is properly cleaned up before loading new content
• Browser navigation support - back/forward buttons work correctly
• URL state management - URLs update correctly and support bookmarking

2. Page Cleanup System

• Automated cleanup - intervals, timeouts, and event listeners are properly removed
• Memory management - prevents memory leaks from accumulated JavaScript objects
• Custom cleanup callbacks - pages can register their own cleanup functions

3. Fallback Compatibility

• Graceful degradation - if SPA navigation fails, falls back to standard navigation
• Mixed navigation - non-SPA pages (settings, collections, etc.) still use traditional navigation

Implementation Details

Core Functions (index.html)

LoadPageContent(page, targetDiv)

Enhanced to support proper page unloading:

• Calls unloadCurrentPage() for home/library pages before loading new content
• Tracks current page state
• Maintains existing functionality for other pages

unloadCurrentPage()

Handles cleanup when switching between SPA pages:

• Calls page-specific unload callbacks
• Performs general cleanup (timers, event listeners, etc.)
• Clears jQuery lazy loading and select2 instances

navigateToPage(page)

Smart navigation function:

• Uses SPA navigation for home ↔ library transitions
• Updates browser history with pushState
• Falls back to standard navigation for other pages

registerPageUnloadCallback(pageName, callback)

Allows pages to register custom cleanup functions:

registerPageUnloadCallback('library', async () => {
    // Custom cleanup code here
});

Page-Specific Cleanup

Library Page (library.js)

• Clears scroll and resize timers
• Saves scroll position to localStorage
• Cleans up filter object callbacks
• Resets loaded pages array
• Removes event listeners

Home Page (home.js)

• Clears loading intervals for game rows
• Resets cover URL lists
• Cleans up any ongoing async operations

Navigation Updates (banner.js)

Navigation buttons now use the enhanced navigateToPage() function with fallback to traditional navigation.

Browser Navigation Support

• popstate event listener handles browser back/forward navigation
• History state management preserves page state in browser history
• URL synchronization keeps URL in sync with current page

Usage Examples

Basic SPA Navigation

// Navigate to library page (SPA mode)
navigateToPage('library');

// Navigate to home page (SPA mode)  
navigateToPage('home');

// Navigate to settings (traditional mode)
navigateToPage('settings');

Custom Page Cleanup

// Register cleanup for a new page
registerPageUnloadCallback('mypage', async () => {
    // Clear timers
    if (myPageTimer) {
        clearTimeout(myPageTimer);
    }
    
    // Remove event listeners
    window.removeEventListener('scroll', myScrollHandler);
    
    // Clear data
    myPageData = [];
    
    console.log('MyPage cleanup completed');
});

Checking Navigation Capability

// Check if SPA navigation is available
if (typeof navigateToPage === 'function') {
    navigateToPage('library');
} else {
    // Fallback to traditional navigation
    window.location.href = '/index.html?page=library';
}

Browser Compatibility

• Modern browsers: Full SPA functionality with history management
• Older browsers: Graceful fallback to traditional navigation
• JavaScript disabled: Standard page navigation still works

Performance Benefits

1. Faster navigation - No full page reloads between home/library
2. Reduced server load - Fewer complete page requests
3. Better user experience - Smooth transitions without white screens
4. Memory efficiency - Proper cleanup prevents memory leaks
5. Preserved state - Background images and other elements persist

Testing the Implementation

Manual Testing

1. Navigate between Home and Library using the navigation buttons
2. Use browser back/forward buttons
3. Reload the page on home or library and verify state restoration
4. Check browser console for cleanup messages
5. Test navigation to other pages (settings, collections) to ensure they still work

Console Monitoring

Look for these console messages indicating proper operation:

• "SPA navigation from library to home"
• "Unloading page: library"
• "Library page cleanup completed"
• "Browser navigation to: home"

Future Enhancements

1. Page transitions - Add smooth animations between pages
2. Preloading - Preload next likely page for even faster navigation
3. State preservation - Maintain scroll position and form state
4. Loading indicators - Show progress during page transitions
5. Cache management - Cache page content for offline navigation

Troubleshooting

Common Issues

1. Cleanup not working: Ensure registerPageUnloadCallback is called after the function is defined
2. History issues: Check that pushState is supported in the browser
3. Memory leaks: Verify all timers and event listeners are properly cleared in cleanup callbacks

Debug Mode

Enable verbose logging by adding this to browser console:

// Enable debug logging
localStorage.setItem('spaDebug', 'true');

This implementation provides a solid foundation for SPA behavior while maintaining backwards compatibility and proper resource management.