Skip to content

Latest commit

 

History

History
188 lines (140 loc) · 6.92 KB

LAYOUT_REFACTORING.md

File metadata and controls

188 lines (140 loc) · 6.92 KB

ChIP-Atlas Layout System Refactoring

Overview

This document describes the successful layout system refactoring that was implemented to eliminate duplicate HTML navigation structure across HAML view files in the ChIP-Atlas application.

Problem Solved

Previously, all HAML view files contained duplicate code for:

  • Navigation bar structure (50+ lines per file)
  • Inconsistent active menu highlighting
  • Maintenance overhead when updating navigation

This led to:

  • Code duplication across 12+ view files
  • Inconsistency in navigation active states
  • Difficulty making global navigation changes

Solution Implemented

Simple Partial-Based Approach

We implemented a partial-based approach that eliminates duplication while maintaining full compatibility:

  1. views/_navigation.haml - Centralized navigation partial
  2. Each HAML file maintains complete HTML structure but uses the shared navigation
  3. @active_menu variable controls which menu item is highlighted

Key Implementation Details

Navigation Partial (_navigation.haml)

  • Contains the complete navbar structure
  • Uses @active_menu variable to determine active state
  • Supports all existing navigation functionality

Usage Pattern in View Files

Each view file follows this pattern:

!!! 5
%html{ :lang => "en" }
  %head
    // Meta tags, title, CSS includes
    
  %body
    - @active_menu = 'page_name'  # or nil for no active state
    != haml :_navigation
    
    .container
      // Page content here
    
    != haml :footer
    
    // JavaScript includes

Active Menu Values

Available @active_menu values:

  • 'peak_browser'
  • 'enrichment_analysis'
  • 'diff_analysis'
  • 'target_genes'
  • 'colo'
  • 'publications'
  • nil (no active state)

Converted Files

Successfully converted the following files:

Main Application Pages

  1. about.haml - Homepage (@active_menu = nil)
  2. peak_browser.haml - Peak visualization (@active_menu = 'peak_browser')
  3. search.haml - Dataset search (@active_menu = nil)
  4. enrichment_analysis.haml - Enrichment analysis (@active_menu = 'enrichment_analysis')
  5. target_genes.haml - Target gene analysis (@active_menu = 'target_genes')
  6. colo.haml - Colocalization analysis (@active_menu = 'colo')
  7. publications.haml - Publications list (@active_menu = 'publications')
  8. diff_analysis.haml - Differential analysis (@active_menu = 'diff_analysis')

Utility Pages

  1. not_found.haml - 404 error page (@active_menu = nil)
  2. experiment.haml - Experiment details (@active_menu = nil)

Result Pages

  1. enrichment_analysis_result.haml - Results display (@active_menu = 'enrichment_analysis')

Benefits Achieved

Code Reduction

  • Before: Each file contained 50+ lines of duplicate navigation HTML
  • After: Navigation centralized in one 51-line partial file
  • Total reduction: ~600+ lines of duplicate code eliminated

Maintenance Improvements

  1. Single source of truth: Navigation changes happen in one file
  2. Consistent active states: Centralized logic prevents inconsistencies
  3. Easy updates: Adding new menu items or changing structure is simple
  4. No routing changes: Compatible with existing Sinatra application structure

Technical Benefits

  1. No layout conflicts: Avoids Sinatra's automatic layout system
  2. Full HTML control: Each file remains complete and self-contained
  3. Incremental approach: Low risk, gradual refactoring
  4. Easy debugging: Clear separation between shared and page-specific code

Critical Implementation Notes

HAML Rendering Syntax

Important: Use != haml :_navigation (not = haml :_navigation)

  • The != prevents HTML escaping and renders the partial correctly
  • The = would escape HTML entities and show raw HTML instead of components

Sinatra Layout System

Important: Removed layout.haml file

  • Sinatra automatically uses layout.haml if it exists, causing conflicts
  • Our approach maintains full HTML structure in each file instead

Variable Scope

  • @active_menu is set before including the navigation partial
  • Instance variables are accessible within the partial context

Future Enhancements

Potential improvements for this approach:

  1. Head section partial: Extract common <head> content
  2. Footer partial: Centralize footer structure (if needed)
  3. JavaScript includes partial: Share common script includes
  4. CSS management: Centralized stylesheet includes

Testing Verification

After implementing this system:

  1. ✅ Navigation renders correctly on all pages
  2. ✅ Active menu highlighting works properly
  3. ✅ All JavaScript functionality preserved (search, responsive menu)
  4. ✅ No visual changes to end users
  5. ✅ Easy navigation updates - changes in one file affect all pages

Migration Process

The refactoring was accomplished through:

  1. Created navigation partial (_navigation.haml)
  2. Updated each HAML file to use != haml :_navigation
  3. Set appropriate @active_menu values for each page
  4. Removed duplicate navigation HTML from each file
  5. Tested functionality to ensure no regressions

Indentation Fix Summary

After the initial implementation, indentation issues were identified and fixed across all HAML files:

Files Fixed for Indentation

  • target_genes.haml - Completely rewritten with proper 2-space indentation
  • enrichment_analysis.haml - Completely rewritten with consistent indentation
  • diff_analysis_result.haml - Fixed to use proper HTML structure with navigation partial
  • All other files - Verified and corrected where necessary

Critical Indentation Rules for HAML

  1. Consistent 2-space indentation throughout all files
  2. Proper nesting hierarchy maintained
  3. Navigation partial integration correctly indented: 
    %body
  - @active_menu = 'page_name'
  != haml :_navigation

Validation Process

  • Systematically checked all modified HAML files
  • Rebuilt files with indentation issues from scratch
  • Verified proper HTML structure and HAML syntax compliance

Conclusion

The partial-based approach successfully eliminated navigation code duplication while maintaining full compatibility with the existing application. The solution is simple, maintainable, and provides a solid foundation for future improvements.

Key Success Factors:

  • Minimal changes to existing architecture
  • No routing modifications required
  • Preserved all existing functionality
  • Reduced maintenance overhead
  • Easy to understand and extend
  • Proper HAML indentation maintained across all files

This approach demonstrates that effective refactoring doesn't always require complex architectural changes - sometimes a simple, focused solution is the most effective. The critical lesson learned is that HAML's indentation sensitivity requires careful attention during refactoring to ensure proper rendering.