Pages Documentation

Overview

This section documents all application pages and routes in the Collage Brand Portal. Pages are located in app/pages/ and use Nuxt 4's file-based routing system. Each page file automatically generates a route based on its file path and name.

Pages Architecture

File-Based Routing

Nuxt 4 uses file-based routing where the file structure in app/pages/ directly maps to application routes. The routing system is automatic and requires no manual route configuration.

Architecture Pattern

┌─────────────────────────────────────────┐
│      Route Request                      │  ← User navigates to URL
├─────────────────────────────────────────┤
│      Middleware Execution               │  ← Global & per-route middleware
│      (auth.global.ts, check-url.ts)     │
├─────────────────────────────────────────┤
│      Layout Selection                   │  ← Layout wrapper (collage-layout, etc.)
├─────────────────────────────────────────┤
│      Page Component                     │  ← Page component from app/pages/
│      ┌───────────────────────────────┐  │
│      │  Composables                  │  │  ← Page logic (useDashboard, etc.)
│      │  Components                    │  │  ← UI components
│      │  API Calls                     │  │  ← Data fetching
│      └───────────────────────────────┘  │
└─────────────────────────────────────────┘

Route Generation Rules

1. File Name = Route Path: login.vue → /login
2. Folders = Route Segments: [brand_name]/login.vue → /{brand_name}/login
3. Dynamic Segments: [id].vue → /:id (dynamic parameter)
4. Index Files: index.vue → / (root of that segment)
5. Nested Routes: folders/[id]/index.vue → /folders/:id

Pages Structure

app/pages/
├── index.vue                              # Root landing page
├── reset-password.vue                     # Root-level password reset
├── get_assets.vue                        # Asset download redirect
├── [...slug].vue                         # Root catch-all
├── [brand_name]/                          # Brand-specific routes
│   ├── index.vue                          # Dashboard/home page
│   ├── login.vue                          # Login page
│   ├── forgot-password.vue                # Password recovery
│   ├── generate-password.vue              # Password generation
│   ├── profile.vue                        # User profile
│   ├── search.vue                         # Search page
│   ├── sharing.vue                        # Share link management
│   ├── support.vue                        # Support/feedback
│   ├── [token]/                           # Token-based routes
│   │   └── index.vue                      # Token login page
│   ├── collage/                           # Collage routes
│   │   ├── index.vue                      # Collage list
│   │   └── [id]/                          # Collage details
│   │       └── index.vue                  # Collage viewer
│   ├── folders/                           # Folder routes
│   │   ├── index.vue                      # Folder list
│   │   └── [id]/                          # Folder details
│   │       └── index.vue                  # Folder contents
│   └── files/                             # File routes
│       └── [id].vue                       # File/asset details
│   └── [...slug].vue                      # Brand catch-all
└── shared-assets/                         # Public shared assets
    └── [type].vue                         # Shared asset viewer

Total: 20 page files (excluding root catch-all)

Route Categories

1. Authentication Pages

Pages for user authentication and password management:

• Login ([brand_name]/login.vue) - Email/password authentication
• Forgot Password ([brand_name]/forgot-password.vue) - Password recovery
• Reset Password (reset-password.vue) - Password reset with token
• Generate Password ([brand_name]/generate-password.vue) - Password generation for invitations
• Token Login ([brand_name]/[token]/index.vue) - One-time token-based access

Common Features:

• HTTP-only cookie authentication
• Form validation
• Error handling
• Loading states
• Redirect logic

2. Main Application Pages

Core application pages for authenticated users:

• Dashboard ([brand_name]/index.vue) - Home page with banners, tiles, trending, and recent uploads
• Profile ([brand_name]/profile.vue) - User profile management
• Search ([brand_name]/search.vue) - Advanced search with Typesense
• Sharing ([brand_name]/sharing.vue) - Share link management
• Support ([brand_name]/support.vue) - Feedback submission

Common Features:

• Protected routes (require authentication)
• Data fetching with composables
• Loading states
• Error handling
• Responsive layouts

3. Folder Pages

Pages for folder navigation and management:

• Folders List ([brand_name]/folders/index.vue) - List of all folders
• Folder Details ([brand_name]/folders/[id]/index.vue) - Folder contents and navigation

Features:

• Hierarchical navigation
• Breadcrumb navigation
• View mode toggle (grid/list)
• Bulk operations
• Asset listing

4. Collage Pages

Pages for collage (collection) management:

• Collage List ([brand_name]/collage/index.vue) - List of all collages
• Collage Details ([brand_name]/collage/[id]/index.vue) - Collage viewer and management

Features:

• Collage display
• Asset management within collage
• Collage sharing
• Collage actions

5. Asset Pages

Pages for individual asset viewing:

• File Details ([brand_name]/files/[id].vue) - Detailed asset information and preview

Features:

• Asset preview
• Asset metadata
• Download options
• Share options
• Version history

6. Utility Pages

Utility and special-purpose pages:

• Root Index (index.vue) - Brand URL entry landing page
• Get Assets (get_assets.vue) - Server-side asset download redirect
• Shared Assets (shared-assets/[type].vue) - Public shared asset viewer
• Catch-all ([...slug].vue) - Root and [brand_name] catch-all routes

Page Patterns

1. Layout Selection

Pages specify their layout using definePageMeta:

<script setup lang="ts">
definePageMeta({
  layout: 'collage-layout'  // or 'login-layout', 'default', 'error-layout'
})
</script>

Available Layouts:

• collage-layout - Main application layout (header + sidebar)
• login-layout - Authentication pages layout
• default - Default minimal layout
• error-layout - Error pages layout

2. Middleware Application

Pages can apply middleware for route protection:

<script setup lang="ts">
definePageMeta({
  middleware: ['check-url', 'redirect-if-logged-in']
})
</script>

Common Middleware:

• check-url - URL validation and brand verification
• redirect-if-logged-in - Redirect authenticated users from auth pages
• public-portal-home - Public portal auto-login
• public-portal-login-redirect - Public portal login redirect

3. Data Fetching Pattern

Most pages use composables for data management:

<script setup lang="ts">
const { 
  bannerData, 
  tileData, 
  contentLoading,
  fetchDashboard 
} = useDashboard()

onMounted(async () => {
  await fetchDashboard()
})
</script>

4. Loading States

Pages implement skeleton loaders during data fetching:

<template>
  <template v-if="contentLoading">
    <v-skeleton-loader type="card" />
  </template>
  <template v-else>
    <!-- Actual content -->
  </template>
</template>

5. Error Handling

Pages implement error boundaries:

<script setup lang="ts">
const error = ref(null)

try {
  await fetchData()
} catch (e) {
  error.value = e
  useSnackbar().showError(e.message)
}
</script>

6. Form Handling

Authentication pages use form validation:

<script setup lang="ts">
const form = ref({
  email: '',
  password: ''
})

const emailError = ref<string | null>(null)

const validateEmail = () => {
  if (!form.value.email) {
    emailError.value = 'Email is required'
  }
}

const login = async () => {
  // Validation and submission
}
</script>

API Usage

Pages use two types of APIs:

Server APIs (Internal)

Internal Nuxt server routes for server-side operations:

• Authentication: /api/auth/set-session, /api/auth/clear-session, /api/auth/session, /api/auth/refresh-user, /api/auth/debug (dev)
• WebSocket Auth: /api/pusher/auth
• Search: /api/typesense/search
• Proxies: /api/pdf/proxy, /api/txt/proxy (asset preview)

Usage:

const response = await $fetch('/api/auth/session')

Composable APIs (External)

External API composables for backend communication:

• useAuthApi() - Authentication operations
• useAppDataApi() - Dashboard and app data
• useAssetsApi() - Asset operations
• useSearchApi() - Search operations
• useSharingApi() - Sharing operations
• useFolderApi() - Folder operations
• useCollectionApi() - Collection/collage operations

Usage:

const appDataApi = useAppDataApi()
const response = await appDataApi.fetchDashboard()

Composables Integration

Pages use composables for logic encapsulation:

Page-Specific Composables

Located in app/composables/core/pages/:

• useDashboard() - Dashboard data management
• useSearch() - Search functionality
• useProfile() - Profile management
• useSharing() - Sharing functionality
• useFolders() - Folder operations
• useCollage() - Collage operations
• useCollageDetails() - Collage details
• useFolderDetails() - Folder details
• useAssetDetails() - Asset details
• useExternalShare() - External share viewing
• useSupport() - Support/feedback

Common Composables

Located in app/composables/core/common/:

• useHelpers() - Utility functions
• useAnalytics() - Analytics tracking
• useSnackbar() - Notification display
• useFileType() - File type detection
• useBreadCrumbs() - Breadcrumb navigation

Route Parameters

Dynamic Route Parameters

Pages use dynamic parameters for flexible routing:

• [brand_name] - Brand/workspace identifier
• [id] - Resource ID (folder, collage, file)
• [token] - One-time access token
• [type] - Asset type identifier

Access in Pages:

<script setup lang="ts">
const route = useRoute()
const brandName = route.params.brand_name as string
const folderId = route.params.id as string
</script>

Page Documentation

Authentication Pages

• Login Page - User authentication with email/password
• Forgot Password Page - Password recovery via email
• Reset Password Page - Password reset with token
• Generate Password Page - Password generation for invitations
• Token Login Page - One-time token-based authentication

Main Application Pages

• Dashboard - Main dashboard/home page
• Search Page - Advanced search with Typesense integration
• Profile Page - User profile management
• Support Page - Feedback submission
• Sharing Page - Share link management

Folder Pages

• Folders List - List of all folders
• Folder Details - Folder contents and management

Collage Pages

• Collage List - List of all collages
• Collage Details - Collage contents and management

Asset Pages

• File Details - Detailed asset information and preview

Utility Pages

• Root Index Page - Brand URL entry landing page
• Get Assets Page - Server-side asset download redirect
• Shared Assets Page - Public shared assets viewer

Best Practices

1. Use Composables: Extract page logic into composables for reusability
2. Loading States: Always show loading states during data fetching
3. Error Handling: Implement proper error handling and user feedback
4. Type Safety: Use TypeScript types from ~/types
5. Caching: Leverage store caching for frequently accessed data
6. SSR Compatibility: Ensure components work with SSR
7. API Usage: Use appropriate API type (Server APIs for internal operations, Composable APIs for external backend calls)
8. Middleware: Apply appropriate middleware for route protection
9. Layout Selection: Choose appropriate layout for page type
10. Form Validation: Implement client-side validation for forms

Related Documentation

• Server APIs - Internal Nuxt server routes
• Composable APIs - External API composables
• Composables - Reusable composition functions
• Stores - Pinia state management
• Middleware - Route protection and access control
• Components - Reusable Vue components
• Layouts - Page layout components
• Types - TypeScript type definitions