orion/docs/features/store-landing-pages.md

# Store Landing Pages

Complete guide to creating custom landing pages for store storefronts.

## Overview

Each store can have a custom landing page at their root URL with different design templates. This landing page serves as the store's homepage, separate from the e-commerce storefront section.

### URL Structure

```
Root Landing Page:
- Custom Domain:   https://customdomain.com/           → Landing Page
- Subdomain:       https://orion.platform.com/      → Landing Page
- Path-based:      http://localhost:8000/stores/orion/ → Landing Page

E-commerce Storefront:
- Custom Domain:   https://customdomain.com/storefront/      → Storefront Homepage
- Subdomain:       https://orion.platform.com/storefront/ → Storefront Homepage
- Path-based:      http://localhost:8000/storefront/orion/ → Storefront Homepage
```

## Features

✅ **Multiple Templates**: Choose from 4 different landing page designs
✅ **CMS-Powered**: Content managed through ContentPage model
✅ **Per-Store Customization**: Each store can have unique design
✅ **Auto-Fallback**: Redirects to storefront if no landing page exists
✅ **Theme-Aware**: Uses store's theme colors and branding

## Available Templates

### 1. **Default** (`landing-default.html`)
- Clean and professional
- Hero section with logo and CTA
- Optional content section
- Quick links grid (3 cards)
- **Best for**: General purpose, simple storefronts

### 2. **Minimal** (`landing-minimal.html`)
- Ultra-simple centered design
- Single page, no scrolling
- One primary CTA
- Minimal navigation
- **Best for**: Single-product stores, portfolio sites

### 3. **Modern** (`landing-modern.html`)
- Full-screen hero with animations
- Feature showcase section
- Gradient backgrounds
- Multiple CTAs
- **Best for**: Tech products, modern brands

### 4. **Full** (`landing-full.html`)
- Split-screen hero layout
- Stats/badges section
- 4-feature grid
- Multiple content sections
- Final CTA section
- **Best for**: Established brands, full product catalogs

## How to Create a Landing Page

### Step 1: Create ContentPage in Database

```python
# Using Python/SQL
from models.database.content_page import ContentPage

landing_page = ContentPage(
    store_id=1,  # Your store ID
    slug="landing",  # Must be "landing" or "home"
    title="Welcome to Our Store",
    content="<p>Your custom HTML content here...</p>",
    template="modern",  # Choose: default, minimal, modern, full
    is_published=True,
    show_in_footer=False,
    show_in_header=False
)
db.add(landing_page)
db.commit()
```

### Step 2: Choose Template

Set the `template` field to one of:
- `"default"` - Clean professional layout
- `"minimal"` - Ultra-simple centered design
- `"modern"` - Full-screen with animations
- `"full"` - Maximum features and sections

### Step 3: Add Content (Optional)

The `content` field supports HTML. This appears in a dedicated section on all templates:

```html
<h2>About Our Store</h2>
<p>We've been serving customers since 2020...</p>
<ul>
  <li>Quality products</li>
  <li>Fast shipping</li>
  <li>Great customer service</li>
</ul>
```

### Step 4: Publish

Set `is_published=True` to make the landing page live.

## Fallback Behavior

If no landing page exists:
1. System checks for `slug="landing"`
2. If not found, checks for `slug="home"`
3. If neither exists, **redirects to `/storefront/`**

This ensures stores always have a working homepage even without a landing page.

## Template Variables

All templates have access to:

### From Request Context
```python
{
    "store": Store object,
    "theme": Theme object with colors/branding,
    "base_url": "/" or "/stores/{code}/",
    "page": ContentPage object,
    "header_pages": List of header navigation pages,
    "footer_pages": List of footer navigation pages
}
```

### Store Properties
```jinja2
{{ store.name }}
{{ store.tagline }}
{{ store.description }}
{{ store.website }}
```

### Theme Properties
```jinja2
{{ theme.branding.logo }}
{{ theme.branding.logo_dark }}
{{ theme.colors.primary }}
{{ theme.colors.accent }}
```

### Page Properties
```jinja2
{{ page.title }}
{{ page.content | safe }}
{{ page.meta_description }}
{{ page.template }}
```

## Migration Applied

Database migration `f68d8da5315a` adds `template` field to `content_pages` table:

```sql
ALTER TABLE content_pages
ADD COLUMN template VARCHAR(50) NOT NULL DEFAULT 'default';
```

## API Endpoints

### Get Landing Page
```http
GET /api/v1/storefront/content-pages/landing
Referer: https://orion.platform.com/

Response:
{
  "id": 1,
  "slug": "landing",
  "title": "Welcome to Orion",
  "content": "<p>...</p>",
  "template": "modern",
  "is_published": true
}
```

## Testing

### Test Landing Page
1. Create a landing page via database or admin panel
2. Access store root URL:
   - Path-based: `http://localhost:8000/stores/orion/`
   - Subdomain: `https://orion.platform.com/`
3. Should see your custom landing page

### Test Fallback
1. Delete or unpublish landing page
2. Access store root URL
3. Should redirect to `/storefront/`

## Customization Guide

### Adding a New Template

1. Create new template file:
   ```
   app/templates/store/landing-{name}.html
   ```

2. Extend storefront base:
   ```jinja2
   {% extends "storefront/base.html" %}
   ```

3. Use template variables as needed

4. Update `page.template` to `{name}` in database

### Modifying Existing Templates

Templates are in:
```
app/templates/store/
├── landing-default.html   (Clean professional)
├── landing-minimal.html   (Ultra-simple)
├── landing-modern.html    (Full-screen hero)
└── landing-full.html      (Maximum features)
```

Edit directly and changes apply immediately (no rebuild needed).

## Best Practices

1. **Choose Template Based on Content**:
   - Minimal: Little content, single CTA
   - Default: Moderate content, professional
   - Modern: Tech/modern brands, animated
   - Full: Lots of content, established brand

2. **Keep Content Concise**: Landing pages should be scannable

3. **Strong CTAs**: Always link to `/storefront/` for e-commerce

4. **Use Theme Colors**: Templates automatically use store theme

5. **Test Responsiveness**: All templates are mobile-friendly

6. **SEO**: Fill in `meta_description` for better search results

## Examples

### Example 1: Simple Store
```python
ContentPage(
    store_id=1,
    slug="landing",
    title="Welcome to TechStore",
    content="<p>Your one-stop shop for electronics</p>",
    template="default",
    is_published=True
)
```

### Example 2: Portfolio Site
```python
ContentPage(
    store_id=2,
    slug="landing",
    title="John's Artwork",
    content="<p>Handcrafted pieces since 2015</p>",
    template="minimal",
    is_published=True
)
```

### Example 3: Modern Brand
```python
ContentPage(
    store_id=3,
    slug="landing",
    title="FutureWear - Style Redefined",
    content="<h2>Our Story</h2><p>Innovation meets fashion...</p>",
    template="modern",
    is_published=True
)
```

## Troubleshooting

### Landing Page Not Showing
- Check `is_published=True`
- Verify `slug="landing"` or `slug="home"`
- Check store ID matches
- Verify template field is valid

### Wrong Template Rendering
- Check `template` field value
- Ensure template file exists at `app/templates/store/landing-{template}.html`
- Check for typos in template name

### Theme Colors Not Applied
- Verify store has theme configured
- Check CSS variables in template: `var(--color-primary)`
- Inspect theme object in template context

## Future Enhancements

**Phase 2: Section Builder** (Future)
- Drag-and-drop section components
- Hero, Features, Testimonials, Gallery sections
- Per-section customization
- Visual page builder interface

This will allow stores to build completely custom layouts without template limitations.