VN Mixed Content Lightbox Gallery

A lightweight, high-performance WordPress plugin for rendering mixed content galleries (images, YouTube, Vimeo, iframes) using lightGallery.js and MetaBox.io.

📋 Overview

This plugin is a renderer that displays beautiful galleries from data managed by MetaBox.io. It follows the Single Responsibility Principle - you manage data with MetaBox, and we handle the display.

✨ Features

• 🎨 Mixed Content: Images, YouTube, Vimeo, iframe content in one gallery
• 🚀 High Performance: Lightweight, follows WordPress best practices
• 📱 Responsive: Perfect on all devices
• 🔍 Filtering: Optional filter buttons (All, Images, Videos)
• 🎯 MetaBox Integration: Seamless MetaBox.io integration
• ⚡ Conflict Resolution: Auto-handles Flatsome's Magnific Popup conflicts
• 🎬 Auto Thumbnails: YouTube thumbnail generation
• 📝 Captions: Title and description support

🔧 Requirements

• WordPress 5.0+
• PHP 7.4+
• MetaBox.io plugin

📦 Installation

1. Install Plugin

cd wp-content/plugins/
git clone [your-repo] vn-gallery
# or upload zip through WordPress admin

2. Download lightGallery Assets

IMPORTANT: Due to licensing, lightGallery files are NOT included.

Download from: https://www.lightgalleryjs.com/

Required files:

vn-gallery/
├── assets/
│   ├── js/
│   │   ├── lightgallery.min.js          ← DOWNLOAD
│   │   └── plugins/
│   │       ├── lg-video.min.js          ← DOWNLOAD
│   │       ├── lg-thumbnail.min.js      ← DOWNLOAD
│   │       └── lg-zoom.min.js           ← DOWNLOAD
│   └── css/
│       └── lightgallery.min.css         ← DOWNLOAD

3. Activate Plugin

wp plugin activate vn-gallery
# or through WordPress admin

🎯 MetaBox Configuration

Field Structure (Required)

Create a MetaBox Group/Repeater with these exact sub-field names:

Example MetaBox Registration

add_filter( 'rwmb_meta_boxes', 'register_mixed_gallery_metabox' );

function register_mixed_gallery_metabox( $meta_boxes ) {
    $meta_boxes[] = [
        'title'      => 'Mixed Content Gallery',
        'id'         => 'mixed_gallery',
        'post_types' => ['page', 'post'],
        'fields'     => [
            [
                'id'     => 'my_gallery_field',
                'name'   => 'Gallery Items',
                'type'   => 'group',
                'clone'  => true,
                'sort_clone' => true,
                'fields' => [
                    // item_type
                    [
                        'id'      => 'item_type',
                        'name'    => 'Content Type',
                        'type'    => 'select',
                        'options' => [
                            'image' => 'Image',
                            'video' => 'Video/Iframe',
                        ],
                        'std'     => 'image',
                    ],

                    // item_image (conditional)
                    [
                        'id'               => 'item_image',
                        'name'             => 'Select Image',
                        'type'             => 'image_advanced',
                        'max_file_uploads' => 1,
                        'hidden'           => ['item_type', '!=', 'image'],
                    ],

                    // item_video_url (conditional)
                    [
                        'id'          => 'item_video_url',
                        'name'        => 'Video URL',
                        'type'        => 'url',
                        'placeholder' => 'https://youtube.com/watch?v=...',
                        'hidden'      => ['item_type', '!=', 'video'],
                    ],

                    // item_title
                    [
                        'id'   => 'item_title',
                        'name' => 'Title',
                        'type' => 'text',
                    ],

                    // item_description
                    [
                        'id'   => 'item_description',
                        'name' => 'Description',
                        'type' => 'textarea',
                        'rows' => 3,
                    ],

                    // item_thumbnail (optional)
                    [
                        'id'               => 'item_thumbnail',
                        'name'             => 'Custom Thumbnail',
                        'desc'             => 'Optional. Leave empty to auto-generate.',
                        'type'             => 'image_advanced',
                        'max_file_uploads' => 1,
                    ],
                ],
            ],
        ],
    ];

    return $meta_boxes;
}

🚀 Usage

Basic Shortcode

[mixed_gallery field="my_gallery_field"]

Shortcode Attributes

Examples

<!-- Default gallery with filters -->
[mixed_gallery field="my_gallery_field"]

<!-- Gallery without filters -->
[mixed_gallery field="my_gallery_field" filters="false"]

<!-- Gallery from another post -->
[mixed_gallery field="my_gallery_field" post_id="123"]

<!-- Combine attributes -->
[mixed_gallery field="gallery_main" post_id="456" filters="true"]

🎬 Supported Video Sources

🏗️ Architecture

File Structure

vn-gallery/
├── vn-gallery.php                  # Main plugin file
├── readme.txt                      # WordPress.org readme
├── README.md                       # This file
├── includes/
│   ├── class-mcl-assets.php        # Assets management
│   └── class-mcl-shortcode.php     # Shortcode handler
└── assets/
    ├── js/
    │   ├── frontend-main.js        # Custom JS (included)
    │   ├── lightgallery.min.js     # lightGallery core (DOWNLOAD)
    │   └── plugins/
    │       ├── lg-video.min.js     # Video plugin (DOWNLOAD)
    │       ├── lg-thumbnail.min.js # Thumbnail plugin (DOWNLOAD)
    │       └── lg-zoom.min.js      # Zoom plugin (DOWNLOAD)
    └── css/
        ├── frontend-main.css       # Custom CSS (included)
        └── lightgallery.min.css    # lightGallery CSS (DOWNLOAD)

Design Principles

1. Single Responsibility: Renderer only, no data management
2. Lazy Loading: Assets load only when shortcode is present
3. Conflict Resolution: Auto-handles competing libraries
4. WordPress Standards: Follows WP coding standards
5. SOLID Principles: Clean, maintainable code

Class Diagram

VN_Gallery (Bootstrap)
├── MCL_Assets (Asset Management)
│   ├── register_assets()
│   ├── enqueue_assets()
│   └── handle_flatsome_conflict()
└── MCL_Shortcode (Shortcode Handler)
    ├── render_shortcode()
    ├── render_filters()
    ├── render_gallery_grid()
    └── render_gallery_item()

🎨 Customization

CSS Customization

Override styles in your theme:

/* Change grid columns */
.vn-gallery-grid {
    grid-template-columns: repeat(4, 1fr);
}

/* Customize filter buttons */
.vn-filter-btn.active {
    background: #your-color;
}

/* Adjust thumbnail aspect ratio */
.vn-gallery-item {
    aspect-ratio: 16 / 9;
}

JavaScript Hooks

Trigger gallery reload after AJAX:

jQuery(document).trigger('vn-gallery-reload');

🐛 Troubleshooting

Gallery Not Showing

1. ✅ MetaBox.io installed and active?
2. ✅ lightGallery files downloaded and placed correctly?
3. ✅ Field name matches in MetaBox and shortcode?
4. ✅ Browser console shows errors?

Conflict with Flatsome

The plugin auto-handles this, but if issues persist:

// Manually dequeue in your theme
add_action( 'wp_enqueue_scripts', function() {
    if ( has_shortcode( get_the_content(), 'mixed_gallery' ) ) {
        wp_dequeue_script( 'magnific-popup' );
    }
}, 100 );

Videos Not Playing

• ✅ Correct URL format?
  • YouTube: https://youtube.com/watch?v=VIDEO_ID
  • Vimeo: https://vimeo.com/VIDEO_ID
• ✅ Video is public/embeddable?

📝 Development

Coding Standards

• WordPress Coding Standards (WPCS)
• PHP 7.4+ features (typed properties, return types)
• declare(strict_types=1) enforced
• Tabs for indentation
• Proper escaping and sanitization

Testing

# Check PHP syntax
find . -name "*.php" -exec php -l {} \;

# WordPress Coding Standards
phpcs --standard=WordPress .

# Fix auto-fixable issues
phpcbf --standard=WordPress .

🔮 Roadmap

• [ ] ACF support
• [ ] Self-hosted video (MP4) support
• [ ] Vimeo API thumbnail integration
• [ ] Custom filters (hook system)
• [ ] Lazy load thumbnails
• [ ] Masonry layout option
• [ ] Lightbox customization filters

📄 License

GPL v2 or later - https://www.gnu.org/licenses/gpl-2.0.html

👨‍💻 Author

VN - WP Mastery Now

🙏 Credits

• lightGallery.js - Awesome lightbox library
• MetaBox.io - Powerful custom fields framework

📞 Support

For support and documentation, visit WP Mastery Now

Made with ❤️ for the WordPress community