Gallery Application - Restructured

This document explains the new modular structure of the gallery application.

Project Structure

web/
├── assets/
│   ├── css/
│   │   ├── main.css              # Main CSS file (imports all others)
│   │   ├── variables.css         # CSS custom properties and themes
│   │   ├── base.css              # Base layout and typography
│   │   ├── navigation.css        # Breadcrumb and navigation styles
│   │   ├── search.css            # Search functionality styles
│   │   ├── folder-tree.css       # Folder tree component styles
│   │   ├── grid.css              # Plot grid and selection styles
│   │   ├── sidebar.css           # Recent plots sidebar styles
│   │   ├── floating-elements.css # Floating buttons and help
│   │   ├── stats.css             # Gallery statistics styles
│   │   ├── comparison.css        # Plot comparison overlay styles
│   │   └── responsive.css        # Mobile and responsive styles
│   └── js/
│       ├── main.js               # Main entry point
│       ├── gallery-app.js        # Main application orchestrator
│       ├── theme-manager.js      # Theme switching functionality
│       ├── navigation-manager.js # Breadcrumb and folder tree
│       ├── search-manager.js     # Search functionality
│       ├── recent-plots-manager.js # Recent plots sidebar
│       ├── comparison-manager.js # Plot comparison features
│       ├── stats-manager.js      # Gallery statistics
│       ├── keyboard-manager.js   # Keyboard shortcuts
│       └── utils.js              # Utility functions
├── templates/
│   └── gallery.html              # Clean HTML template
├── template.html                 # Original monolithic file (backup)
├── config.py
├── config.yaml
├── generate_gallery.py
└── README.md

Key Improvements

1. Separation of Concerns

• CSS: Organized into logical components (navigation, search, grid, etc.)
• JavaScript: Split into focused managers with single responsibilities
• HTML: Clean template focusing on structure

2. Modular Architecture

• Each JavaScript module handles a specific feature area
• Modules can be independently maintained and tested
• Clear dependencies and interfaces between modules

3. Maintainability

• Individual files are much smaller and focused
• Easy to locate and modify specific functionality
• Reduced cognitive load when working on features

4. Development Benefits

• Better IDE support with syntax highlighting and intellisense
• Easier debugging with source maps
• Ability to add build tools if needed

Module Responsibilities

CSS Modules

• variables.css: Theme colors and CSS custom properties
• base.css: Typography, basic layout, list styles
• navigation.css: Breadcrumb and navigation button styles
• search.css: Search box, results, and highlighting
• folder-tree.css: Collapsible folder tree display
• grid.css: Plot thumbnails grid and selection states
• sidebar.css: Recent plots sidebar and overlay
• floating-elements.css: Action buttons and keyboard help
• stats.css: Gallery statistics display
• comparison.css: Plot comparison overlay
• responsive.css: Mobile and tablet adaptations

JavaScript Modules

• ThemeManager: Light/dark theme switching and persistence
• NavigationManager: Breadcrumb building and folder tree construction
• SearchManager: Plot search with debouncing and results display
• RecentPlotsManager: Recent plots tracking and sidebar management
• ComparisonManager: Plot comparison functionality
• StatsManager: Gallery statistics calculation and display
• KeyboardManager: Keyboard shortcuts and escape handling
• Utils: File size formatting, thumbnail highlighting, gallery refresh

Main Application

• GalleryApp: Orchestrates all managers and provides unified interface
• main.js: Entry point that initializes the application

Usage

The restructured application maintains full backward compatibility with the original template. All existing functionality works exactly the same way.

For Python Backend

Update your template reference to use the new template:

# Instead of template.html, use:
template_path = 'templates/gallery.html'

CSS Asset Path

The template expects CSS/JS assets to be served from /assets/ relative to the gallery pages. Update your web server configuration to serve these static files.

No Breaking Changes

• All onclick handlers work the same
• All CSS classes remain unchanged
• All IDs and functionality preserved
• Jinja2 template variables work identically

Development Workflow

Adding New Features

1. Identify which manager should handle the new functionality
2. Add methods to the appropriate manager class
3. Update the main GalleryApp class if needed
4. Add any new CSS to the appropriate CSS module

Modifying Existing Features

1. Locate the relevant manager (theme, search, navigation, etc.)
2. Make changes to the specific module
3. Test that the feature works as expected

Styling Changes

1. Identify the component being styled
2. Edit the appropriate CSS module
3. The main.css file will automatically include changes

Benefits of This Structure

1. Easier Debugging: Each feature is isolated in its own file
2. Better Performance: Browser can cache individual modules
3. Team Development: Multiple developers can work on different features simultaneously
4. Code Reuse: Managers can be reused in other projects
5. Testing: Individual modules can be unit tested
6. Documentation: Each file has a clear, focused purpose

This restructuring makes the gallery application much more maintainable while preserving all existing functionality.