# Modyo Site - Content Flow, Patterns & Best Practices
**Version**: 1.0.0
**Last Updated**: 2025-01-09
**Module**: Channels
> This document is part of the [Site Architecture Guide](./site-architecture.md). See also [Component Deep Dive](./site-components.md).
## Content Flow
### Page Rendering Sequence
```
┌─────────────────────────────────────────────────────────┐
│ 1. USER REQUEST │
│ https://www.example.com/products/laptop-x │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 2. SITE RESOLUTION │
│ - Lookup domain in site configuration │
│ - Verify site is enabled │
│ - Check authentication requirements │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 3. ROUTE MATCHING │
│ - Parse URL path: /products/laptop-x │
│ - Match against page routes │
│ - Found: /products/:slug (dynamic route) │
│ - Extract slug parameter: "laptop-x" │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 4. PAGE LOADING │
│ - Load page configuration │
│ - Check page privacy settings │
│ - Verify user permissions │
│ - Get page layout: Base Layout │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 5. CONTENT RETRIEVAL (Content Pages Only) │
│ ⚠️ Only for page_type: "content" or "entry" │
│ - Lookup content entry by slug: "laptop-x" │
│ - Fetch from Content Type: "Products" (ID: 5756) │
│ - Load all entry fields and metadata │
│ - Inject automatic Liquid drops: │
│ • {{ entry }} - for show view (single entry) │
│ • {{ entries }} - for index view (list) │
│ ❌ Widget Pages: No automatic content retrieval │
│ ❌ Origination Pages: No content retrieval │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 6. LAYOUT RENDERING │
│ - Load Base Layout template │
│ - Process layout Liquid markup │
│ │
│ Base Layout: │
│ │
│ │
│ │
│ {% snippet 'head-meta' %} ◄─────────┐ │
│ │ │
│ │ │
│ {% snippet 'site-header' %} ◄────────┼─────┐ │
│ {% menu 'main-navigation' %} ◄───────┼─────┼─┐ │
│ │ │ │ │
│ {{ content_for_layout }} ◄─────────┼─────┼─┼─┐│
│ │ │ │ ││
│ {% snippet 'site-footer' %} ◄────────┼─────┼─┼─││
│ │ │ │ ││
│ │ │ │ ││
└────────────────────────────────────────────┼─────┼─┼─││
│ │ │ ││
┌──────────────────┘ │ │ ││
▼ │ │ ││
┌─────────────────────────────────────────────────┐ │ ││
│ 7. SNIPPET PROCESSING │ │ ││
│ - Load snippet: 'head-meta' │ │ ││
│ - Render snippet Liquid │ │ ││
│ - Insert into layout │ │ ││
│ │ │ ││
│ head-meta snippet: │ │ ││
│ │ │ ││
│ │ │ ││
└─────────────────────────────────────────────────┘ │ ││
┌──────────────────────────┘ ││
▼ ││
┌─────────────────────────────────────────────────────┐││
│ 8. SNIPPET PROCESSING │││
│ - Load snippet: 'site-header' │││
│ - Render snippet Liquid │││
│ │││
│ site-header snippet: │││
│ │││
│ ...
│││
│ │││
│ │││
└─────────────────────────────────────────────────────┘││
┌────────────────────────────┘│
▼ │
┌─────────────────────────────────────────────────────┐ │
│ 9. MENU RENDERING │ │
│ - Load menu: 'main-navigation' │ │
│ - Build menu HTML hierarchy │ │
│ - Mark active items based on current URL │ │
│ │ │
│ Output: │ │
│ │ │
└─────────────────────────────────────────────────────┘ │
┌──────────────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ 10. CONTENT RENDERING (content_for_layout) │
│ - If Widget Page: Render widgets in zones │
│ - If Content Page: Render content entry data │
│ │
│ Product Detail (Content Page): │
│ │
│ {{ entry.name }}
│
│ 
│
│ {{ entry.description }}
│
│ ${{ entry.price }} │
│ │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 11. FINAL HTML ASSEMBLY │
│ - Combine all rendered components │
│ - Process all Liquid variables │
│ - Inject CSS templates │
│ - Inject JS templates │
│ - Minify (if enabled) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 12. HTTP RESPONSE │
│ - Return complete HTML document │
│ - Send HTTP headers (cache, security, etc.) │
│ - Set cookies (if needed) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 13. BROWSER RENDERING │
│ - Browser receives HTML │
│ - Loads CSS (from CSS templates) │
│ - Executes JS (from JS templates) │
│ - Loads widget JS (if async widgets) │
│ - Renders final page to user │
└─────────────────────────────────────────────────────┘
```
---
## Common Architecture Patterns
### Pattern 1: Basic Marketing Website
```
Site: www.company.com
├── Pages
│ ├── / (Home - Widget Page)
│ │ └── Widgets: [Hero, Features, Testimonials, CTA]
│ ├── /about (Widget Page)
│ │ └── Widgets: [Team Grid, Company Values]
│ ├── /services (Widget Page)
│ │ └── Widgets: [Service Cards, Pricing Table]
│ └── /contact (Widget Page)
│ └── Widgets: [Contact Form, Map]
├── Templates
│ ├── Base Layout (shared structure)
│ ├── Snippets
│ │ ├── site-header
│ │ ├── site-footer
│ │ └── analytics
│ └── CSS/JS
│ ├── global-styles.css
│ └── global-scripts.js
└── Navigation
└── Main Menu: [Home, About, Services, Contact]
```
### Pattern 2: E-Commerce Site
```
Site: shop.example.com
├── Pages
│ ├── / (Home - Widget Page)
│ │ └── Widgets: [Hero Slider, Featured Products, Promotions]
│ │
│ ├── /products (Product List - Content Page)
│ │ ├── Type: Content Page (Index)
│ │ ├── Content Type: Products
│ │ └── Displays: Grid of all products
│ │
│ ├── /products/:slug (Product Detail - Content Page)
│ │ ├── Type: Content Page (Show)
│ │ ├── has_router: true
│ │ ├── Content Type: Products
│ │ └── Displays: Individual product
│ │
│ ├── /cart (Widget Page)
│ │ └── Widgets: [Shopping Cart, Checkout Button]
│ │
│ └── /checkout (Widget Page - Private)
│ ├── private: true
│ └── Widgets: [Checkout Form, Payment Gateway]
│
├── Templates
│ ├── Base Layout
│ ├── Product Layout (for product pages)
│ ├── Snippets
│ │ ├── site-header (with cart icon)
│ │ ├── product-card
│ │ ├── add-to-cart-button
│ │ └── site-footer
│ └── Custom Snippets
│ ├── product-grid
│ ├── product-filters
│ └── customer-reviews
│
└── Navigation
├── Main Menu: [Home, Products, Cart, My Account]
└── Footer Menu: [Shipping, Returns, FAQ, Support]
```
### Pattern 3: Blog / Content Hub
```
Site: blog.example.com
├── Pages
│ ├── / (Home - Widget Page)
│ │ └── Widgets: [Featured Posts, Recent Posts, Newsletter]
│ │
│ ├── /blog (Blog List - Content Page)
│ │ ├── Type: Content Page (Index)
│ │ ├── Content Type: Blog Posts
│ │ └── Displays: List of all blog posts
│ │
│ ├── /blog/:slug (Blog Post - Content Page)
│ │ ├── Type: Content Page (Show)
│ │ ├── has_router: true
│ │ ├── Content Type: Blog Posts
│ │ └── Displays: Individual blog post
│ │
│ ├── /blog/category/:category (Category Page)
│ │ ├── Type: Content Page (Index)
│ │ ├── has_router: true
│ │ └── Displays: Posts filtered by category
│ │
│ └── /authors/:slug (Author Page)
│ ├── Type: Content Page (Show)
│ ├── has_router: true
│ └── Displays: Author bio + their posts
│
├── Templates
│ ├── Base Layout
│ ├── Blog Layout (for blog posts)
│ ├── Snippets
│ │ ├── site-header
│ │ ├── blog-post-card
│ │ ├── author-bio
│ │ ├── social-share
│ │ ├── related-posts
│ │ └── site-footer
│ └── Custom Snippets
│ ├── comments-section
│ ├── newsletter-signup
│ └── category-tags
│
└── Navigation
├── Main Menu: [Home, Blog, Categories, Authors]
└── Categories Sub-menu: [Technology, Design, Marketing]
```
### Pattern 4: Customer Portal (Private)
```
Site: portal.example.com
├── Settings
│ ├── private: true (entire site requires auth)
│ ├── realm_id: 5
│ └── authentication_required: true
│
├── Pages
│ ├── /login (Public - Widget Page)
│ │ ├── page_type: "default"
│ │ ├── private: false (exception)
│ │ ├─> ✅ Accepts: Custom widgets
│ │ └── Widgets: [Login Form Widget]
│ │
│ ├── /dashboard (Private - Widget Page)
│ │ ├── page_type: "default"
│ │ ├── private: true
│ │ ├─> ✅ Accepts: Custom widgets
│ │ └── Widgets: [User Stats, Recent Activity, Quick Actions]
│ │
│ ├── /account (Private - Widget Page)
│ │ ├── page_type: "default"
│ │ ├── private: true
│ │ ├─> ✅ Accepts: Custom widgets
│ │ └── Widgets: [Profile Form, Password Change]
│ │
│ ├── /documents (Private - Content Page)
│ │ ├── page_type: "content"
│ │ ├── content_type_id: 8201 (Documents)
│ │ ├── private: true
│ │ ├─> ❌ No custom widgets
│ │ ├─> ✅ Automatic: {{ entries }} drop
│ │ └── Displays: User's documents (index view)
│ │
│ └── /documents/:slug (Private - Content Page)
│ ├── page_type: "entry"
│ ├── content_type_id: 8201 (Documents)
│ ├── private: true
│ ├── has_router: true
│ ├─> ❌ No custom widgets
│ ├─> ✅ Automatic: {{ entry }} drop
│ └── Displays: Document viewer (show view)
│
├── Templates
│ ├── Base Layout (with user menu)
│ ├── Snippets
│ │ ├── private-header (with logout)
│ │ ├── user-menu
│ │ ├── breadcrumbs
│ │ └── site-footer
│ └── Custom Snippets
│ ├── document-viewer
│ └── file-uploader
│
└── Navigation
└── User Menu: [Dashboard, Documents, Account, Settings, Logout]
```
### Pattern 5: Multi-Language Site
```
Site: www.global-company.com
├── Settings
│ ├── languages: [en, es, pt]
│ └── default_language: en
│
├── Pages
│ ├── /en (English Home)
│ ├── /es (Spanish Home)
│ ├── /pt (Portuguese Home)
│ │
│ ├── /en/about
│ ├── /es/acerca
│ ├── /pt/sobre
│ │
│ └── Language switcher logic in header
│
├── Templates
│ ├── Snippets
│ │ ├── site-header-en
│ │ ├── site-header-es
│ │ ├── site-header-pt
│ │ └── language-switcher
│ └── CSS/JS (language-specific)
│
└── Navigation
├── Main Menu EN: [Home, About, Products, Contact]
├── Main Menu ES: [Inicio, Acerca, Productos, Contacto]
└── Main Menu PT: [Início, Sobre, Produtos, Contato]
```
---
## Best Practices
### 1. Site Structure
✅ **Do**:
- Plan URL structure before creating pages
- Use semantic paths: `/products/laptops` not `/p/l`
- Keep navigation max 3 levels deep
- Create staging site before production
❌ **Don't**:
- Don't use generic paths like `/page1`, `/item2`
- Don't create circular navigation references
- Don't exceed 3 navigation levels
- Don't skip testing in staging
### 2. Templates & Snippets
✅ **Do**:
- Use snippets for all reusable code
- Create snippet for header, footer, analytics
- Name snippets descriptively: `product-card` not `snippet1`
- Document snippet parameters
- Keep snippets focused (single responsibility)
❌ **Don't**:
- Don't duplicate code across pages
- Don't create overly complex snippets
- Don't mix concerns (layout + logic in one snippet)
- Don't forget to publish snippets
### 3. Widgets
✅ **Do**:
- Create widgets for interactive components
- Use widget variables for configuration
- Implement responsive design
- Test widgets in isolation
- Document widget variables
❌ **Don't**:
- Don't hardcode values (use variables)
- Don't create widgets for static content (use snippets)
- Don't forget about mobile responsiveness
- Don't skip accessibility testing
### 4. Pages
**⚠️ CRITICAL: Choose the correct page type for your use case!**
✅ **Do**:
- **Widget Pages** (page_type: "default" or "home"):
- Use for custom layouts with widgets
- Use for marketing pages, dashboards, landing pages
- Configure grid_type for column layout
- Add custom widgets with page-add-widgets tool
- **Content Pages** (page_type: "content" or "entry"):
- Use for displaying Content API entries
- ALWAYS specify content_type_id
- Use index view for lists (automatic {{ entries }} drop)
- Use show view for details (automatic {{ entry }} drop)
- Do NOT try to add custom widgets (use Liquid only)
- **Origination Pages** (page_type: "origination"):
- Use for multi-step forms (loan apps, onboarding)
- Use for task-based workflows
- Do NOT add custom widgets
- **All Page Types**:
- Set appropriate privacy settings
- Configure SEO meta tags
- Test dynamic routing (for content pages)
❌ **Don't**:
- **Never** try to add custom widgets to content pages or origination pages
- **Never** forget to specify content_type_id for content pages
- Don't create duplicate paths
- Don't publish without testing
- Don't use wrong page type (see [MODYO_PAGE_TYPES.md](./MODYO_PAGE_TYPES.md))
- Don't ignore SEO metadata
- Don't forget to set page excerpts
### 5. Navigation
✅ **Do**:
- Keep menu structure logical
- Use consistent naming
- Mark current page as active
- Test menu on mobile devices
- Use private flags for protected content
❌ **Don't**:
- Don't exceed 3 levels of depth
- Don't use confusing labels
- Don't forget to test all links
- Don't hardcode navigation (use {% menu %})
### 6. Performance
✅ **Do**:
- Minimize CSS and JS templates
- Use asynchronous widget loading
- Optimize images before upload
- Enable caching headers
- Use CDN for assets
❌ **Don't**:
- Don't load large libraries unnecessarily
- Don't use synchronous loading for all widgets
- Don't upload unoptimized images
- Don't skip performance testing
### 7. Security
✅ **Do**:
- Configure security headers
- Use HTTPS for all sites
- Set appropriate CORS policies
- Implement CSP (Content Security Policy)
- Use private pages for sensitive content
❌ **Don't**:
- Don't expose sensitive data in page source
- Don't skip authentication for private content
- Don't use weak security headers
- Don't trust client-side validation alone
### 8. Version Control & Workflow
✅ **Do**:
- Use team review for production
- Test in staging before production
- Document changes in commit messages
- Keep backups of templates
- Use versioning system
❌ **Don't**:
- Don't publish directly to production
- Don't skip code review
- Don't forget to test changes
- Don't lose previous versions
---
## Troubleshooting
### Issue: Site Not Loading / 404 Error
**Possible Causes**:
- Site is disabled
- Domain not configured correctly
- No published pages
- DNS not pointing to Modyo
**Solutions**:
1. Verify site is enabled in settings
2. Check domain configuration matches DNS
3. Ensure at least one page is published
4. Verify DNS CNAME points to Modyo
5. Clear browser cache and test
### Issue: Snippet Not Rendering
**Possible Causes**:
- Snippet not published
- Incorrect snippet name in Liquid tag
- Syntax error in snippet code
**Solutions**:
1. Verify snippet is published (not draft)
2. Check exact spelling: `{% snippet 'site-header' %}`
3. Review snippet code for syntax errors
4. Test snippet in isolation
5. Check browser console for errors
### Issue: Widget Not Appearing on Page
**⚠️ CRITICAL: Check page type first!**
**Possible Causes**:
- ❌ **WRONG PAGE TYPE** - Content pages and origination pages do NOT accept custom widgets
- Widget not published via releases
- Widget not added to page
- JavaScript error blocking execution
- Widget loading asynchronously
**Solutions**:
1. **Verify page type** - Use `page-get` tool to check page_type:
- ✅ "default" or "home" = Widget page (accepts widgets)
- ❌ "content" or "entry" = Content page (NO custom widgets)
- ❌ "origination" = Origination page (NO custom widgets)
2. For widget pages only:
- Verify widget is published (use release-get-elements-to-publish and release-create)
- Check widget added to page (use page-get to see widgets array)
- Open browser console for JS errors
- Check widget loading mode (sync vs async)
- Clear browser cache
3. For content/origination pages:
- Use Liquid templates instead of custom widgets
- See [MODYO_PAGE_TYPES.md](./MODYO_PAGE_TYPES.md) for alternatives
### Issue: Navigation Menu Not Updating
**Possible Causes**:
- Menu not published
- Cache not cleared
- Wrong menu name in template
- Menu in draft state
**Solutions**:
1. Publish menu changes
2. Clear site cache
3. Verify menu name: `{% menu 'main-navigation' %}`
4. Check menu publication status
5. Test in incognito mode
### Issue: Dynamic Page Not Loading Content
**⚠️ Content pages only!**
**Possible Causes**:
- ❌ **WRONG PAGE TYPE** - Page must be page_type: "content" or "entry"
- content_type_id not specified (REQUIRED for content pages)
- Content type not linked to page
- `has_router` not enabled (for show view)
- Content entry not published
- Slug mismatch
**Solutions**:
1. **Verify page type** - Use `page-get` tool to check:
- page_type must be "content" or "entry"
- content_type_id must be set (REQUIRED)
2. Enable `has_router: true` for dynamic routes (show view)
3. For index view (list): Use page_type "content"
4. For show view (detail): Use page_type "entry" with has_router
3. Ensure content entry is published
4. Check URL slug matches content entry slug
5. Test with `/content/api/entries` endpoint
### Issue: CSS/JS Not Loading
**Possible Causes**:
- Template not published
- Syntax error in code
- Cache not cleared
- Wrong asset path
**Solutions**:
1. Publish CSS/JS templates
2. Validate CSS/JS syntax
3. Clear browser cache (hard reload)
4. Check asset URLs: `{{ 'file.css' | asset_url }}`
5. Open browser console for errors
### Issue: Private Page Accessible Without Login
**Possible Causes**:
- Page `private` flag not set
- Realm not configured
- Authentication bypass
**Solutions**:
1. Set `private: true` on page
2. Verify site has `realm_id` configured
3. Check authentication settings
4. Test in incognito mode
5. Review security headers
### Issue: SEO Meta Tags Not Showing
**Possible Causes**:
- Meta snippet not included in layout
- Page excerpt not set
- Liquid variables incorrect
**Solutions**:
1. Add `{% snippet 'head-meta' %}` to layout
2. Set page excerpt in page settings
3. Verify Liquid syntax: `{{ page.title }}`
4. Check page source HTML
5. Use SEO testing tools
---
## Additional Resources
### Official Modyo Documentation
- [Channels Overview](https://docs.modyo.com/en/platform/channels/)
- [Sites Documentation](https://docs.modyo.com/en/platform/channels/sites.html)
- [Pages Documentation](https://docs.modyo.com/en/platform/channels/pages.html)
- [Templates Documentation](https://docs.modyo.com/en/platform/channels/templates.html)
- [Widgets Documentation](https://docs.modyo.com/en/platform/channels/widgets.html)
- [Navigation Documentation](https://docs.modyo.com/en/platform/channels/navigation.html)
- [Liquid Markup Guide](https://docs.modyo.com/en/platform/channels/liquid-markup.html)
### API References
- [Modyo Admin API](https://api.modyo.com/swagger)
- [Content API](https://docs.modyo.com/en/platform/content/public-api.html)
### Related Guides
- **[MODYO_PAGE_TYPES.md](./MODYO_PAGE_TYPES.md)** - Comprehensive guide to Widget, Content, and Origination pages
- [tools/TOOLS_SUMMARY.md](./tools/TOOLS_SUMMARY.md) - Complete tool summary and workflows
- [tools/RELEASE_TOOLS.md](./tools/RELEASE_TOOLS.md) - Publishing workflow documentation
- [tools/WIDGET_TOOLS.md](./tools/WIDGET_TOOLS.md) - Widget management tools
- [tools/PAGE_WIDGET_TOOLS.md](./tools/PAGE_WIDGET_TOOLS.md) - Adding widgets to pages
- [COMPREHENSIVE_MCP_TESTING_PLAN.md](./COMPREHENSIVE_MCP_TESTING_PLAN.md)
- [TOOL_DOCUMENTATION_STRATEGY.md](./TOOL_DOCUMENTATION_STRATEGY.md)
- [CHANNELS_TOOLS_AUDIT.md](./CHANNELS_TOOLS_AUDIT.md)
---
**Document Version**: 2.0.0
**Last Updated**: 2025-01-09
**Maintained By**: Modyo MCP Development Team
**Changelog**:
- v2.0.0 (2025-01-09): Updated with comprehensive 3-page-type architecture (Widget, Content, Origination)
- v1.0.0: Initial version