kennethreitz/kjvstudy.org

Fork 0

mirror of https://github.com/kennethreitz/kjvstudy.org.git synced 2026-06-05 23:00:16 +00:00

Files

T

kennethreitz 13fba60637 Add comprehensive family tree feature expansion

2025-05-30 19:53:20 -04:00

18 KiB

Raw Blame History

Family Tree Expansion Implementation Guide

This comprehensive guide details how to implement and integrate the advanced family tree features for the KJV Study application.

Overview

The family tree expansion includes five major components:

Advanced Tree Layouts - Multiple visualization algorithms
Enhanced Search & Navigation - Comprehensive search with highlighting
Statistical Analytics - Interactive charts and demographic insights
Mobile Optimization - Responsive design for all devices
Export Capabilities - Multiple output formats

📁 File Structure

kjvstudy_org/
├── static/
│   ├── js/
│   │   ├── advanced-tree-layouts.js          # Multiple layout algorithms
│   │   ├── family-tree-search.js             # Search and navigation
│   │   ├── family-tree-analytics.js          # Statistics and insights
│   │   └── family-tree-analytics-complete.js # Complete analytics
│   └── css/
│       └── family-tree-expansions.css        # All styling
├── templates/
│   ├── family_tree.html                      # Original template
│   └── enhanced_family_tree.html             # New enhanced template
└── FAMILY_TREE_EXPANSION_GUIDE.md           # This guide

🚀 Quick Start Implementation

Step 1: Add Dependencies

Add these dependencies to your existing family_tree.html template:

<!-- Add to <head> section -->
<script src="https://d3js.org/d3.v7.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<link href="/static/css/family-tree-expansions.css" rel="stylesheet">

<!-- Add before closing </body> tag -->
<script src="/static/js/advanced-tree-layouts.js"></script>
<script src="/static/js/family-tree-search.js"></script>
<script src="/static/js/family-tree-analytics.js"></script>

Step 2: Initialize Components

Add this to your existing JavaScript section:

// Initialize advanced components after family data loads
let advancedLayouts, searchEngine, analyticsEngine;

function initializeAdvancedFeatures() {
    const svg = d3.select("#tree-svg");
    
    // Initialize layout engine
    advancedLayouts = new AdvancedTreeLayouts(svg.node(), familyData);
    advancedLayouts.setSelectPersonCallback(selectPerson);
    
    // Initialize search
    searchEngine = new FamilyTreeSearch(familyData, advancedLayouts);
    
    // Initialize analytics
    analyticsEngine = new FamilyTreeAnalytics(familyData);
}

// Call this after familyData is loaded
initializeAdvancedFeatures();

Step 3: Add Layout Selector

Insert this HTML where you want the layout controls:

<div class="layout-controls">
    <button onclick="switchLayout('hierarchical')" class="layout-btn active">
        <i class="fas fa-sitemap"></i> Hierarchical
    </button>
    <button onclick="switchLayout('radial')" class="layout-btn">
        <i class="fas fa-sun"></i> Radial
    </button>
    <button onclick="switchLayout('force-directed')" class="layout-btn">
        <i class="fas fa-project-diagram"></i> Force-Directed
    </button>
    <button onclick="switchLayout('timeline')" class="layout-btn">
        <i class="fas fa-timeline"></i> Timeline
    </button>
</div>

🎨 Advanced Tree Layouts

Available Layouts

1. Hierarchical Tree (Default)

Use Case: Traditional family tree representation
Best For: Clear parent-child relationships
Implementation:

// Uses existing D3 tree layout - no changes needed
updateD3Tree(person, personId);

2. Radial Tree

Use Case: Generations in concentric circles
Best For: Showing generational patterns
Implementation:

advancedLayouts.renderRadialLayout(personId, maxGenerations);

3. Force-Directed Layout

Use Case: Dynamic relationship visualization
Best For: Exploring complex relationships
Implementation:

advancedLayouts.renderForceDirectedLayout(personId, includeExtended);

4. Timeline Layout

Use Case: Chronological family history
Best For: Historical context and lifespans
Implementation:

advancedLayouts.renderTimelineLayout(personId);

5. Circular Pedigree

Use Case: Traditional pedigree charts
Best For: Ancestry focus
Implementation:

advancedLayouts.renderCircularPedigreeLayout(personId);

Layout Switching Function

function switchLayout(layoutType) {
    // Update UI
    document.querySelectorAll('.layout-btn').forEach(btn => {
        btn.classList.remove('active');
    });
    event.target.classList.add('active');
    
    // Switch layout
    switch(layoutType) {
        case 'radial':
            advancedLayouts.renderRadialLayout(currentPersonId);
            break;
        case 'force-directed':
            advancedLayouts.renderForceDirectedLayout(currentPersonId);
            break;
        case 'timeline':
            advancedLayouts.renderTimelineLayout(currentPersonId);
            break;
        case 'circular-pedigree':
            advancedLayouts.renderCircularPedigreeLayout(currentPersonId);
            break;
        default:
            updateD3Tree(familyData[currentPersonId], currentPersonId);
    }
}

Search Features

Basic Search

Real-time search with debouncing
Multiple field search (name, title, description, verses)
Gender and generation filtering

Advanced Features

Bookmarking system with localStorage
Navigation breadcrumbs
Search result highlighting in tree
Export search results to CSV

Integration Example

// The search system auto-integrates when initialized
// Customize search behavior:
searchEngine.setTreeVisualization(advancedLayouts);

// Handle search result selection
function handleSearchResult(personId) {
    selectPerson(personId);
    searchEngine.addToBreadcrumbs(personId);
}

Bookmark Management

// Add current person to bookmarks
function addCurrentBookmark() {
    searchEngine.addBookmark(currentPersonId);
}

// Navigate to bookmarked person
function navigateToBookmark(personId) {
    selectPerson(personId);
}

📊 Statistical Analytics

Available Analytics

Overview Statistics

Total persons count
Gender distribution
Generation count
Family metrics
Average children per family

Interactive Charts

Demographics - Gender distribution (pie/bar/doughnut)
Generations - Population by generation
Relationships - Family size distribution
Timeline - Biblical timeline analysis
Longevity - Lifespan distribution

Custom Analytics

// Add custom insight
analyticsEngine.addCustomInsight = function(title, value, description) {
    const insightsList = document.getElementById('notable-stats');
    const li = document.createElement('li');
    li.innerHTML = `<strong>${title}:</strong> ${value} - ${description}`;
    insightsList.appendChild(li);
};

// Example usage
analyticsEngine.addCustomInsight(
    "Longest Lineage", 
    "10 generations", 
    "From Adam to Noah"
);

Chart Customization

// Customize chart colors
const customColors = {
    primary: '#007bff',
    secondary: '#6c757d',
    success: '#28a745',
    danger: '#dc3545',
    warning: '#ffc107',
    info: '#17a2b8'
};

// Apply to charts
analyticsEngine.chartColors = customColors;

📱 Mobile Optimization

Responsive Features

The CSS includes comprehensive mobile optimizations:

Touch-friendly controls - Larger tap targets
Adaptive layouts - Grid systems that stack on mobile
Optimized charts - Reduced heights and simplified legends
Collapsible sections - Save screen space
Swipe gestures - For navigation (where supported)

Mobile-Specific CSS

@media (max-width: 768px) {
    .family-search-container {
        margin: 10px;
        padding: 15px;
    }
    
    .search-input-wrapper {
        flex-direction: column;
    }
    
    .chart-container {
        height: 250px; /* Reduced from 300px */
    }
    
    .stats-overview {
        grid-template-columns: 1fr; /* Single column on mobile */
    }
}

💾 Export Capabilities

Available Export Formats

SVG Export

function exportSVG() {
    const svg = document.getElementById('tree-svg');
    const svgData = new XMLSerializer().serializeToString(svg);
    const blob = new Blob([svgData], {type: 'image/svg+xml'});
    const url = URL.createObjectURL(blob);
    
    const link = document.createElement('a');
    link.href = url;
    link.download = 'family-tree.svg';
    link.click();
}

PNG Export

function exportPNG() {
    const svg = document.getElementById('tree-svg');
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    
    const data = new XMLSerializer().serializeToString(svg);
    const img = new Image();
    
    img.onload = function() {
        canvas.width = img.width;
        canvas.height = img.height;
        ctx.drawImage(img, 0, 0);
        
        const link = document.createElement('a');
        link.download = 'family-tree.png';
        link.href = canvas.toDataURL();
        link.click();
    };
    
    img.src = 'data:image/svg+xml;base64,' + btoa(data);
}

Data Export

function exportData() {
    // Export search results as CSV
    searchEngine.exportSearchResults();
    
    // Export analytics report
    analyticsEngine.exportAnalyticsReport();
}

🔧 Server-Side Integration

Enhanced Route Handler

Update your server.py to include additional endpoints:

@app.get("/family-tree-enhanced", response_class=HTMLResponse)
def enhanced_family_tree_page(request: Request):
    """Enhanced family tree with advanced features"""
    books = list(bible.iter_books())
    
    # Load GEDCOM data (existing logic)
    static_dir = Path(__file__).parent / "static"
    gedcom_path = static_dir / "adameve.ged"
    
    if not gedcom_path.exists():
        raise HTTPException(status_code=404, detail="GEDCOM file not found")
    
    try:
        family_tree_data = parse_gedcom_to_tree_data(gedcom_path)
        
        # Add enhanced metadata
        enhanced_data = enhance_family_data(family_tree_data)
        
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Failed to parse GEDCOM: {str(e)}")
    
    return templates.TemplateResponse(
        "enhanced_family_tree.html",
        {
            "request": request,
            "books": books,
            "family_tree_data": enhanced_data,
            "analytics_enabled": True,
            "search_enabled": True
        }
    )

def enhance_family_data(family_data):
    """Add enhanced metadata for analytics"""
    for person_id, person in family_data.items():
        # Add generation calculation
        person['generation'] = calculate_generation(person_id, family_data)
        
        # Add relationship metrics
        person['relationship_count'] = len(person.get('children', [])) + len(person.get('parents', []))
        
        # Add search keywords
        person['search_keywords'] = generate_search_keywords(person)
    
    return family_data

API Endpoints

Add these endpoints for dynamic data:

@app.get("/api/family-tree/search")
def search_family_tree(q: str, filters: str = None):
    """Search family tree data"""
    # Implement server-side search
    pass

@app.get("/api/family-tree/analytics")
def get_family_analytics():
    """Get pre-computed analytics"""
    # Return analytics data
    pass

@app.post("/api/family-tree/bookmark")
def save_bookmark(person_id: str, user_id: str = None):
    """Save user bookmark"""
    # Implement bookmark persistence
    pass

🎯 Performance Optimization

Large Dataset Handling

For families with 1000+ members:

// Implement pagination
const CHUNK_SIZE = 100;

function loadDataInChunks(familyData) {
    const chunks = Object.keys(familyData).reduce((acc, key, index) => {
        const chunkIndex = Math.floor(index / CHUNK_SIZE);
        if (!acc[chunkIndex]) acc[chunkIndex] = {};
        acc[chunkIndex][key] = familyData[key];
        return acc;
    }, []);
    
    return chunks;
}

// Lazy loading for search
searchEngine.enableLazyLoading = true;
searchEngine.chunkSize = CHUNK_SIZE;

Memory Management

// Clean up on layout switch
function cleanupLayout() {
    if (advancedLayouts.simulation) {
        advancedLayouts.simulation.stop();
    }
    
    // Clear D3 selections
    d3.select("#tree-svg").selectAll("*").remove();
    
    // Clear analytics charts
    Object.values(analyticsEngine.chartInstances).forEach(chart => {
        if (chart) chart.destroy();
    });
}

🧪 Testing

Unit Tests

// Test layout switching
describe('AdvancedTreeLayouts', () => {
    let layouts;
    
    beforeEach(() => {
        layouts = new AdvancedTreeLayouts(mockSvg, mockFamilyData);
    });
    
    test('should switch to radial layout', () => {
        layouts.renderRadialLayout('adam');
        expect(layouts.getCurrentLayout()).toBe('radial');
    });
    
    test('should center view', () => {
        const spy = jest.spyOn(layouts, 'centerView');
        layouts.centerView();
        expect(spy).toHaveBeenCalled();
    });
});

// Test search functionality
describe('FamilyTreeSearch', () => {
    test('should find persons by name', () => {
        const results = searchEngine.performSearch('adam');
        expect(results.length).toBeGreaterThan(0);
        expect(results[0].name.toLowerCase()).toContain('adam');
    });
});

Integration Tests

# Test enhanced family tree endpoint
def test_enhanced_family_tree_endpoint(client):
    response = client.get("/family-tree-enhanced")
    assert response.status_code == 200
    assert "Enhanced Family Tree" in response.text
    assert "advanced-tree-layouts.js" in response.text

🚨 Troubleshooting

Common Issues

1. Charts Not Rendering

// Check if Chart.js is loaded
if (typeof Chart === 'undefined') {
    console.error('Chart.js not loaded');
    // Load Chart.js dynamically
    const script = document.createElement('script');
    script.src = 'https://cdn.jsdelivr.net/npm/chart.js';
    document.head.appendChild(script);
}

2. D3.js Layout Issues

// Check D3.js version compatibility
if (!d3.version || d3.version.split('.')[0] < '7') {
    console.warn('D3.js v7+ required for full functionality');
}

// Handle missing data gracefully
function safeRenderLayout(personId) {
    if (!familyData[personId]) {
        console.warn('Person not found:', personId);
        return;
    }
    
    try {
        advancedLayouts.renderRadialLayout(personId);
    } catch (error) {
        console.error('Layout render failed:', error);
        // Fallback to hierarchical
        updateD3Tree(familyData[personId], personId);
    }
}

3. Mobile Performance

// Reduce complexity on mobile
function isMobile() {
    return window.innerWidth < 768;
}

if (isMobile()) {
    // Disable complex animations
    advancedLayouts.disableAnimations = true;
    
    // Reduce max nodes
    advancedLayouts.maxNodes = 50;
    
    // Simplify force simulation
    if (advancedLayouts.simulation) {
        advancedLayouts.simulation.force("charge").strength(-100);
    }
}

📈 Future Enhancements

Planned Features

3D Visualization - Three.js integration for 3D family trees
Virtual Reality - WebXR support for immersive exploration
Collaborative Features - Real-time collaboration on family trees
AI Insights - Machine learning for relationship discovery
Blockchain Integration - Immutable family records

Extension Points

// Plugin system for custom layouts
AdvancedTreeLayouts.registerPlugin = function(name, plugin) {
    this.plugins[name] = plugin;
};

// Custom analytics modules
FamilyTreeAnalytics.addModule = function(name, module) {
    this.modules[name] = module;
};

// Search providers
FamilyTreeSearch.addProvider = function(name, provider) {
    this.providers[name] = provider;
};

📚 Resources

Documentation

Examples

See enhanced_family_tree.html for complete integration example
Check browser developer tools for debugging layout issues
Use the demo controls to test all features

Support

File issues in the project repository
Check console for error messages
Test in latest Chrome/Firefox for best compatibility

🎉 Conclusion

This expansion transforms the basic family tree into a comprehensive genealogy exploration tool with:

5 different layout algorithms for varied perspectives
Advanced search capabilities with real-time filtering
Statistical insights through interactive charts
Mobile-optimized interface for all devices
Export capabilities for sharing and archiving

The modular design allows for gradual implementation and easy customization for specific biblical genealogy needs.

Next Steps:

Implement basic integration following the Quick Start guide
Customize styling to match your application theme
Add server-side endpoints for persistence
Test thoroughly across different devices
Consider performance optimizations for large datasets

The enhanced family tree will significantly improve user engagement and provide valuable insights into biblical genealogies and family relationships.

18 KiB Raw Blame History