Tutorials

Overview

The Tutorials panel provides users with access to a curated collection of video tutorials and documentation that help them learn how to use different features of the Shakudo Dashboard. Tutorials are fetched from a remote CDN and cover various platform capabilities including sessions, jobs, microservices, and stack components. The panel provides an interactive, searchable gallery of tutorial cards with video previews and links to detailed documentation.

Access & Location

• Route: ?panel=tutorials
• Navigation: Root Menu → Tutorials
• Access Requirements: None (available to all authenticated users)
• Feature Flags: None

Key Capabilities

Browse Tutorials

Users can browse through all available tutorials in a responsive grid layout. Each tutorial is displayed as a card with a preview image or video, title, and description.

Search Tutorials

The search functionality allows users to quickly find relevant tutorials by searching through tutorial titles and descriptions. The search uses fuzzy matching to provide flexible results.

Watch Tutorial Videos

Tutorials that include video content can be watched directly in the dashboard through an interactive video dialog. Videos autoplay on hover and can be expanded to full-screen viewing.

Access Documentation

For tutorials that include written documentation, users can click to open the documentation in a new browser tab, providing detailed step-by-step instructions.

User Interface

Main View

The tutorials panel displays a grid of tutorial cards (3 columns on desktop, responsive on mobile). Each card shows:

• Preview image or looping video (160px height on home panel, 220px height on tutorials panel)
• Tutorial title
• Brief description (truncated to 2 lines)
• Hover interactions that reveal video controls and expand icons

At the top of the panel:

• Panel title: "Tutorials"
• Search bar with placeholder text "Search Tutorials"
• Loading spinner during data fetch
• Error/empty state alerts when appropriate

Dialogs & Modals

1. Tutorial Video Dialog
   • Purpose: Provides full-screen viewing of tutorial videos
   • Fields:
     • Video player with controls
     • Title overlay (shown on hover)
     • Description overlay (shown on hover)
   • Actions:
     • Play/pause video
     • Close dialog (X button in top-right)
     • Hover to reveal title and description overlay

Tables & Data Grids

No tables are used in this feature. Content is displayed as a grid of cards.

Technical Details

GraphQL Operations

This feature does not use GraphQL operations. Tutorial data is fetched directly from an external CDN.

External Data Source:

• URL: https://raw.githubusercontent.com/devsentient/cdn/main/tutorials-list.json
• Format: JSON array of tutorial objects
• Fetched via standard HTTP fetch API

Tutorial Object Schema:

{
  tutorial_id: string;
  title: string;
  description: string;
  video_url?: string;          // Optional video content
  preview_image_url: string;   // Thumbnail/preview image
  usage_docs_url?: string;     // Link to documentation
  component?: string;          // Associated dashboard component
}

Component Structure

• Main Component: /components/Tutorials/TutorialPanel.tsx
• Card Component: /components/Tutorials/TutorialCard.tsx
• Video Dialog: /components/Tutorials/TutorialVideoDialog.tsx
• Component Tutorial: /components/Tutorials/TutorialComponent.tsx (for inline tutorials)
• Hook: /hooks/useFetchTutorial.ts
• Search Integration: /components/Search/TutorialsSearchResults.tsx

Search Implementation

The tutorials panel uses two search mechanisms:

1. Panel Search: Simple text filtering on title and description (case-insensitive substring match)
2. Global Search: Fuse.js fuzzy search integration with 0.6 threshold for platform-wide search results

Common Workflows

Finding a Tutorial

1. Navigate to Tutorials panel via sidebar menu
2. Browse the grid of available tutorials
3. Use the search bar to filter by keywords
4. Click on a tutorial card to view

Watching a Tutorial Video

1. Find a tutorial with video content (indicated by video preview)
2. Hover over the card to see video preview autoplay
3. Click the card or expand icon to open full-screen video dialog
4. Video plays with controls available
5. Hover over video to see title/description overlay
6. Close dialog when finished

Accessing Documentation

1. Find a tutorial (typically without video content)
2. Click the tutorial card
3. Documentation opens in a new browser tab
4. Follow step-by-step instructions in the documentation

Home Panel Integration

1. The home panel displays a filtered subset of tutorials
2. Only tutorials with documentation links are shown (filtered by usage_docs_url)
3. Search bar is disabled on home panel
4. Cards are smaller (160px vs 220px height)
5. Provides quick access to getting started resources

Related Features

• Home Panel - Displays featured tutorials in the "Get Started" section
• Stack Components - Many tutorials relate to installed stack components
• Component-specific tutorials - Inline tutorials shown within specific dashboard panels

Notes & Tips

• Caching: Tutorial data is fetched fresh on each panel load with a 250ms artificial delay for smooth loading transitions
• Video Performance: Videos on cards use autoPlay and muted attributes to play automatically on hover without sound
• Responsive Design: Grid adjusts from 3 columns (desktop) to 1 column (mobile) for optimal viewing
• Error Handling: If tutorial data fails to load, users see a friendly error message instead of broken UI
• Empty States: When no tutorials match a search query, an informative message is displayed
• Component Integration: Tutorials can be associated with specific dashboard components via the component field for contextual help
• External Content: All tutorial content is managed externally through the CDN, allowing updates without code deployments
• Search Integration: Tutorials are searchable through both the panel-specific search bar and the global platform search (Cmd+K)