Wix Pro Gallery Custom JS: Fixing Masonry Layout for External Images

Unlocking Dynamic Image Layouts in Wix Pro Gallery with Custom Code

For e-commerce store owners and developers seeking to integrate external media seamlessly into their Wix websites, the Wix Pro Gallery offers powerful customization options. However, a common challenge arises when attempting to programmatically populate a Pro Gallery with external images, especially when aiming for advanced layouts like Masonry. While the Pro Gallery excels at dynamic resizing and arrangement for images uploaded directly through the Wix editor, integrating custom JavaScript to fetch images from an external server can sometimes disrupt this sophisticated layout engine, leading to unexpected cropping instead of intelligent resizing.

The Core Challenge: Programmatic vs. Editor-Loaded Content

The issue typically manifests when a store owner uses custom Velo (Wix's development platform) code to fetch image URLs from their own server and assign them to a Pro Gallery component. Despite configuring the gallery for a 'Custom' Masonry layout with specific settings (e.g., vertical layout, items per row, spacing), the images appear in a rigid grid. Instead of adapting to varying aspect ratios, the gallery crops images to fit a uniform size, negating the very purpose of a Masonry layout.

This discrepancy highlights a crucial difference in how the Wix Pro Gallery processes content:

Editor-Loaded Images: When images are uploaded via the Wix editor, the platform's internal mechanisms likely pre-process each image. This includes extracting critical metadata such as natural width and height, which are then stored and used by the gallery's layout engine to calculate optimal placement and resizing for dynamic layouts like Masonry.
Programmatically Loaded Images: When images are loaded via custom JavaScript, the gallery component receives only the basic properties provided in the items array (e.g., src and type). Without explicit dimension data for external images, the gallery's layout engine defaults to a simpler, less intelligent grid-like behavior, resulting in cropping. The component behaves as if it's missing vital information for its advanced layout calculations.

The Solution: Providing Explicit Image Dimensions

To ensure the Wix Pro Gallery's Masonry layout functions correctly with programmatically loaded external images, it's imperative to provide the gallery component with the width and height properties for each image. These dimensions allow the gallery's layout algorithm to accurately determine how to arrange and resize images of different aspect ratios, achieving the desired dynamic and visually appealing Masonry effect.

Implementing the Fix: Step-by-Step

Here’s how to modify your custom JavaScript to include image dimensions:

Enhance Your Image Data Retrieval: Your custom function (e.g., getMedia()) should ideally retrieve or allow for the retrieval of image dimensions alongside their URLs. If your server API can provide this, it's the most efficient approach.
Dynamically Fetch Dimensions (Client-Side Fallback): If your server cannot provide dimensions, you'll need to fetch them client-side using JavaScript. This involves creating a temporary Image object for each URL to read its natural width and height.
Construct the items Array with Dimensions: Populate the gallery's items array with objects that include src, type, width, and height for each image.

Consider the following refined code example, building upon a typical implementation:


$w.onReady(function () {
    getMedia()
        .then(async (mediaUrls) => { // Use async to allow awaiting dimension fetching
            console.log(mediaUrls);
            let baseUrl = "fakewebsite.com"; // Replace with your actual base URL
            let items = [];

            for (const mediaUrl of mediaUrls) {
                const fullUrl = baseUrl + "/" + mediaUrl;
                let item = {
                    type: mediaUrl.includes("mp4") || mediaUrl.includes("mov") ? "video" : "image",
                    src: fullUrl
                };

                // Only fetch dimensions for images
                if (item.type === "image") {
                    try {
                        const dimensi getImageDimensions(fullUrl); // Await custom function
                        item.width = dimensions.width;
                        item.height = dimensions.height;
                    } catch (error) {
                        console.error(`Failed to get dimensions for ${fullUrl}:`, error);
                        // Implement fallback logic here, e.g., assign default dimensions or skip item
                    }
                }
                items.push(item);
            }
            $w('#gallery3').items = items; // Assign the fully constructed array
        })
        .catch((err) => {
            console.error(err);
        });
});

// Helper function to get image dimensions asynchronously
function getImageDimensions(url) {
    return new Promise((resolve, reject) => {
        const img = new Image();
        img. => resolve({ width: img.naturalWidth, height: img.naturalHeight });
        img. => reject(err); // Handle errors during image loading
        img.src = url;
    });
}

Important Considerations:

Performance: Fetching dimensions client-side for many images can introduce a slight delay. Optimize by pre-fetching dimensions on your server if possible.
Video Content: For video items, the width and height properties might need to be determined differently, potentially by pre-processing the video files or using a video player's metadata API.
Error Handling: Implement robust error handling for dimension fetching to prevent gallery items from failing to load or display correctly.

Achieving a Truly Dynamic Gallery

By explicitly providing image dimensions, you empower the Wix Pro Gallery's layout engine to perform its intended function. This ensures that your custom-loaded external media integrates seamlessly, adopting the dynamic and visually appealing Masonry layout you've configured. This approach not only resolves the cropping issue but also unlocks the full potential of the Pro Gallery for a more professional and engaging user experience on your e-commerce site.

Mastering Wix Pro Gallery: Dynamic Masonry Layouts with Custom JavaScript