# Module Page Templates Architecture ## Overview This system allows admins to select pre-designed layouts for module pages (e-commerce, booking, listings, payments) while automatically inheriting the website's theme styling (colors, typography, spacing). **Key Concept:** Fixed layouts + Dynamic theme styling + Shared header/footer --- ## 1. Core Principles ### 1.1 Fixed Layouts, Dynamic Styling - **Layouts are NOT drag-and-drop** - they're pre-designed for each module - **Styling follows theme** - colors, fonts, spacing from Website Customizer - **Multiple layout options** - 2-3 variations per module page type ### 1.2 Module Page Types #### E-Commerce Module - **Product Listing** - Grid display (3-col, 4-col variants) - **Product Details** - 3 layouts: - Layout 1: Modern single column - Layout 2: Sidebar with gallery - Layout 3: Split screen (image left, details right) - **Cart Page** - 2 layouts: - Sidebar cart (items left, summary right) - Full-width cart (items top, summary bottom) - **Checkout Page** - 2 layouts: - Single-page checkout - Multi-step checkout #### Booking Module - **Booking Form** - 2 layouts: - Vertical form layout - Horizontal calendar layout - **Booking Details** - 1 layout: - Standard confirmation layout #### Listing Module - **Listing Grid** - Display all listings - **Listing Details** - 2 layouts: - Layout 1: Gallery top, details below - Layout 2: Split view #### Payment Module (Centralized) - **Payment Page** - 1 layout: - Centered payment form - Works for all modules (e-commerce, booking, payment forms) --- ## 2. Database Schema ### 2.1 Add to `websites.settings` JSON Column ```json { "theme": { "colors": { "primary": "#3B82F6", "secondary": "#10B981", "text": "#1F2937", "background": "#FFFFFF", "border": "#E5E7EB", "success": "#10B981", "error": "#EF4444", "warning": "#F59E0B" }, "typography": { "heading_font": "Inter", "body_font": "Inter", "heading_weight": "700", "body_weight": "400", "heading_size": "2.5rem", "body_size": "1rem", "line_height": "1.6" }, "spacing": { "container_width": "1200px", "section_padding": "80px", "element_gap": "1.5rem" }, "borders": { "radius": "8px", "width": "1px" }, "shadows": { "card": "0 4px 6px rgba(0,0,0,0.1)", "button": "0 2px 4px rgba(0,0,0,0.1)" } }, "module_layouts": { "product_listing": "grid-3col", "product_details": "layout-1", "cart_page": "sidebar-cart", "checkout_page": "single-page", "booking_form": "vertical-form", "booking_details": "standard", "listing_grid": "grid-3col", "listing_details": "gallery-top", "payment_page": "centered" } } ``` ### 2.2 No New Tables Required - All settings stored in existing `websites.settings` JSON column - Layout selections stored in `module_layouts` key - Theme settings stored in `theme` key --- ## 3. File Structure ``` app/ ├── Services/ │ ├── ThemeService.php (existing - will extend) │ └── ModuleLayoutService.php (NEW) │ ├── Http/Controllers/ │ ├── ModuleLayoutController.php (NEW - for customizer) │ └── Public/ │ ├── EcommerceController.php (existing - update) │ ├── BookingController.php (existing - update) │ ├── ListingController.php (existing - update) │ └── PaymentController.php (existing - update) resources/views/ ├── public/ │ ├── layouts/ │ │ ├── module-wrapper.blade.php (NEW - main wrapper with theme) │ │ └── theme-styles.blade.php (NEW - CSS injection) │ │ │ ├── modules/ │ │ ├── ecommerce/ │ │ │ ├── product-listing/ │ │ │ │ ├── grid-3col.blade.php (NEW) │ │ │ │ └── grid-4col.blade.php (NEW) │ │ │ │ │ │ │ ├── product-details/ │ │ │ │ ├── layout-1.blade.php (NEW - modern single) │ │ │ │ ├── layout-2.blade.php (NEW - sidebar gallery) │ │ │ │ └── layout-3.blade.php (NEW - split screen) │ │ │ │ │ │ │ ├── cart/ │ │ │ │ ├── sidebar-cart.blade.php (NEW) │ │ │ │ └── full-width-cart.blade.php (NEW) │ │ │ │ │ │ │ └── checkout/ │ │ │ ├── single-page.blade.php (NEW) │ │ │ └── multi-step.blade.php (NEW) │ │ │ │ │ ├── booking/ │ │ │ ├── booking-form/ │ │ │ │ ├── vertical-form.blade.php (NEW) │ │ │ │ └── calendar-horizontal.blade.php (NEW) │ │ │ │ │ │ │ └── booking-details/ │ │ │ └── standard.blade.php (NEW) │ │ │ │ │ ├── listing/ │ │ │ ├── listing-grid/ │ │ │ │ └── grid-3col.blade.php (NEW) │ │ │ │ │ │ │ └── listing-details/ │ │ │ ├── gallery-top.blade.php (NEW) │ │ │ └── split-view.blade.php (NEW) │ │ │ │ │ └── payment/ │ │ └── payment-page/ │ │ └── centered.blade.php (NEW) │ │ │ └── components/ │ └── module-header.blade.php (NEW - breadcrumbs, etc.) │ ├── customizer/ │ ├── module-layouts.blade.php (NEW - layout selector UI) │ └── partials/ │ └── layout-selector.blade.php (NEW - reusable selector) public/ └── css/ └── module-templates.css (NEW - base module styles) ``` **Total New Files:** ~25 files --- ## 4. How It Works ### 4.1 Request Flow ``` User clicks product → Product Details Page ↓ 1. Route: /products/{slug} ↓ 2. Controller: EcommerceController@showProduct ↓ 3. Gets layout selection: ModuleLayoutService->getLayout('product_details') → Returns: "layout-2" (admin's choice) ↓ 4. Gets theme settings: ThemeService->getTheme($website) → Returns: colors, fonts, spacing ↓ 5. Renders view: modules/ecommerce/product-details/layout-2.blade.php ↓ 6. Wrapped in: layouts/module-wrapper.blade.php → Injects: Header (from page builder) → Injects: Theme CSS variables → Injects: Footer (from page builder) ↓ 7. User sees: Product page with selected layout + theme styling + header/footer ``` ### 4.2 Theme CSS Injection **Theme variables are injected as CSS custom properties:** ```css :root { /* Colors */ --color-primary: #3B82F6; --color-secondary: #10B981; --color-text: #1F2937; --color-background: #FFFFFF; --color-border: #E5E7EB; /* Typography */ --font-heading: 'Inter', sans-serif; --font-body: 'Inter', sans-serif; --size-heading: 2.5rem; --size-body: 1rem; --line-height: 1.6; /* Spacing */ --container-width: 1200px; --spacing-section: 80px; --spacing-gap: 1.5rem; /* Borders */ --border-radius: 8px; --border-width: 1px; } ``` **Module templates use these variables:** ```html

Product Name

``` --- ## 5. Customizer Integration ### 5.1 New Customizer Tab: "Module Layouts" **Location:** `/websites/{website}/customizer` → New tab **UI Structure:** ``` ┌─────────────────────────────────────────────────┐ │ Website Customizer │ ├─────────────────────────────────────────────────┤ │ [ General ] [ Theme ] [ Module Layouts ] [ ... ]│ ├─────────────────────────────────────────────────┤ │ │ │ MODULE LAYOUTS │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ E-Commerce Module │ │ │ ├─────────────────────────────────────────┤ │ │ │ Product Listing │ │ │ │ [ ] 3 Column Grid [x] 4 Column Grid │ │ │ │ │ │ │ │ Product Details Page │ │ │ │ [x] Modern Single │ │ │ │ [ ] Sidebar Gallery │ │ │ │ [ ] Split Screen │ │ │ │ [Preview thumbnail images] │ │ │ │ │ │ │ │ Cart Page │ │ │ │ [x] Sidebar Cart │ │ │ │ [ ] Full Width Cart │ │ │ └─────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ Booking Module │ │ │ ├─────────────────────────────────────────┤ │ │ │ Booking Form │ │ │ │ [x] Vertical Form │ │ │ │ [ ] Calendar Horizontal │ │ │ └─────────────────────────────────────────┘ │ │ │ │ [Save Changes] │ └─────────────────────────────────────────────────┘ ``` ### 5.2 Layout Preview System Each layout option shows: - **Thumbnail preview** (screenshot of layout) - **Name** (e.g., "Modern Single Column") - **Description** (e.g., "Clean layout with large product images") - **Radio button** for selection --- ## 6. Services Architecture ### 6.1 ModuleLayoutService **Purpose:** Manage module layout selections and available layouts **Methods:** ```php // Get selected layout for a module page getLayout(Website $website, string $module): string // Get all available layouts for a module getAvailableLayouts(string $module): array // Update layout selection setLayout(Website $website, string $module, string $layout): void // Get layout metadata (name, description, preview image) getLayoutMetadata(string $module, string $layout): array // Render layout view path getLayoutViewPath(string $module, string $layout): string ``` **Example Usage:** ```php $layoutService = app(ModuleLayoutService::class); // Admin selects "layout-2" for product details $layoutService->setLayout($website, 'product_details', 'layout-2'); // Controller gets the selected layout $layout = $layoutService->getLayout($website, 'product_details'); // Returns: "layout-2" // Render the view $viewPath = $layoutService->getLayoutViewPath('product_details', $layout); // Returns: "public.modules.ecommerce.product-details.layout-2" return view($viewPath, ['product' => $product, 'website' => $website]); ``` ### 6.2 ThemeService (Extended) **New Methods to Add:** ```php // Generate CSS variables from theme settings generateThemeCSS(Website $website): string // Get theme settings (already exists, may need updates) getTheme(Website $website): array // Update theme settings updateTheme(Website $website, array $settings): void ``` --- ## 7. Module Wrapper System ### 7.1 Module Wrapper Layout **Purpose:** Wraps all module pages with: - Theme CSS injection - Header from page builder - Footer from page builder - Consistent spacing/structure **Structure:** ```blade {{ $title }} @include('public.layouts.theme-styles', ['website' => $website]) @include('public.components.header', ['website' => $website])
@yield('module-content')
@include('public.components.footer', ['website' => $website]) @stack('scripts') ``` ### 7.2 Theme Styles Injection **File:** `resources/views/public/layouts/theme-styles.blade.php` ```blade ``` --- ## 8. Example Layout Templates ### 8.1 Product Details - Layout 1 (Modern Single) **File:** `resources/views/public/modules/ecommerce/product-details/layout-1.blade.php` **Structure:** ``` ┌────────────────────────────────────────┐ │ [Header from page builder] │ ├────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────┐ │ │ │ Product Image Gallery (large) │ │ │ │ │ │ │ └──────────────────────────────────┘ │ │ │ │ Product Name │ │ ⭐⭐⭐⭐⭐ (5.0) 120 reviews │ │ │ │ $49.99 │ │ │ │ Description text here... │ │ │ │ [Add to Cart] [Buy Now] │ │ │ │ ┌──────────────────────────────────┐ │ │ │ Product Details Tab │ │ │ │ - Specifications │ │ │ │ - Reviews │ │ │ └──────────────────────────────────┘ │ │ │ ├────────────────────────────────────────┤ │ [Footer from page builder] │ └────────────────────────────────────────┘ ``` ### 8.2 Product Details - Layout 2 (Sidebar Gallery) **Structure:** ``` ┌────────────────────────────────────────┐ │ [Header] │ ├────────────────────────────────────────┤ │ ┌─────────┐ ┌───────────────────┐ │ │ │ Gallery │ │ Product Name │ │ │ │ │ │ ⭐⭐⭐⭐⭐ │ │ │ │ [img] │ │ │ │ │ │ [img] │ │ $49.99 │ │ │ │ [img] │ │ │ │ │ │ │ │ Description... │ │ │ │ │ │ │ │ │ │ │ │ [Add to Cart] │ │ │ └─────────┘ └───────────────────┘ │ │ │ ├────────────────────────────────────────┤ │ [Footer] │ └────────────────────────────────────────┘ ``` ### 8.3 Cart Page - Sidebar Cart **Structure:** ``` ┌────────────────────────────────────────┐ │ [Header] │ ├────────────────────────────────────────┤ │ Shopping Cart │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Cart Items │ │ Order Summary│ │ │ │ │ │ │ │ │ │ [Product 1] │ │ Subtotal: $99│ │ │ │ [Product 2] │ │ Shipping: $10│ │ │ │ [Product 3] │ │ Tax: $8 │ │ │ │ │ │ │ │ │ │ │ │ Total: $117 │ │ │ │ │ │ │ │ │ │ │ │ [Checkout] │ │ │ └──────────────┘ └──────────────┘ │ │ │ ├────────────────────────────────────────┤ │ [Footer] │ └────────────────────────────────────────┘ ``` --- ## 9. Routes Architecture **No new routes needed!** Use existing routes: ```php // Existing routes (just update controllers to use layouts) Route::get('/products', [EcommerceController::class, 'index']); Route::get('/products/{slug}', [EcommerceController::class, 'show']); Route::get('/cart', [EcommerceController::class, 'cart']); Route::get('/checkout', [EcommerceController::class, 'checkout']); Route::get('/booking', [BookingController::class, 'index']); Route::get('/booking/{id}', [BookingController::class, 'show']); Route::get('/listings', [ListingController::class, 'index']); Route::get('/listings/{slug}', [ListingController::class, 'show']); Route::get('/payment/{slug}', [PaymentController::class, 'show']); ``` **New customizer routes:** ```php // In customizer routes group Route::get('/module-layouts', [ModuleLayoutController::class, 'index']) ->name('customizer.module-layouts'); Route::post('/module-layouts', [ModuleLayoutController::class, 'update']) ->name('customizer.module-layouts.update'); ``` --- ## 10. Controller Updates **Before (example - ProductController):** ```php public function show(Website $website, $slug) { $product = Product::where('slug', $slug)->firstOrFail(); return view('public.product-details', compact('product', 'website')); } ``` **After (with layout system):** ```php public function show(Website $website, $slug) { $product = Product::where('slug', $slug)->firstOrFail(); // Get selected layout $layoutService = app(ModuleLayoutService::class); $layout = $layoutService->getLayout($website, 'product_details'); // Get theme settings $themeService = app(ThemeService::class); $theme = $themeService->getTheme($website); // Render with selected layout $viewPath = $layoutService->getLayoutViewPath('product_details', $layout); return view($viewPath, compact('product', 'website', 'theme')); } ``` --- ## 11. Implementation Phases ### Phase 1: Foundation (Week 1) 1. Create `ModuleLayoutService` 2. Create module wrapper layout 3. Create theme CSS injection system 4. Update database schema (settings JSON) 5. Create base CSS file **Deliverable:** System can render module pages with theme styling ### Phase 2: E-Commerce Layouts (Week 2) 1. Create all product details layouts (3 layouts) 2. Create cart layouts (2 layouts) 3. Create checkout layouts (2 layouts) 4. Create product listing layouts (2 layouts) 5. Update EcommerceController **Deliverable:** E-commerce module fully working with layouts ### Phase 3: Booking & Listing Layouts (Week 3) 1. Create booking form layouts (2 layouts) 2. Create booking details layout 3. Create listing layouts (2 layouts) 4. Update BookingController and ListingController **Deliverable:** Booking and Listing modules working ### Phase 4: Customizer Integration (Week 4) 1. Create customizer UI for layout selection 2. Create preview thumbnails for each layout 3. Add ModuleLayoutController 4. Test end-to-end flow **Deliverable:** Admins can select layouts via customizer ### Phase 5: Centralized Payment Page (Week 5) 1. Create unified payment page layout 2. Update all modules to use same payment flow 3. Handle different payment contexts (product, booking, form) **Deliverable:** One payment page for all modules ### Phase 6: Polish & Documentation (Week 6) 1. Add layout preview images 2. Create user documentation 3. Performance optimization 4. Testing across all modules **Deliverable:** Production-ready system --- ## 12. Benefits of This Architecture ### For Admins ✅ Easy layout selection - just pick from dropdown ✅ No coding required ✅ Consistent branding across all pages ✅ Quick theme changes apply everywhere ### For Developers ✅ Clean separation of concerns ✅ Easy to add new layouts ✅ Reusable components ✅ Maintainable codebase ### For End Users ✅ Consistent experience across site ✅ Professional-looking pages ✅ Fast loading (no heavy page builder JS) ✅ Mobile responsive --- ## 13. Future Enhancements ### Phase 7+ (Future) - **Layout Builder:** Allow admins to create custom layouts - **A/B Testing:** Test different layouts for conversion - **Mobile-specific layouts:** Different layouts for mobile vs desktop - **Import/Export:** Share layouts between websites - **Marketplace:** Sell/buy premium layouts --- ## 14. Technical Considerations ### Performance - CSS variables are fast (no JS required) - Layouts are server-rendered (no client-side build) - Can cache rendered layouts ### Compatibility - Works with existing page builder - Doesn't conflict with custom pages - Module pages use layouts, custom pages use builder ### Migration - Existing sites continue working - New sites get default layouts - Can migrate existing module pages to use layouts --- ## 15. Questions to Consider Before Implementation 1. **Do you want to implement all modules at once, or start with e-commerce?** - Recommendation: Start with e-commerce (most complex) 2. **How many layout variations per page type?** - Current plan: 2-3 per type - Can add more later 3. **Should admins be able to customize individual layouts?** - Not in MVP - Add in Phase 7+ 4. **Preview functionality - real data or mockups?** - Recommendation: Screenshot previews for MVP - Live previews in Phase 7+ 5. **Mobile responsiveness - automatic or separate mobile layouts?** - Recommendation: Automatic (using Bootstrap responsive classes) --- ## Ready for Implementation? Once you approve this architecture, I'll start implementing: **Step 1:** Create `ModuleLayoutService` **Step 2:** Create module wrapper layout system **Step 3:** Create first layout (Product Details - Layout 1) **Step 4:** Test end-to-end flow Let me know if you want to: - Proceed with implementation ✅ - Modify the architecture - Ask questions about specific parts