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

Vendor Landing Pages

Complete guide to creating custom landing pages for vendor storefronts.

Overview

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

URL Structure

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

E-commerce Shop:
- Custom Domain:   https://customdomain.com/shop/      → Shop Homepage
- Subdomain:       https://wizamart.platform.com/shop/ → Shop Homepage
- Path-based:      http://localhost:8000/vendors/wizamart/shop/ → Shop Homepage

Features

✅ Multiple Templates: Choose from 4 different landing page designs ✅ CMS-Powered: Content managed through ContentPage model ✅ Per-Vendor Customization: Each vendor can have unique design ✅ Auto-Fallback: Redirects to shop if no landing page exists ✅ Theme-Aware: Uses vendor'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 vendors, 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

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

landing_page = ContentPage(
    vendor_id=1,  # Your vendor 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:

<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 /shop/

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

Template Variables

All templates have access to:

From Request Context

{
    "vendor": Vendor object,
    "theme": Theme object with colors/branding,
    "base_url": "/" or "/vendors/{code}/",
    "page": ContentPage object,
    "header_pages": List of header navigation pages,
    "footer_pages": List of footer navigation pages
}

Vendor Properties

{{ vendor.name }}
{{ vendor.tagline }}
{{ vendor.description }}
{{ vendor.website }}

Theme Properties

{{ theme.branding.logo }}
{{ theme.branding.logo_dark }}
{{ theme.colors.primary }}
{{ theme.colors.accent }}

Page Properties

{{ page.title }}
{{ page.content | safe }}
{{ page.meta_description }}
{{ page.template }}

Migration Applied

Database migration f68d8da5315a adds template field to content_pages table:

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

API Endpoints

Get Landing Page

GET /api/v1/shop/content-pages/landing
Referer: https://wizamart.platform.com/

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

Testing

Test Landing Page

1. Create a landing page via database or admin panel
2. Access vendor root URL:
   • Path-based: http://localhost:8000/vendors/wizamart/
   • Subdomain: https://wizamart.platform.com/
3. Should see your custom landing page

Test Fallback

1. Delete or unpublish landing page
2. Access vendor root URL
3. Should redirect to /shop/

Customization Guide

Adding a New Template

1. Create new template file:

   app/templates/vendor/landing-{name}.html
   

2. Extend shop base:

   {% extends "shop/base.html" %}
   

3. Use template variables as needed

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

Modifying Existing Templates

Templates are in:

app/templates/vendor/
├── 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 /shop/ for e-commerce

4. Use Theme Colors: Templates automatically use vendor theme

5. Test Responsiveness: All templates are mobile-friendly

6. SEO: Fill in meta_description for better search results

Examples

Example 1: Simple Store

ContentPage(
    vendor_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

ContentPage(
    vendor_id=2,
    slug="landing",
    title="John's Artwork",
    content="<p>Handcrafted pieces since 2015</p>",
    template="minimal",
    is_published=True
)

Example 3: Modern Brand

ContentPage(
    vendor_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 vendor ID matches
• Verify template field is valid

Wrong Template Rendering

• Check template field value
• Ensure template file exists at app/templates/vendor/landing-{template}.html
• Check for typos in template name

Theme Colors Not Applied

• Verify vendor 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 vendors to build completely custom layouts without template limitations.