igny8/TEMPLATE_SYSTEM_EXPLANATION.md

# Template System - Current State & Plans

## Current Template Architecture

### 1. Site-Level Layouts (Implemented)
**Location**: `sites/src/utils/layoutRenderer.tsx`

**Available Layouts**:
- `default` - Standard header, content, footer
- `minimal` - Clean, minimal design
- `magazine` - Editorial, content-focused
- `ecommerce` - Product-focused
- `portfolio` - Showcase layout
- `blog` - Content-first
- `corporate` - Business layout

**How it works**:
- Set in `SiteBlueprint.structure_json.layout`
- Applied to the entire site
- All pages use the same layout

### 2. Block Templates (Implemented)
**Location**: `sites/src/utils/templateEngine.tsx`

**Available Block Types**:
- `hero` - Hero section with title, subtitle, CTA
- `text` - Text content block
- `features` - Feature grid
- `testimonials` - Testimonials section
- `services` - Services grid
- `stats` - Statistics panel
- `cta` - Call to action
- `image` - Image block
- `video` - Video block
- `form` - Contact form
- `faq` - FAQ accordion
- `quote` - Quote block
- `grid` - Grid layout
- `card` - Card block
- `list` - List block
- `accordion` - Accordion block

**How it works**:
- Each page has `blocks_json` array
- Each block has `type` and `data`
- `renderTemplate()` renders blocks based on type

### 3. Page Types (Defined, but NO templates yet)
**Location**: `backend/igny8_core/business/site_building/models.py`

**Page Type Choices**:
- `home` - Homepage
- `about` - About page
- `services` - Services page
- `products` - Products page
- `blog` - Blog page
- `contact` - Contact page
- `custom` - Custom page

**Current State**: 
- Page types are stored but **NOT used for rendering**
- All pages render the same way regardless of type
- No page-type-specific templates exist

## Missing: Page-Type Templates

### What's Missing
Currently, there's **NO page-type-specific template system**. All pages render identically:
- Home page renders the same as Products page
- Blog page renders the same as Contact page
- No special handling for different page types

### Where Page-Type Templates Should Be

**Proposed Location**: `sites/src/utils/pageTypeRenderer.tsx`

**Proposed Structure**:
```typescript
// Page-type specific renderers
function renderHomePage(page: PageDefinition, blocks: Block[]): React.ReactElement {
  // Home-specific template: Hero, features, testimonials, CTA
}

function renderProductsPage(page: PageDefinition, blocks: Block[]): React.ReactElement {
  // Products-specific template: Product grid, filters, categories
}

function renderBlogPage(page: PageDefinition, blocks: Block[]): React.ReactElement {
  // Blog-specific template: Post list, sidebar, pagination
}

function renderContactPage(page: PageDefinition, blocks: Block[]): React.ReactElement {
  // Contact-specific template: Form, map, contact info
}
```

### How It Should Work

1. **In `layoutRenderer.tsx`**: After determining site layout, check page type
2. **Route to page-type renderer**: If page type has specific template, use it
3. **Fallback to default**: If no page-type template, use default block rendering

**Example Flow**:
```
Site Definition → Site Layout (default/minimal/etc.)
  ↓
Page Type (home/products/blog/etc.)
  ↓
Page-Type Template (if exists) OR Default Block Rendering
  ↓
Block Templates (hero/text/features/etc.)
```

## Current Rendering Flow

```
SiteRenderer
  ↓
loadSiteDefinition()
  ↓
renderLayout(siteDefinition) → Uses site.layout (default/minimal/etc.)
  ↓
renderDefaultLayout() → Renders all pages the same way
  ↓
renderTemplate(block) → Renders individual blocks
```

## Proposed Enhanced Flow

```
SiteRenderer
  ↓
loadSiteDefinition()
  ↓
renderLayout(siteDefinition) → Uses site.layout
  ↓
For each page:
  ↓
  Check page.type (home/products/blog/etc.)
  ↓
  If page-type template exists:
    → renderPageTypeTemplate(page)
  Else:
    → renderDefaultPageTemplate(page)
  ↓
  renderTemplate(block) → Renders blocks
```

## Implementation Plan

### Phase 1: Create Page-Type Renderers
- Create `sites/src/utils/pageTypeRenderer.tsx`
- Implement templates for each page type:
  - `home` - Hero + features + testimonials layout
  - `products` - Product grid + filters
  - `blog` - Post list + sidebar
  - `contact` - Form + map + info
  - `about` - Team + mission + values
  - `services` - Service cards + descriptions

### Phase 2: Integrate with Layout Renderer
- Modify `renderDefaultLayout()` to check page type
- Route to page-type renderer if template exists
- Fallback to current block rendering

### Phase 3: Make Templates Configurable
- Allow templates to be customized per site
- Store template preferences in `SiteBlueprint.config_json`
- Support custom templates

## Current Files

- **Site Layouts**: `sites/src/utils/layoutRenderer.tsx`
- **Block Templates**: `sites/src/utils/templateEngine.tsx`
- **Page Types**: `backend/igny8_core/business/site_building/models.py` (PageBlueprint.PAGE_TYPE_CHOICES)
- **Missing**: Page-type templates (not implemented yet)

## Summary

✅ **Implemented**: Site-level layouts, block templates
❌ **Missing**: Page-type-specific templates
📝 **Planned**: Page-type renderers in `sites/src/utils/pageTypeRenderer.tsx`

Currently, all pages render the same way. Page types are stored but not used for rendering. To add page-type templates, create a new file `pageTypeRenderer.tsx` and integrate it into the layout renderer.