MyListing Video Gallery Field
The {CODICTS} MyListing Video Gallery Field plugin adds a self-hosted video gallery field to the MyListing theme. Unlike external-URL-based video fields, this plugin allows listing owners to upload video files directly to the WordPress media library and display them in an interactive gallery on the single listing page — with a lightbox video player, automatic thumbnail generation, optional server-side video optimization, and role-based access restriction with visual blurring for unauthorized users.
Requirements
| Requirement | Details |
|---|---|
| FFmpeg + FFprobe (optional) | Only required if you enable the “Optimize Videos” feature for server-side transcoding |
Child theme required: The plugin copies template files into the child theme for the upload form field and display block. Without a child theme, the plugin cannot install its templates and will display an error notice.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
On activation, the plugin automatically copies its template files into your child theme. Navigate to any Listing Type → Fields tab to start adding the Video Gallery field.
Key Features
| Feature | Description |
|---|---|
| Direct Video Upload | AJAX-powered upload of video files (MP4, MPEG, WebM, OGG, FLV, MOV) directly to the WordPress media library. |
| Multiple Uploads | Upload multiple video files per listing with a configurable maximum limit. |
| Automatic Thumbnails | Video thumbnails are generated automatically on the client side — no server dependencies required. Works on both desktop and iOS. |
| Video Optimization | Optional server-side transcoding to MP4 with downscaling to 1080p (requires FFmpeg on the server). |
| Lightbox Player | Click any video thumbnail to open a full-screen lightbox video player. |
| Access Restriction | Role-based privacy control — blur thumbnails and lock playback for unauthorized users, with a lock icon replacing the play button. |
| Three Display Modes | Carousel, Carousel with Preview (large preview + thumbnail strip), and Grid view. |
| iOS Compatibility | Dedicated thumbnail rendering for iOS Safari/Chrome using native video elements. |
| CDN Compatible | Base64-encoded file references prevent CDN plugins from breaking attachment links. |
How It Works
1. A listing owner uploads video files via the AJAX-powered upload area on the add/edit listing form. Files are uploaded to the WordPress media library with a progress bar showing upload status.
2. If “Optimize Videos” is enabled (and FFmpeg is available on the server), uploaded videos are automatically transcoded to MP4 and downscaled to a maximum of 1080p resolution.
3. When the listing is saved, the uploaded videos are permanently attached to the listing. Any videos removed from the form are cleaned up from the media library.
4. On the single listing page, the display block renders video thumbnails in the configured layout (carousel, carousel with preview, or grid). Thumbnails are generated automatically on the visitor’s browser — a frame is extracted from each video and displayed as the thumbnail image with a play button overlay.
5. Clicking a thumbnail opens the video in a full-screen lightbox player. If access restriction is enabled, unauthorized users see blurred thumbnails with a lock icon and cannot play the videos.
Supported Video Formats
| Format | Extension |
|---|---|
| MP4 | .mp4 |
| MPEG | .mpeg |
| WebM | .webm |
| OGG | .ogg |
| FLV | .flv |
| QuickTime | .mov |
Adding the Video Gallery Field
1. Edit a listing type in the MyListing admin.
2. Navigate to the Fields tab.
3. Click the {C} Video Gallery button in the field sidebar to add the field.
4. Configure the field settings:
| Setting | Default | Description |
|---|---|---|
| Label | {C} Video Gallery | Display label for the field on the add/edit listing form. |
| Key | (auto-generated) | Unique field key for data storage. |
| Placeholder | (empty) | Placeholder text for the upload area. |
| Description | (empty) | Help text shown below the field. |
| Maximum Uploads | (empty = unlimited) | Maximum number of video files allowed per listing. Leave empty for no limit. |
| Optimize Videos | Off | When enabled, uploaded videos are transcoded to MP4 and downscaled to 1080p. Requires FFmpeg on the server. Warning: transcoding is CPU-intensive. |
| Required | No | Whether at least one video upload is mandatory. |
5. Save the listing type.
What Listing Owners See
On the add/edit listing form, listing owners see an upload area where they can select video files. Each upload shows a progress bar during transfer. After upload, video thumbnails appear with a play button overlay. Listing owners can remove videos by clicking the remove button on each thumbnail. The maximum number of uploads is enforced — if the limit is reached, additional uploads are prevented.
Adding the Display Block
1. Edit the same listing type.
2. Navigate to the Single Page tab.
3. Add a new content block and select “{C} Video Gallery”.
4. Configure the block settings:
| Setting | Default | Description |
|---|---|---|
| Title | {C} Video Gallery | Section heading displayed above the video gallery (e.g., “Videos,” “Highlights,” “Portfolio”). |
| Source Field | (none) | Select the Video Gallery field to display. Only Video Gallery fields appear in this list. |
| Gallery Type | Carousel | Display mode for the video gallery (see comparison below). |
| Restrict Access | Off | Enable role-based access restriction for the video gallery. |
| User Access Roles | (none) | WordPress user roles allowed to view videos. Visible when Restrict Access is enabled. |
5. Save the listing type.
Gallery Display Types
| Type | Description |
|---|---|
| Carousel | A horizontal slider showing up to 3 video thumbnails per row with navigation arrows. Click to play in lightbox. |
| Carousel with Preview | A large main preview area on top with a row of smaller thumbnail slides below for navigation. Click any to play in lightbox. |
| Grid | A responsive CSS grid of video thumbnails. Collapses to a single column on mobile. Click to play in lightbox. |
What Visitors See
On the single listing page, visitors see video thumbnails arranged in the configured layout. Each thumbnail has a play button overlay with a hover animation. Clicking any thumbnail opens the video in a full-screen lightbox player with a close button and dimmed background. The lightbox is responsive and works on both desktop and mobile.
Access Restriction
The plugin provides role-based access control for video galleries, allowing you to restrict who can view and play videos.
1. In the Video Gallery content block settings, enable “Restrict Access”.
2. Select the WordPress user roles that should be allowed to view the videos (e.g., Subscriber, Customer).
3. Save the listing type.
| User State | Thumbnail | Icon | Playback |
|---|---|---|---|
| Authorized (matching role) | Normal thumbnail | Play button (▶) | Lightbox opens and plays video. |
| Unauthorized (wrong role or logged out) | Blurred thumbnail | Lock icon (🔒) | No playback — clicking does nothing. |
The blurring is applied automatically — on desktop browsers via canvas-based blur, and on iOS via CSS. The play button SVG is replaced with a padlock icon to clearly indicate the content is restricted.
Tip: Use access restriction to create a registration incentive. Visitors see blurred video thumbnails indicating exclusive content is available, encouraging them to sign up for an account with the required role.
Video Optimization (Optional)
When “Optimize Videos” is enabled in the field settings, uploaded videos are processed on the server before being saved:
| Processing Step | What It Does |
|---|---|
| Transcode to MP4 | Re-encodes the video using H.264 codec with AAC audio for maximum browser compatibility. |
| Downscale to 1080p | Videos wider than 1920px are scaled down to 1080p resolution, reducing file size while maintaining quality. |
Important: This feature requires FFmpeg and FFprobe to be installed on your server. Ask your hosting provider to install them if not available. Video transcoding is CPU-intensive and may timeout on shared hosting — use with caution and consider dedicated hosting for heavy video processing.
If “Optimize Videos” is disabled (the default), videos are uploaded as-is without any server-side processing. Thumbnails are still generated automatically on the client side.
Example Setup — Listing Video Portfolio
1. Activate the plugin with the MyListing theme and a child theme active.
2. Edit a listing type (e.g., “Profiles” or “Businesses”).
3. On the Fields tab, add a {C} Video Gallery field. Set the Label to “Video Portfolio” and Maximum Uploads to 10. Leave “Optimize Videos” disabled unless FFmpeg is available on your server.
4. On the Single Page tab, add a “{C} Video Gallery” content block. Set the Title to “Video Portfolio,” Source Field to your Video Gallery field, and Gallery Type to “Carousel with Preview.”
5. Save the listing type.
6. A listing owner creates their profile and uploads 5 video files (MP4, WebM, etc.) via the upload area. Each file shows a progress bar during upload and a thumbnail preview once complete.
7. On the listing page, visitors see a large video preview area with a row of thumbnail slides below. Each thumbnail has a play button overlay. Clicking any video opens it in a full-screen lightbox player.
Example Setup — Members-Only Video Gallery
1. Follow the same field setup as above.
2. On the content block settings, enable “Restrict Access” and select the roles that should have access (e.g., “Subscriber” and “Customer”).
3. Save the listing type.
4. Logged-out visitors and users without the selected roles see blurred thumbnails with lock icons — they can see videos exist but cannot play them. This creates a registration incentive.
5. Users with the allowed roles see normal thumbnails with play buttons and can open any video in the lightbox player.
Frequently Asked Questions
Does this require a child theme?
Yes. The plugin copies template files into the child theme for the upload form field and display block. Without a child theme, the plugin cannot install its templates.
What video formats can be uploaded?
MP4, MPEG, WebM, OGG, FLV, and MOV (QuickTime). These are the supported formats for direct upload to the WordPress media library.
How are thumbnails generated?
Thumbnails are generated automatically on the visitor’s browser (client-side). The plugin extracts a video frame using HTML5 canvas on desktop browsers, or uses a native inline video element on iOS. No server-side software is needed for thumbnail generation.
Do I need FFmpeg?
No — not for core functionality. FFmpeg is only required if you enable the optional “Optimize Videos” feature, which transcodes uploaded videos to MP4 and downscales them to 1080p. Without FFmpeg, videos are uploaded as-is and thumbnails are generated on the client side.
What does “Optimize Videos” do?
When enabled, uploaded videos are re-encoded to H.264 MP4 with AAC audio and downscaled to a maximum of 1080p resolution. This ensures maximum browser compatibility and reduced file sizes. It requires FFmpeg and FFprobe on the server and is CPU-intensive.
How does access restriction work?
Enable “Restrict Access” on the content block and select which WordPress user roles can view videos. Authorized users see normal thumbnails with play buttons. Unauthorized users (wrong role or logged out) see blurred thumbnails with lock icons and cannot play the videos.
Does the lightbox work on mobile?
Yes. The lightbox player is responsive and works on both desktop and mobile browsers. The plugin includes specific compatibility fixes for iOS Safari and Chrome.
Can I limit how many videos users can upload?
Yes. Set “Maximum Uploads” in the field settings to your desired limit. Leave empty for unlimited uploads.
What’s the maximum file size for uploads?
The maximum file size is governed by your server’s PHP settings: upload_max_filesize and post_max_size. Contact your hosting provider to increase these limits if needed. WordPress’s own wp_max_upload_size() also applies.
Does the plugin work with CDN plugins?
Yes. The plugin uses Base64-encoded file references internally to prevent CDN and media offload plugins from breaking attachment links. This is handled automatically — no configuration needed.
Does the plugin create any database tables?
No. Videos are stored as standard WordPress attachments in the media library, linked to the listing. Video gallery data is stored as post meta on the listing. The plugin also stores processed files (if optimization is enabled) in wp-content/uploads/codicts_video_gallery/.
What happens when the plugin is deactivated?
The template files are removed from the child theme and the field and block will no longer appear. Uploaded video files remain in the WordPress media library. Reactivating the plugin restores full functionality with existing data intact.
Troubleshooting
Field Not Appearing in Listing Type Editor
| Cause | Solution |
|---|---|
| Templates not installed | Deactivate and reactivate the plugin to force-reinstall templates. Verify template files exist in your child theme’s templates/ directory. |
| Plugin not activated | Go to Plugins → Installed Plugins and verify the plugin is active. |
| MyListing or child theme not active | Both the MyListing theme and a child theme must be active. |
Video Uploads Fail or Show an Error
| Cause | Solution |
|---|---|
| Unsupported file format | Only MP4, MPEG, WebM, OGG, FLV, and MOV files are accepted. Convert your video to a supported format before uploading. |
| File too large | Check your server’s upload_max_filesize and post_max_size PHP settings. Contact your hosting provider to increase them for large video files. |
| Upload directory not writable | Verify the wp-content/uploads/ directory and its subdirectories have proper write permissions. |
| JavaScript error | Check the browser console (F12 → Console) for errors. Ad blockers or other plugins may interfere with the AJAX upload. |
Upload Progress Bar Appears But Never Completes
| Cause | Solution |
|---|---|
| Server timeout | Large video files may exceed your server’s execution time limit. Increase max_execution_time in your PHP configuration, or upload smaller files. |
| Optimize Videos enabled without FFmpeg | If “Optimize Videos” is on but FFmpeg isn’t installed, processing may fail silently. Disable the option or install FFmpeg on your server. |
Thumbnails Not Appearing for Videos
| Cause | Solution |
|---|---|
| JavaScript blocked | Thumbnails are generated client-side via JavaScript. Ensure JavaScript is enabled and not blocked by ad blockers or browser extensions. |
| CORS issues | The video file must be accessible from the browser. If using a CDN, ensure proper CORS headers are set to allow video loading from the listing page’s domain. |
| iOS compatibility | Ensure you’re running plugin version 1.5.3 or later, which includes iOS-specific thumbnail fixes. |
Videos Show Lock Icon Instead of Play Button
| Cause | Solution |
|---|---|
| Access restriction enabled | “Restrict Access” is enabled on the content block. Either disable it in the block settings, or ensure the viewing user has one of the allowed roles. Log out and view in an incognito window to test the unauthorized experience. |
Clicking Thumbnails Doesn’t Open the Video Player
| Cause | Solution |
|---|---|
| Lightbox scripts not loading | The lightbox requires both JavaScript and CSS files to load. Check the browser console for script loading errors or conflicts with other plugins. |
| Access restriction active | If the user is unauthorized, clicking does nothing by design. Check if Restrict Access is enabled. |
“Optimize Videos” Not Working
| Cause | Solution |
|---|---|
| FFmpeg not installed | This feature requires FFmpeg and FFprobe on the server. Ask your hosting provider to install them. Run ffmpeg -version via SSH to verify. |
| Shared hosting limitations | Video transcoding is CPU-intensive and may timeout on shared hosting. Consider dedicated or VPS hosting for this feature. |
Template Overwrite Warning
The following template files in your child theme are managed by this plugin and will be overwritten on reactivation and updates:
templates/add-listing/form-fields/video-gallery-field.php
templates/single-listing/content-blocks/video-gallery-block.phpIf you’ve customized these files, back up your changes before updating the plugin or deactivating/reactivating it.
“MyListing Theme Not Detected” or “Child Theme Not Detected” Error
The MyListing theme and a child theme must both be installed and active. Go to Appearance → Themes to verify.
For further support, visit codicts.com or contact us at support@codicts.com.