# Page Parameters Explained

## Overview

This document clarifies key page parameters in Modyo Channels that have different meanings based on context.

## `has_router` Parameter

The `has_router` parameter has **different purposes** depending on the page type:

### Widget Pages (page_type: "default" or "home")

**Purpose**: Enables **client-side JavaScript routing**

**Behavior**:
- When `has_router: true`, the same widgets are rendered for **all sub-routes** under the page path
- Widgets handle navigation internally using JavaScript routers (React Router, Vue Router, etc.)
- Server doesn't create new routes - widgets manage routing client-side

**Example**:
```typescript
// Page at /app with has_router: true
page-create({
  name: "Banking App",
  path: "/app",
  page_type: "default",
  has_router: true,
  grid_type: "full_grid"
})

// The SAME widgets render for ALL these routes:
// /app
// /app/dashboard
// /app/accounts
// /app/transfers
// /app/settings

// Widgets use React Router/Vue Router to handle routing
```

**Use Cases**:
- Single Page Applications (SPAs)
- Client-side navigation without page reloads
- React/Vue/Angular applications with multiple views
- Complex interactive dashboards with multiple sections

### Content Pages (page_type: "content" or "entry")

**Purpose**: Enables **server-side dynamic routing** for content entries

**Behavior**:
- Required for "entry" (show) pages to enable dynamic slug routing
- Server automatically routes `/path/{slug}` to the correct content entry
- Each entry slug gets its own server-side route

**Example**:
```typescript
// Index page - lists all blog posts
page-create({
  name: "Blog Index",
  path: "/blog",
  page_type: "content",
  content_type_id: 5756,
  has_router: false  // Not needed for index
})
// Creates: /blog (shows list of entries)

// Show page - displays single blog post
page-create({
  name: "Blog Post",
  path: "/blog",
  page_type: "entry",
  content_type_id: 5756,
  has_router: true  // REQUIRED for dynamic slugs
})
// Creates: /blog/{slug} (shows single entry)
// Example: /blog/my-first-post, /blog/announcing-feature
```

**Use Cases**:
- Blog post detail pages
- Product detail pages
- News article pages
- Documentation pages
- Any content-driven pages with unique entry URLs

## `sync` Parameter (Widgets)

The `sync` parameter controls **widget loading behavior** on pages.

### Synchronous Loading (`sync: true`)

**Behavior**:
- Widget HTML/CSS/JS is injected **during** page render
- Page rendering **blocks** until widget is loaded
- Widget content appears immediately with initial page load

**When to Use**:
- Critical above-the-fold content
- Hero sections or banners
- Content that affects layout significantly
- Content needed for first paint

**Performance Impact**:
- Slower initial page load
- Better user experience for critical content
- Can cause render blocking

**Example**:
```typescript
{
  type: "custom_widget",
  widget_definition_uuid: "abc123...",
  position: 0,
  column: 0,
  sync: true,  // Load immediately with page
  label: "Hero Banner - Critical"
}
```

### Asynchronous Loading (`sync: false`)

**Behavior**:
- Widget loads **after** page render completes
- Page rendering doesn't wait for widget
- Widget content appears after initial page load

**When to Use**:
- Below-the-fold content
- Non-critical widgets
- Third-party integrations
- Analytics widgets
- Most widgets (default recommendation)

**Performance Impact**:
- Faster initial page load
- Better Core Web Vitals scores
- Progressive enhancement pattern

**Example**:
```typescript
{
  type: "custom_widget",
  widget_definition_uuid: "xyz789...",
  position: 1,
  column: 0,
  sync: false,  // Load after page renders
  label: "Related Products - Non-Critical"
}
```

## Best Practice Recommendations

### `has_router` Usage

**Widget Pages**:
- ✅ Use `has_router: true` for SPAs with client-side routing
- ❌ Don't use for static pages with no sub-routes
- ✅ Ensure widgets can handle routing (React Router, Vue Router)
- ✅ Test all sub-routes to ensure widget handles them

**Content Pages**:
- ✅ Always use `has_router: true` for show/entry pages
- ❌ Don't use for index/content pages
- ✅ Ensure content_type_id is set
- ✅ Test entry slugs work correctly

### `sync` Usage

**Performance First**:
- ✅ Default to `sync: false` (async) for better performance
- ✅ Use `sync: true` only for critical above-the-fold content
- ✅ Test page load times with different sync configurations
- ✅ Monitor Core Web Vitals impact

**Content Priority**:
```typescript
// Good pattern - critical first, rest async
widgets: [
  {
    label: "Hero Banner",
    position: 0,
    sync: true  // Critical - load immediately
  },
  {
    label: "Feature Grid",
    position: 1,
    sync: false  // Non-critical - load async
  },
  {
    label: "Related Content",
    position: 2,
    sync: false  // Non-critical - load async
  }
]
```

## Common Mistakes

### `has_router` Mistakes

❌ **Using has_router on widget page without client-side routing**:
```typescript
// Bad - has_router: true but no JS routing in widgets
page-create({
  path: "/marketing",
  page_type: "default",
  has_router: true  // ❌ No widgets handle routing
})
```

❌ **Forgetting has_router on content show page**:
```typescript
// Bad - entry page without has_router
page-create({
  path: "/blog",
  page_type: "entry",
  content_type_id: 5756,
  has_router: false  // ❌ Dynamic slugs won't work!
})
```

### `sync` Mistakes

❌ **Making all widgets synchronous**:
```typescript
// Bad - all widgets block rendering
widgets: [
  { sync: true },  // Hero - OK
  { sync: true },  // Features - ❌ Should be async
  { sync: true },  // Footer - ❌ Should be async
]
```

❌ **Making critical content asynchronous**:
```typescript
// Bad - hero banner loads after page
{
  label: "Hero Banner",
  position: 0,
  sync: false  // ❌ Critical content should be sync
}
```

## Related Documentation

- [MODYO_PAGE_TYPES.md](../MODYO_PAGE_TYPES.md) - Complete page types guide
- [PAGE_WIDGET_TOOLS.md](./PAGE_WIDGET_TOOLS.md) - Widget management tools
- [MODYO_SITE_ARCHITECTURE.md](../MODYO_SITE_ARCHITECTURE.md) - Site architecture overview

---

**Document Version**: 1.0.0
**Last Updated**: 2025-01-09
**Maintained By**: Modyo MCP Development Team