Kylian Schmidt
142 lines
5.9 KiB
Markdown
142 lines
5.9 KiB
Markdown
# 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:
|
|
```python
|
|
# 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.
|