mirror of https://github.com/ColorlibHQ/gentelella
321 lines
8.8 KiB
Markdown
321 lines
8.8 KiB
Markdown
# HTML Componentization Gameplan
|
|
*Saved for future implementation*
|
|
|
|
## **Executive Summary**
|
|
|
|
**Problem**: 40+ HTML files with 80% duplicate code (sidebar, header, footer, navigation)
|
|
**Solution**: Extract common components into reusable templates
|
|
**Impact**: Dramatically improve maintainability, development speed, and consistency
|
|
|
|
---
|
|
|
|
## **Current Structure Analysis**
|
|
|
|
### **Repeating Components Identified**
|
|
1. **HTML Head Section** (~15 lines)
|
|
- Meta tags, title, Vite imports
|
|
- Same across all files except page-specific titles
|
|
|
|
2. **Sidebar Navigation** (~140 lines)
|
|
- Logo and branding
|
|
- User profile section
|
|
- Main navigation menu
|
|
- Sidebar footer buttons
|
|
|
|
3. **Top Navigation** (~120 lines)
|
|
- Hamburger menu toggle
|
|
- User profile dropdown
|
|
- Notifications dropdown
|
|
- Messages list
|
|
|
|
4. **Footer** (~10 lines)
|
|
- Copyright and attribution
|
|
- Consistent across all pages
|
|
|
|
5. **Body Wrapper Structure** (~20 lines)
|
|
- Container and layout divs
|
|
- Same Bootstrap 5 structure
|
|
|
|
### **Code Duplication Stats**
|
|
- **Total Files**: 40+ HTML files
|
|
- **Duplicate Code**: ~80% (300+ lines per file)
|
|
- **Unique Content**: ~20% (varying by page complexity)
|
|
- **Maintenance Burden**: Updates require touching 40+ files
|
|
|
|
---
|
|
|
|
## **Implementation Options**
|
|
|
|
### **Option 1: Template Engine (Recommended)**
|
|
**Technology**: Eleventy (11ty) or Handlebars
|
|
**Benefits**: Static generation, great documentation, minimal learning curve
|
|
|
|
```html
|
|
<!-- layouts/base.html -->
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
{{> head title=title }}
|
|
</head>
|
|
<body class="nav-md">
|
|
<div class="container body">
|
|
<div class="main_container">
|
|
{{> sidebar activeMenu=activeMenu }}
|
|
{{> topnav user=user }}
|
|
|
|
<div class="right_col" role="main">
|
|
<div class="page_title">
|
|
<div class="title_left">
|
|
<h3>{{title}}</h3>
|
|
</div>
|
|
</div>
|
|
<div class="clearfix"></div>
|
|
|
|
{{{ content }}}
|
|
</div>
|
|
|
|
{{> footer }}
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
### **Option 2: Server-Side Includes**
|
|
**Technology**: PHP includes or SSI
|
|
**Benefits**: Simple, widely supported
|
|
|
|
```php
|
|
<?php
|
|
$pageTitle = "Dashboard";
|
|
$activeMenu = "home";
|
|
include 'components/head.php';
|
|
?>
|
|
<body class="nav-md">
|
|
<?php include 'components/sidebar.php'; ?>
|
|
<?php include 'components/topnav.php'; ?>
|
|
|
|
<!-- Page content here -->
|
|
|
|
<?php include 'components/footer.php'; ?>
|
|
</body>
|
|
```
|
|
|
|
### **Option 3: Build Script**
|
|
**Technology**: Node.js build script
|
|
**Benefits**: Custom control, integrates with existing Vite setup
|
|
|
|
```javascript
|
|
// build-components.js
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
|
|
function buildPage(pageContent, config) {
|
|
const template = fs.readFileSync('templates/base.html', 'utf8');
|
|
const sidebar = fs.readFileSync('components/sidebar.html', 'utf8');
|
|
const topnav = fs.readFileSync('components/topnav.html', 'utf8');
|
|
const footer = fs.readFileSync('components/footer.html', 'utf8');
|
|
|
|
return template
|
|
.replace('{{sidebar}}', sidebar)
|
|
.replace('{{topnav}}', topnav)
|
|
.replace('{{footer}}', footer)
|
|
.replace('{{content}}', pageContent)
|
|
.replace('{{title}}', config.title)
|
|
.replace('{{activeMenu}}', config.activeMenu);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## **Implementation Plan**
|
|
|
|
### **Phase 1: Component Extraction**
|
|
**Duration**: 2-3 hours
|
|
|
|
1. **Create directory structure**:
|
|
```
|
|
components/
|
|
├── head.html
|
|
├── sidebar.html
|
|
├── topnav.html
|
|
└── footer.html
|
|
|
|
templates/
|
|
└── base.html
|
|
|
|
pages/
|
|
├── dashboard-content.html
|
|
├── forms-content.html
|
|
└── ... (page-specific content)
|
|
```
|
|
|
|
2. **Extract sidebar component** (lines 21-160 from existing files):
|
|
```html
|
|
<!-- components/sidebar.html -->
|
|
<div class="col-md-3 left_col">
|
|
<div class="left_col scroll-view">
|
|
<!-- navbar brand -->
|
|
<div class="navbar nav_title" style="border: 0;">
|
|
<a href="index.html" class="site_title">
|
|
<i class="fas fa-paw"></i> <span>Gentelella Alela!</span>
|
|
</a>
|
|
</div>
|
|
<!-- ... rest of sidebar -->
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
3. **Extract other components** following the same pattern
|
|
|
|
### **Phase 2: Template System Setup**
|
|
**Duration**: 1-2 hours
|
|
|
|
1. **Install template engine**:
|
|
```bash
|
|
npm install @11ty/eleventy --save-dev
|
|
```
|
|
|
|
2. **Configure build process**:
|
|
```javascript
|
|
// .eleventy.js
|
|
module.exports = function(eleventyConfig) {
|
|
eleventyConfig.addPassthroughCopy("src");
|
|
eleventyConfig.addPassthroughCopy("images");
|
|
|
|
return {
|
|
dir: {
|
|
input: "pages",
|
|
output: "production",
|
|
includes: "../components",
|
|
layouts: "../templates"
|
|
}
|
|
};
|
|
};
|
|
```
|
|
|
|
### **Phase 3: Convert Pages**
|
|
**Duration**: 4-6 hours
|
|
|
|
1. **Start with simple pages**:
|
|
- `plain_page.html` → `pages/plain-page.md`
|
|
- `page_404.html` → `pages/404.md`
|
|
|
|
2. **Convert dashboard pages**:
|
|
- Extract unique content from `index.html`, `index2.html`, `index3.html`
|
|
- Create page-specific data files for dynamic content
|
|
|
|
3. **Handle complex pages**:
|
|
- `form_advanced.html` (lots of unique JavaScript)
|
|
- `tables_dynamic.html` (DataTables integration)
|
|
|
|
### **Phase 4: Dynamic Features**
|
|
**Duration**: 2-3 hours
|
|
|
|
1. **Active menu highlighting**:
|
|
```html
|
|
<li class="{{#if (eq activeMenu 'home')}}active{{/if}}">
|
|
<a href="index.html">Dashboard</a>
|
|
</li>
|
|
```
|
|
|
|
2. **Page-specific titles and meta tags**:
|
|
```yaml
|
|
---
|
|
title: "Dashboard - Gentelella"
|
|
description: "Main dashboard overview"
|
|
activeMenu: "home"
|
|
scripts: ["dashboard-specific.js"]
|
|
---
|
|
```
|
|
|
|
3. **Conditional content**:
|
|
```html
|
|
{{#if showNotifications}}
|
|
{{> notifications-dropdown}}
|
|
{{/if}}
|
|
```
|
|
|
|
---
|
|
|
|
## **Benefits After Implementation**
|
|
|
|
### **Immediate Benefits**
|
|
- **Single Point of Updates**: Change navigation in one file, applies everywhere
|
|
- **Consistency Guaranteed**: No more forgetting to update one file
|
|
- **Development Speed**: New pages only need content, not full HTML structure
|
|
- **Bug Fixes**: Fix header/sidebar issues once, not 40+ times
|
|
|
|
### **Long-term Benefits**
|
|
- **Easy Rebranding**: Logo, colors, layout changes in components only
|
|
- **A/B Testing**: Test different navigation layouts easily
|
|
- **Team Collaboration**: Multiple developers can work without conflicts
|
|
- **Scalability**: Add new pages without duplicating boilerplate
|
|
|
|
### **Technical Benefits**
|
|
- **Smaller Git Diffs**: Only content changes tracked, not structure
|
|
- **Better Caching**: Separate content from layout for browser caching
|
|
- **SEO Improvements**: Consistent meta tags and structure
|
|
- **Accessibility**: Implement improvements across all pages simultaneously
|
|
|
|
---
|
|
|
|
## **Migration Strategy**
|
|
|
|
### **Risk Mitigation**
|
|
1. **Backup Strategy**: Keep original files in `production-backup/`
|
|
2. **Gradual Migration**: Convert 5-10 pages at a time
|
|
3. **Testing Protocol**: Compare generated vs original HTML
|
|
4. **Rollback Plan**: Git branches for easy reversion
|
|
|
|
### **Quality Assurance**
|
|
1. **Visual Regression Testing**: Screenshot comparison
|
|
2. **Functionality Testing**: Ensure all JavaScript still works
|
|
3. **Responsive Testing**: Mobile/tablet layouts intact
|
|
4. **Cross-browser Testing**: Same compatibility as originals
|
|
|
|
### **Performance Considerations**
|
|
1. **Build Time**: Template compilation should be fast (<5 seconds)
|
|
2. **Output Size**: Generated HTML should be identical in size
|
|
3. **Development Speed**: Hot reload for template changes
|
|
4. **Maintenance**: Clear documentation for future developers
|
|
|
|
---
|
|
|
|
## **Recommended Next Steps**
|
|
|
|
### **When Ready to Implement**
|
|
1. **Start Small**: Begin with 3-5 simple pages (plain_page, 404, etc.)
|
|
2. **Choose Technology**: Recommend Eleventy for its simplicity
|
|
3. **Set Timeline**: Allocate 1-2 days for full implementation
|
|
4. **Team Training**: Ensure team understands new workflow
|
|
|
|
### **Prerequisites**
|
|
- [ ] Backup current production files
|
|
- [ ] Choose template engine (Eleventy recommended)
|
|
- [ ] Set up development environment
|
|
- [ ] Plan testing strategy
|
|
|
|
---
|
|
|
|
## **ROI Analysis**
|
|
|
|
### **Time Investment**
|
|
- **Initial Setup**: 8-12 hours (one-time)
|
|
- **Learning Curve**: 2-4 hours (one-time)
|
|
|
|
### **Time Savings**
|
|
- **Per Navigation Update**: From 2 hours → 5 minutes (96% reduction)
|
|
- **New Page Creation**: From 30 minutes → 5 minutes (83% reduction)
|
|
- **Bug Fixes**: From 1-2 hours → 10 minutes (90% reduction)
|
|
|
|
### **Annual Savings** (estimated)
|
|
- **Development Time**: 40-60 hours saved per year
|
|
- **QA Time**: 20-30 hours saved per year
|
|
- **Bug Prevention**: Fewer inconsistency issues
|
|
|
|
**Total ROI**: 500-800% return on initial investment within first year
|
|
|
|
---
|
|
|
|
*This gameplan provides a complete roadmap for componentizing the Gentelella HTML files. Implementation can begin whenever the team is ready to modernize the development workflow.* |