Viewports System

Viewports define where your app displays within the Teachfloor platform.

What is a Viewport?

A viewport is a specific location in the Teachfloor dashboard where your app renders its UI. Each viewport corresponds to a page or section of the platform.

Viewport Structure

Viewports follow a hierarchical naming pattern:

teachfloor.{area}.{page}.{section}

Example: teachfloor.dashboard.course.detail

• teachfloor: Platform namespace
• dashboard: Area (dashboard vs public pages)
• course: Page category
• detail: Specific page

Available Viewports

Quick Reference Table

Course Management

teachfloor.dashboard.course.list

Displays on: Course listing page Path: /:organization/courses Use cases: Course directory widgets, filters, quick actions

{
  "viewport": "teachfloor.dashboard.course.list",
  "component": "CourseListView"
}

teachfloor.dashboard.course.detail

Displays on: Individual course page Path: /:organization/courses/:courseId Use cases: Course analytics, notes, supplementary materials

{
  "viewport": "teachfloor.dashboard.course.detail",
  "component": "CourseDetailView"
}

teachfloor.dashboard.course.module.detail

Displays on: Module detail page Path: /:organization/courses/:courseId/modules/:moduleId Use cases: Module-specific tools, notes, progress tracking

{
  "viewport": "teachfloor.dashboard.course.module.detail",
  "component": "ModuleDetailView"
}

teachfloor.dashboard.course.element.detail

Displays on: Learning element page (assignments, videos, etc.) Path: /:organization/courses/:courseId/modules/:moduleId/elements/:elementId Use cases: Element annotations, supplementary content, tools

{
  "viewport": "teachfloor.dashboard.course.element.detail",
  "component": "ElementDetailView"
}

teachfloor.dashboard.course.module.list

Displays on: Module list page Path: /:organization/courses/:courseId/modules Use cases: Module overview, navigation tools

{
  "viewport": "teachfloor.dashboard.course.module.list",
  "component": "ModuleListView"
}

teachfloor.dashboard.course.assessment.list

Displays on: Assessment list page Path: /:organization/courses/:courseId/assessments Use cases: Assessment overview, quiz management

{
  "viewport": "teachfloor.dashboard.course.assessment.list",
  "component": "AssessmentListView"
}

teachfloor.dashboard.course.progress.detail

Displays on: Course progress page Path: /:organization/courses/:courseId/progress Use cases: Progress tracking, completion status

{
  "viewport": "teachfloor.dashboard.course.progress.detail",
  "component": "CourseProgressView"
}

teachfloor.dashboard.course.calendar.detail

Displays on: Course calendar page Path: /:organization/courses/:courseId/calendar Use cases: Schedule view, deadline tracking

{
  "viewport": "teachfloor.dashboard.course.calendar.detail",
  "component": "CourseCalendarView"
}

teachfloor.dashboard.course.member.list

Displays on: Course members page Path: /:organization/courses/:courseId/members Use cases: Learner list, member management

{
  "viewport": "teachfloor.dashboard.course.member.list",
  "component": "CourseMemberListView"
}

Community

teachfloor.dashboard.community.post.list

Displays on: Community posts/feed page Path: /:organization/community/:communityId/posts Use cases: Social features, engagement tools, moderation

{
  "viewport": "teachfloor.dashboard.community.post.list",
  "component": "CommunityPostsView"
}

teachfloor.dashboard.community.member.list

Displays on: Community members directory Path: /:organization/community/:communityId/members Use cases: Member profiles, networking tools, search

{
  "viewport": "teachfloor.dashboard.community.member.list",
  "component": "CommunityMembersView"
}

Settings

teachfloor.dashboard.settings.general.detail

Displays on: General settings page Path: /:organization/settings/general Use cases: Organization-wide integrations, preferences

{
  "viewport": "teachfloor.dashboard.settings.general.detail",
  "component": "GeneralSettingsView"
}

teachfloor.dashboard.settings.customization.detail

Displays on: Customization settings page Path: /:organization/settings/customization Use cases: Branding tools, theme extensions

{
  "viewport": "teachfloor.dashboard.settings.customization.detail",
  "component": "CustomizationView"
}

teachfloor.dashboard.settings.team.list

Displays on: Team management page Path: /:organization/settings/team Use cases: Team collaboration tools, role management

{
  "viewport": "teachfloor.dashboard.settings.team.list",
  "component": "TeamSettingsView"
}

teachfloor.dashboard.settings.billing.detail

Displays on: Billing settings page Path: /:organization/settings/billing Use cases: Usage analytics, cost tracking

{
  "viewport": "teachfloor.dashboard.settings.billing.detail",
  "component": "BillingView"
}

teachfloor.dashboard.settings.integration.list

Displays on: Integrations page Path: /:organization/settings/integrations Use cases: Third-party integrations, API tools

{
  "viewport": "teachfloor.dashboard.settings.integration.list",
  "component": "IntegrationView"
}

teachfloor.dashboard.settings.notification.list

Displays on: Notification settings page Path: /:organization/settings/notifications Use cases: Custom notification rules, digest tools

{
  "viewport": "teachfloor.dashboard.settings.notification.list",
  "component": "NotificationView"
}

teachfloor.dashboard.settings.custom-field.list

Displays on: Custom fields settings page Path: /:organization/settings/custom-fields Use cases: Custom field management, data import tools

{
  "viewport": "teachfloor.dashboard.settings.custom-field.list",
  "component": "CustomFieldView"
}

teachfloor.dashboard.settings.import.list

Displays on: Import data page Path: /:organization/settings/import Use cases: Bulk import tools, data migration

{
  "viewport": "teachfloor.dashboard.settings.import.list",
  "component": "ImportView"
}

teachfloor.dashboard.settings.app.list

Displays on: Apps settings page Path: /:organization/settings/apps Use cases: Installed apps, app marketplace

{
  "viewport": "teachfloor.dashboard.settings.app.list",
  "component": "AppListView"
}

User Management

teachfloor.dashboard.account.detail

Displays on: User account settings page Path: /:organization/account Use cases: Personal tools, user preferences, integrations

{
  "viewport": "teachfloor.dashboard.account.detail",
  "component": "AccountView"
}

teachfloor.dashboard.learner.list

Displays on: Learners management page Path: /:organization/learners Use cases: Learner analytics, bulk actions, import tools

{
  "viewport": "teachfloor.dashboard.learner.list",
  "component": "LearnerListView"
}

Commerce

teachfloor.dashboard.payment.list

Displays on: Payments page Path: /:organization/payments Use cases: Payment analytics, invoicing tools

{
  "viewport": "teachfloor.dashboard.payment.list",
  "component": "PaymentView"
}

App Settings

settings

Displays on: Your app's settings page Path: /:organization/settings/apps/:appId Use cases: App configuration, user preferences

{
  "viewport": "settings",
  "component": "AppSettingsView"
}

Viewport Context

When your app renders in a viewport, it receives context about the current page:

import { useExtensionContext } from '@teachfloor/extension-kit'

const MyView = () => {
  const { environment } = useExtensionContext()

  console.log(environment.viewport)  // "teachfloor.dashboard.course.detail"
  console.log(environment.path)      // "/myorg/courses/123"

  return <div>Current viewport: {environment.viewport}</div>
}

Available Context

environment: {
  initialized: boolean      // SDK ready state
  viewport: string         // Current viewport ID
  path: string            // Current URL path
}

Viewport Matching

How Matching Works

1. User navigates to a page (e.g., /myorg/courses)
2. Platform determines viewport (teachfloor.dashboard.course.list)
3. Platform finds apps with views matching the exact viewport
4. Matching app views are rendered in their designated positions

Example Scenario

Your app manifest:

{
  "ui_extension": {
    "views": [
      {
        "viewport": "teachfloor.dashboard.course.detail",
        "component": "CourseDetailView"
      },
      {
        "viewport": "teachfloor.dashboard.course.list",
        "component": "CourseListView"
      },
      {
        "viewport": "settings",
        "component": "SettingsView"
      }
    ]
  }
}

User visits course detail page (/org/courses/123):

• ✅ CourseDetailView renders (viewport: teachfloor.dashboard.course.detail)
• ❌ CourseListView does not render (different viewport)

User visits course list page (/org/courses):

• ✅ CourseListView renders (viewport: teachfloor.dashboard.course.list)
• ❌ CourseDetailView does not render (different viewport)

User visits app settings page (/org/settings/apps/yourapp):

• ✅ SettingsView renders (viewport: settings)

View Component Structure

Basic View Component

import React from 'react'
import { Container, Text, useExtensionContext } from '@teachfloor/extension-kit'

const CourseListView = () => {
  const { environment, userContext } = useExtensionContext()

  return (
    <Container>
      <Text>Hello {userContext.full_name}</Text>
      <Text size="sm" c="dimmed">
        You're viewing: {environment.viewport}
      </Text>
    </Container>
  )
}

export default CourseListView

Viewport-Aware Component

import React from 'react'
import { useExtensionContext } from '@teachfloor/extension-kit'

const SmartView = () => {
  const { environment } = useExtensionContext()

  // Render different UI based on viewport
  if (environment.viewport.includes('course.detail')) {
    return <CourseSpecificUI />
  }

  if (environment.viewport.includes('settings')) {
    return <SettingsUI />
  }

  return <DefaultUI />
}

Dynamic View Loader

import React from 'react'
import { ExtensionViewLoader } from '@teachfloor/extension-kit'
import manifest from '../../teachfloor-app.json'

const App = () => {
  return (
    <ExtensionViewLoader
      manifest={manifest}
      componentResolver={(componentName) => import(`./${componentName}`)}
    />
  )
}

export default App

Adding Views to Your App

Using CLI

teachfloor apps add view

1. Select viewport from list
2. Enter component name (PascalCase)
3. Choose whether to generate example code

Manual Addition

1. Create component file:

touch src/views/CourseListView.jsx

2. Update manifest:

{
  "ui_extension": {
    "views": [
      {
        "viewport": "teachfloor.dashboard.course.list",
        "component": "CourseListView"
      }
    ]
  }
}

3. Implement component:

import React from 'react'
import { Container, Text } from '@teachfloor/extension-kit'

const CourseListView = () => {
  return (
    <Container>
      <Text>My Course List Widget</Text>
    </Container>
  )
}

export default CourseListView

Removing Views

Using CLI

teachfloor apps remove view

Manual Removal

1. Delete component file
2. Remove from manifest:

{
  "ui_extension": {
    "views": [
      // Remove the view object
    ]
  }
}

Next Steps

→ Continue to Extension Kit Components

Additional Resources

• Best Practices - Viewport selection and performance optimization
• Troubleshooting Guide - Viewport issues and debugging
• Examples - Multi-viewport app examples
• Extension Kit Integration