Nopio Video

NopioVideo Documentation

Overview

NopioVideo is a comprehensive PHP service class for handling video embedding and rendering in WordPress themes. It supports YouTube, Vimeo, and direct file videos with flexible display modes, time ranges, modal integration, and advanced customization options.

Resources

  • Service Class: inc/services/nopio-video.php
  • Placeholder Service: inc/services/nopio-placeholder-image.php
  • Modal Service: inc/services/nopio-modal.php
  • Test Suite: test-nopio-video-service.php

Video Types

NopioVideo automatically detects and supports three video types:

YouTube

Supports various YouTube URL formats:

  • https://youtube.com/watch?v=VIDEO_ID
  • https://youtu.be/VIDEO_ID
  • https://youtube.com/embed/VIDEO_ID
  • https://youtube.com/shorts/VIDEO_ID
  • Direct video ID: VIDEO_ID

Vimeo

Supports various Vimeo URL formats:

  • https://vimeo.com/VIDEO_ID
  • https://player.vimeo.com/video/VIDEO_ID
  • Direct video ID: VIDEO_ID

File Videos

Direct video file URLs (typically MP4):

  • https://example.com/path/to/video.mp4
  • Any valid video file URL

Display Modes

Background Mode (bg)

Background videos are designed to play automatically, loop continuously, and remain muted. Perfect for hero sections and background elements.

Characteristics:

  • Autoplay enabled
  • Looping enabled
  • Muted by default
  • No controls visible
  • Optimized for performance

Inline Mode (inline)

Inline videos display with a play button overlay and can be controlled by the user. Perfect for content sections.

Characteristics:

  • Play button overlay
  • User-initiated playback
  • Optional controls
  • Preview mode support
  • Fullscreen support

Basic Usage

Simple Background Video

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'bg',
];
 
$video = new NopioVideo($settings);
echo $video->render();

Simple Inline Video

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'play_button_text' => 'Watch Video',
];
 
$video = new NopioVideo($settings);
echo $video->render();

File Video

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'inline',
];
 
$video = new NopioVideo($settings);
echo $video->render();

Configuration Options

The constructor accepts an array of settings with the following options:

Required Settings

  • video_code (string, required): Video URL or embed code
    • YouTube URL, Vimeo URL, or direct file URL
    • Can be full URL or just video ID for YouTube/Vimeo

Display Settings

  • display_type (string, default: 'bg'): Display mode
    • 'bg' or 'background' - Background video mode
    • 'inline' - Inline video mode

Time Range Settings

  • start_time (int|null, optional): Start time in seconds

    • When set, video will start at this timestamp
    • Only works with streaming videos (YouTube/Vimeo) when Player API is enabled

  • end_time (int|null, optional): End time in seconds

    • When set, video will stop at this timestamp
    • Only works with streaming videos (YouTube/Vimeo) when Player API is enabled

Playback Settings

  • enable_autoplay (int, default: 0): Enable autoplay for inline videos

    • 0 - No autoplay
    • 1 - Autoplay enabled

  • enable_preview (int, default: 0): Enable preview mode

    • 0 - No preview
    • 1 - Preview enabled

  • enable_full_screen (int, default: 0): Enable fullscreen support

    • 0 - No fullscreen
    • 1 - Fullscreen enabled

Play Button Settings

  • play_button_text (string, default: 'Watch Video'): Text for play button

    • Custom text displayed on the play button
    • Only applies to inline videos

  • play_button_classes (string, optional): Additional CSS classes for play button

    • Space-separated list of CSS classes

  • play_button_html (string, optional): Custom HTML for play button wrapper

    • Overrides default play button HTML

Placeholder Image Settings

  • placeholder_image (mixed, default: false): Placeholder image configuration
    • false or 0 - No placeholder
    • true or 1 - Use default placeholder (auto-generated for YouTube/Vimeo)
    • WordPress attachment ID (int) - Use WordPress media attachment
    • HTML string - Custom HTML for placeholder
    • URL string - Direct image URL

Modal Settings

  • enable_modal (bool, default: false): Enable modal mode
    • true - Video opens in Bootstrap modal
    • false - Normal video display
    • Requires NopioModal class to be available

Cursor Settings

  • enable_cursor (int, default: 0): Enable custom cursor effects

    • 0 - No custom cursor
    • 1 - Custom cursor enabled on play button

  • cursor_class (string, default: 'cursor--video'): CSS class for custom cursor

    • Applied to play button wrapper when cursor is enabled

Advanced Settings

  • video_index (int, default: random): Unique index for video container ID
    • Used to generate unique container IDs: video-placeholder-{index}
    • Set explicitly if you need predictable IDs

Advanced Features

Time Ranges

Set start and end times for video playback:

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'bg',
    'start_time' => 10,  // Start at 10 seconds
    'end_time' => 30,    // End at 30 seconds
];
 
$video = new NopioVideo($settings);
echo $video->render();

Note: Time ranges require Player API for YouTube/Vimeo videos. The service automatically enables Player API when time ranges are set.

Modal Mode

Display videos in a Bootstrap modal:

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'bg',
    'enable_modal' => true,
    'play_button_text' => 'Open Video',
];
 
$video = new NopioVideo($settings);
echo $video->render();

The modal uses the template at parts/modal-video.php and requires Bootstrap 5 modal JavaScript.

Preview Mode

Enable preview mode for inline videos:

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'enable_preview' => 1,
    'start_time' => 10,
    'end_time' => 12,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Fullscreen Support

Enable fullscreen functionality:

$settings = [
    'video_code' => 'https://example.com/video.mp4',
    'display_type' => 'inline',
    'enable_full_screen' => 1,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Custom Cursor

Enable custom cursor effects on play button:

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'inline',
    'enable_cursor' => 1,
    'cursor_class' => 'cursor--video-dark', // Optional custom class
];
 
$video = new NopioVideo($settings);
echo $video->render();

Placeholder Images

Placeholder images are displayed before video playback starts. Multiple formats are supported:

WordPress Attachment ID

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'inline',
    'placeholder_image' => 123, // WordPress attachment ID
];
 
$video = new NopioVideo($settings);
echo $video->render();

HTML String

$settings = [
    'video_code' => 'https://example.com/video.mp4',
    'display_type' => 'inline',
    'placeholder_image' => '<img src="placeholder.jpg" alt="Video thumbnail" class="stretch-img">',
];
 
$video = new NopioVideo($settings);
echo $video->render();

URL String

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'placeholder_image' => 'https://example.com/thumbnail.jpg',
];
 
$video = new NopioVideo($settings);
echo $video->render();

Auto-Generated (YouTube/Vimeo)

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'placeholder_image' => true, // Auto-fetch from Vimeo oEmbed API
];
 
$video = new NopioVideo($settings);
echo $video->render();

Note: For Vimeo videos, the service automatically fetches the thumbnail from Vimeo's oEmbed API when placeholder_image is set to true.

CSS Classes and Data Attributes

Generated CSS Classes

Background Videos

  • YouTube: l__bg l__bg--youtube js-video-background-youtube
  • Vimeo: l__bg l__bg--vimeo js-video-background-vimeo
  • File: js-video-background-file

Inline Videos

  • YouTube: l__inline l__inline--youtube js-video-inline-youtube
  • Vimeo: l__inline l__inline--vimeo js-video-inline-vimeo
  • File: js-video-inline js-video-inline-file l__inline l__inline--file

Data Attributes

The service generates data attributes for JavaScript integration:

  • data-video-id: Video ID (YouTube/Vimeo) or empty (file videos)
  • data-video-src: Direct video URL (file videos only)
  • data-video-start: Start time in seconds
  • data-video-end: End time in seconds
  • data-autoplay: Autoplay flag (0 or 1)
  • data-preview: Preview mode flag (0 or 1)
  • data-full-screen: Fullscreen flag (0 or 1)

Container IDs

Container IDs follow the pattern: video-placeholder-{video_index}

Example:

<div id="video-placeholder-12345" class="l__bg l__bg--youtube js-video-background-youtube">

Debugging

Using the debug() Method

The service provides a debug method to inspect video configuration:

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'bg',
    'start_time' => 10,
    'end_time' => 30,
];
 
$video = new NopioVideo($settings);
$video->debug();

This outputs formatted debug information including:

  • Video type detection
  • Video ID extraction
  • Time range settings
  • Player API requirements
  • All normalized settings

Common Issues

Video Not Playing

  • Check that video_code is valid and accessible
  • Verify video type is correctly detected
  • For YouTube/Vimeo, ensure video is publicly accessible
  • Check browser console for JavaScript errors

Time Ranges Not Working

  • Time ranges only work with YouTube/Vimeo videos
  • Ensure Player API is enabled (automatic when time ranges are set)
  • Verify JavaScript video handlers are loaded

Modal Not Opening

  • Ensure NopioModal class is available
  • Check that Bootstrap 5 modal JavaScript is loaded
  • Verify modal template exists at parts/modal-video.php
  • Check that enable_modal is set to true

Placeholder Not Showing

  • Verify placeholder_image setting is correct
  • For WordPress attachments, ensure attachment ID is valid
  • Check that image URL is accessible
  • For Vimeo auto-fetch, verify oEmbed API is reachable

Examples from Test Cases

Example 1: Background YouTube Video

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'bg',
    'video_index' => rand(),
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 2: Background Vimeo Video

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'bg',
    'video_index' => rand(),
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 3: Background File Video

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'bg',
    'video_index' => rand(),
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 4: Inline YouTube Video with Placeholder

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'inline',
    'video_index' => rand(),
    'play_button_text' => 'Watch Video',
    'placeholder_image' => true,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 5: Inline Vimeo Video with Placeholder

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'video_index' => rand(),
    'play_button_text' => 'Watch Video',
    'placeholder_image' => true,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 6: Inline File Video with HTML Placeholder

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'inline',
    'video_index' => rand(),
    'play_button_text' => 'Watch Video',
    'placeholder_image' => '<img fetchpriority="high" decoding="async" class="stretch-img" alt="" src="https://example.com/thumbnail.jpg" width="1990" height="1119">',
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 7: Background YouTube with Time Range

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'bg',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 8: Background Vimeo with Time Range

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'bg',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 9: Background File with Time Range

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'bg',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 10: Inline YouTube with Preview Mode

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 11: Inline Vimeo with Preview Mode

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 12: Inline File with Preview Mode

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 13: Inline YouTube with Custom Cursor

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
    'enable_cursor' => 1,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 14: Inline Vimeo with Custom Cursor

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
    'enable_cursor' => 1,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 15: Inline File with Custom Cursor

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
    'enable_cursor' => 1,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 16: Inline YouTube with Fullscreen

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
    'enable_cursor' => 1,
    'enable_full_screen' => true,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 17: Inline Vimeo with Fullscreen

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
    'enable_cursor' => 1,
    'enable_full_screen' => true,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 18: Inline File with Fullscreen

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'inline',
    'video_index' => rand(),
    'start_time' => 10,
    'end_time' => 12,
    'enable_preview' => 1,
    'enable_controls' => 1,
    'enable_cursor' => 1,
    'enable_full_screen' => true,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 19: Modal YouTube Video

$settings = [
    'video_code' => 'https://youtu.be/4zVxpjQxNzA',
    'display_type' => 'bg',
    'video_index' => rand(),
    'enable_modal' => true,
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 20: Modal Vimeo Video

$settings = [
    'video_code' => 'https://vimeo.com/690465271',
    'display_type' => 'bg',
    'video_index' => rand(),
    'enable_modal' => true,
    'play_button_text' => 'Open Vimeo Modal',
];
 
$video = new NopioVideo($settings);
echo $video->render();

Example 21: Modal File Video

$settings = [
    'video_code' => 'https://example.com/videos/video.mp4',
    'display_type' => 'bg',
    'video_index' => rand(),
    'enable_modal' => true,
    'play_button_text' => 'Open File Modal',
];
 
$video = new NopioVideo($settings);
echo $video->render();

API Reference

Methods

__construct(array $settings)

Constructor that initializes the video service with configuration settings.

Parameters:

  • $settings (array): Configuration array (see Configuration Options)

Returns: NopioVideo instance

render(string|null $display_mode = null): string

Renders the video HTML output.

Parameters:

  • $display_mode (string|null): Optional display mode override ('bg', 'background', or 'inline')

Returns: string - HTML output

getVideoId(): string|null

Gets the extracted video ID.

Returns: string|null - Video ID or null

getData(): array

Gets structured video data for rendering.

Returns: array - Video data with keys: type, id, url, use_player_api, video_code, start_time, end_time, poster_url

setTimeRange(int|null $start, int|null $end): void

Sets time range for video playback.

Parameters:

  • $start (int|null): Start time in seconds
  • $end (int|null): End time in seconds

Returns: void

debug(): void

Outputs debug information about the video configuration.

Returns: void

Integration Notes

JavaScript Requirements

The rendered HTML includes data attributes and CSS classes that require JavaScript handlers:

  • Background videos: JavaScript handlers for js-video-background-* classes
  • Inline videos: JavaScript handlers for js-video-inline-* classes
  • Modal videos: Bootstrap 5 modal JavaScript
  • Custom cursor: Custom cursor JavaScript component

WordPress Integration

The service integrates with WordPress functions:

  • esc_attr() - Attribute escaping
  • esc_html() - HTML escaping
  • esc_url() - URL escaping
  • add_query_arg() - URL parameter building
  • wp_remote_get() - HTTP requests (for Vimeo oEmbed)
  • wp_get_attachment_url() - WordPress media URLs

Template Integration

When using in WordPress templates:

<?php
require_once get_template_directory() . '/inc/services/nopio-video.php';
 
$settings = [
    'video_code' => get_field('video_url'), // ACF example
    'display_type' => 'inline',
    'play_button_text' => 'Watch Video',
];
 
$video = new NopioVideo($settings);
echo $video->render();
?>

Best Practices

  1. Always provide a placeholder image for better user experience and SEO
  2. Use unique video_index when rendering multiple videos on the same page
  3. Set explicit time ranges for long videos to improve performance
  4. Enable modal mode for background videos that need user interaction
  5. Test video accessibility - ensure videos are publicly accessible
  6. Use appropriate display modes - background for hero sections, inline for content
  7. Leverage WordPress attachment IDs for placeholder images when possible
  8. Enable preview mode for inline videos with time ranges to show specific segments
Nopio Alm FilterNopioModal Class