feat: implement vendor landing pages with multi-template support and fix shop routing
Major improvements to shop URL routing and vendor landing page system:
## Landing Page System
- Add template field to ContentPage model for flexible landing page designs
- Create 4 landing page templates: default, minimal, modern, and full
- Implement smart root handler to serve landing pages or redirect to shop
- Add create_landing_page.py script for easy landing page management
- Support both domain/subdomain and path-based vendor access
- Add comprehensive landing page documentation
## Route Fixes
- Fix duplicate /shop prefix in shop_pages.py routes
- Correct product detail page routing (was /shop/shop/products/{id})
- Update all shop routes to work with router prefix mounting
- Remove unused public vendor endpoints (/api/v1/public/vendors)
## Template Link Corrections
- Fix all shop template links to include /shop/ prefix
- Update breadcrumb 'Home' links to point to vendor root (landing page)
- Update header navigation 'Home' link to point to vendor root
- Correct CMS page links in footer navigation
- Fix account, cart, and error page navigation links
## Navigation Architecture
- Establish two-tier navigation: landing page (/) and shop (/shop/)
- Document complete navigation flow and URL hierarchy
- Support for vendors with or without landing pages (auto-redirect fallback)
- Consistent breadcrumb and header navigation behavior
## Documentation
- Add vendor-landing-pages.md feature documentation
- Add navigation-flow.md with complete URL hierarchy
- Update shop architecture docs with error handling section
- Add orphaned docs to mkdocs.yml navigation
- Document multi-access routing patterns
## Database
- Migration f68d8da5315a: add template field to content_pages table
- Support template values: default, minimal, modern, full
This establishes a complete landing page system allowing vendors to have
custom marketing homepages separate from their e-commerce shop, with
flexible template options and proper navigation hierarchy.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
313
docs/features/vendor-landing-pages.md
Normal file
313
docs/features/vendor-landing-pages.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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:
|
||||
|
||||
```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 `/shop/`**
|
||||
|
||||
This ensures vendors always have a working homepage even without a landing page.
|
||||
|
||||
## Template Variables
|
||||
|
||||
All templates have access to:
|
||||
|
||||
### From Request Context
|
||||
```python
|
||||
{
|
||||
"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
|
||||
```jinja2
|
||||
{{ vendor.name }}
|
||||
{{ vendor.tagline }}
|
||||
{{ vendor.description }}
|
||||
{{ vendor.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/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:
|
||||
```jinja2
|
||||
{% 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
|
||||
```python
|
||||
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
|
||||
```python
|
||||
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
|
||||
```python
|
||||
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.
|
||||
Reference in New Issue
Block a user