Step 1: Installation

The fastest way to get started is by uploading the cloudfold.zip file to your WordPress dashboard. For detailed instructions on other methods like FTP or WP-CLI, see the full Installation guide.

Step 2: Rendering Your First Gallery

CloudFold provides a seamless native integration with the Gutenberg block editor. Alternatively, render a gallery anywhere with a shortcode:

<!-- Drop this into any shortcode block -->
[cloudfold_gallery id="12" layout="justified" gap="10px" lazyload="true"]

Canonical Shortcodes

Via WordPress Dashboard

The most common method to install CloudFold.

1. Download cloudfold.zip from your customer portal or email receipt.
2. Go to Plugins > Add New > Upload Plugin and select your zip file.
3. Click Install Now followed by Activate Plugin to initialize the React backend.

Developer: WP-CLI

Automate your deployment and database migrations with the native CLI commands.

# 1. Install the plugin from a path or URL
wp plugin install /path/to/cloudfold.zip --activate

# 2. Prime the Virtual Folder relationship engine
wp cloudfold migrate:init --force

License State Matrix

The Concept

Standard WordPress media management is linear. To categorize an image, you usually rely on tags or move files into physical directories on the server. Moving files breaks SEO indexing and leads to 404 errors on existing posts.

Key Benefits

• SEO Integrity: since the attachment ID and URL never change, search rankings stay undisturbed regardless of how often you re-organize your library.
• Multi-Assignment: assign a single image to multiple virtual folders (e.g. "Architecture" and "Client Review") without creating duplicate files on the server.
• Lightning Fast: optimized custom SQL indexes mean querying a virtual folder with 50,000 assets takes less than 12ms.

The Media Organizer Interface

The React-powered Media Organizer provides a desktop-class drag-and-drop experience. You can create nested folders, bulk-move items, and manage asset metadata through a centralized "Gallery Drawer".

AI Providers

CloudFold supports the following AI providers in current runtime settings:

Modern Web APIs Utilized

• Intersection Observer: native lazy-loading for images, using the browser's hardware-accelerated intersection API to load assets precisely when they enter the viewport.
• CSS Grid & Flexbox: 90% of the Masonry and Metro layout logic is offloaded to native CSS, triggering JavaScript recalculation only on window resize.
• requestAnimationFrame: visual transitions and layout work are batched alongside the browser's native paint cycle, eliminating jank and dropped frames.
• Event Delegation: a single listener sits at the gallery root instead of hundreds of per-item click listeners, saving memory and processing overhead.

Modular Asset Loading

CloudFold strictly adheres to WordPress best practices for asset enqueuing. If a page does not contain a CloudFold gallery, zero plugin scripts or styles are loaded. Assets are also loaded per layout: a Justified Grid page only loads the Justified module, ignoring Carousel and Masonry dependencies entirely.

When to Use Masonry

Use the Masonry layout when your gallery consists of images with highly variable heights (a mix of portrait and landscape orientations) and you want to prevent white space gaps without cropping the original images.

Implementation

To render a masonry grid, set the layout parameter to masonry. You can define the number of columns to generate.

<!-- Basic Masonry Shortcode -->
[cloudfold_gallery id="12" layout="masonry" columns="3" gap="15px"]

Responsive Columns

CloudFold automatically handles responsiveness. By default, a 3-column layout drops to 2 columns on tablets and 1 column on mobile. You can explicitly override these breakpoints:

<!-- Advanced Responsive Masonry -->
[cloudfold_gallery 
    id="12" 
    layout="masonry" 
    columns_desktop="4" 
    columns_tablet="3" 
    columns_mobile="2"
]

Technical Details

The Masonry engine uses native CSS column-count combined with a lightweight JavaScript fallback for older browsers. This ensures the layout renders immediately on initial DOM load, preventing the "FOUC" (Flash of Unstyled Content) commonly seen in jQuery-based masonry libraries.

The Algorithm

The Justified engine mathematically calculates the aspect ratio of every image in a given query. It then groups them into rows and dynamically adjusts the row height to perfectly fit the container's width — all on the client side, in milliseconds.

Implementation

Enforce a Justified grid via Gutenberg block properties, or by passing layout parameters to the shortcode:

<!-- Basic Justified Shortcode -->
[cloudfold_gallery id="12" layout="justified" row_height="250" gap="10px"]

Configuration Parameters

Last Row Behavior

One common issue with Justified layouts is the final row. If there aren't enough images to complete the row, stretching them to fit the container creates massive, blurry images. By default, CloudFold sets last_row="nojustify", aligning remaining images to the left using their natural calculated size.

Mixed Media Support

The Carousel layout natively supports mixed media. You can combine static images, self-hosted MP4 files, and external embeds (YouTube, Vimeo) in the same slider. When a user clicks a video slide, the carousel pauses automatically and opens the video in the hardware-accelerated lightbox.

Implementation

Render a fully functional carousel with touch-swipe capabilities by changing the layout parameter.

<!-- Basic Carousel Shortcode -->
[cloudfold_gallery id="12" layout="carousel" autoplay="true" interval="3000"]

Configuration Parameters

When to Use

Use Grid for product galleries, team portfolios, and consistent card-based visual systems.

Implementation

[cloudfold_gallery id="12" layout="grid" columns="4" gap="12px"]

When to Use

Use Metro when hero images need more visual weight than secondary images.

Implementation

[cloudfold_gallery id="12" layout="metro" columns="4" gap="10px"]

When to Use

Use Mosaic for storytelling pages where uniform symmetry is not the design goal.

Implementation

[cloudfold_gallery id="12" layout="mosaic" columns="4" gap="10px"]

When to Use

Use Slider for one-at-a-time focus, where each image needs maximum viewport attention.

Implementation

[cloudfold_gallery id="12" layout="slider" slider_height="560"]

When to Use

Use Story for bite-sized visual sequences and mobile-first audience engagement.

Implementation

[cloudfold_gallery id="12" layout="story" lightbox="true"]

The Cropping Problem

When displaying a portrait image in a square grid, standard CSS behavior (object-fit: cover) crops equally from all sides, anchoring to the center. If your subject's face is near the top of the image, it will inevitably be cut off.

How It Works

When you click on the image preview within the CloudFold Media Organizer, CloudFold captures the X and Y coordinate percentages. These coordinates are saved directly to the attachment's metadata.

On the frontend, the layout engine dynamically applies these coordinates as an inline CSS object-position property to the image. Because this relies on native CSS, the feature has zero impact on load times or JavaScript execution.

<!-- Generated DOM Output -->
<img 
    src="portrait-shot.jpg" 
    style="object-fit: cover; object-position: 50% 25%;"
/>

Automated WebP Conversion

When an image is uploaded to WordPress, CloudFold's background queue hooks into the native attachment generation process and silently generates modern WebP versions of your JPEGs and PNGs.

Smart Srcset Engine

Instead of relying purely on WordPress default sizes (thumbnail, medium, large), CloudFold calculates the exact mathematical dimensions required by your specific layout and outputs an optimized picture and srcset element.

<!-- Example of generated DOM -->
<picture>
    <source type="image/webp" srcset="image-400.webp 400w, image-800.webp 800w" sizes="(max-width: 768px) 100vw, 33vw">
    <img src="image-800.jpg" alt="Optimized SEO description" loading="lazy" />
</picture>

Intersection Observer Lazy Loading

While browsers now support native loading="lazy", it can sometimes be too aggressive or inconsistent across browser engines. CloudFold employs a highly tuned IntersectionObserver in vanilla JavaScript — images swap into the DOM only when they come within a configurable threshold (e.g. 200px) of the viewport, so off-screen assets consume zero bandwidth during initial page load.

Adding Hotspots

Hotspots can be added via the Media Organizer drawer. When editing an image, switch to the Hotspots tab, click anywhere on the image preview to drop a pin, then fill out the resulting form to add text, a URL, or link it to a product.

WooCommerce Integration

CloudFold includes native WooCommerce integration via class-cloudfold-woocommerce.php. When adding a hotspot, select "WooCommerce Product" as the type and search your store catalog. The tooltip automatically pulls the product's title, price, featured image, and an "Add to Cart" button.

Woo Feature Matrix

Setup Flow (Recommended)

1. Enable WooCommerce and confirm products have media assets assigned.
2. Configure CloudFold gallery settings (layout, lightbox, interaction style).
3. Add Woo-linked hotspots from the image drawer where product tagging is needed.
4. Test variable product pages and quick interactions (zoom/lightbox/cart CTA).
5. Clear cache/CDN and verify final frontend behavior on desktop and mobile.

Compatibility Notes

• Theme overrides: some Woo themes replace default gallery hooks; validate render priority after activation.
• Performance plugins: aggressive JS deferral/minification may delay hotspot/lightbox bindings.
• Caching: product pages with dynamic variation states should bypass stale fragment caches where needed.

Woo Troubleshooting

Key Features

• Approval Workflow: clients click intuitive checkmark or cross buttons on images to mark them as approved or rejected.
• Client Comments: an integrated commenting system within the Lightbox lets clients request specific edits.
• Admin Dashboard: photographers view a summarized breakdown of all client selections directly in the WordPress backend, with easy bulk downloading of approved files.

Setting Up a Proofing Gallery

To enable proofing, toggle the proofing attribute on your gallery block or shortcode. It is highly recommended to combine this with WordPress core password protection.

<!-- Enabling Proofing Mode -->
[cloudfold_gallery id="12" layout="masonry" proofing="true"]

Proofing Policy Controls

Supported Providers

CloudFold currently supports these storage/offload providers:

How It Works

Once credentials and rules are configured, the runtime flow is:

Offload Decision Path

If offload output does not match expectations, follow this deterministic path before retrying bulk operations:

1. Confirm provider credentials and bucket/container access in Integrations.
2. Verify the target rule is enabled and priority order is correct.
3. Validate include-size and ACL/signed URL settings for the failing file type.
4. Run a single-file test upload and inspect the resulting URL rewrite behavior.
5. If still failing, review Insights telemetry and server logs before mass retries.

Endpoint Contracts

All CloudFold endpoints are prefixed with /wp-json/cloudfold/v1/. Route surfaces are split by capability domain rather than one generic endpoint.

Authentication

Public read routes can be open or tokenized depending on route policy. Admin operations must send a valid WordPress REST nonce from an active admin session.

Example Request

Admin-request example (nonce-based):

const response = await fetch('/wp-json/cloudfold/v1/library/media?page=1&per_page=20', {
  headers: {
    'X-WP-Nonce': window.cloudfoldAdmin?.restNonce || '',
    'Content-Type': 'application/json'
  }
});
if (!response.ok) {
  throw new Error(`CloudFold REST error ${response.status}`);
}
const payload = await response.json();

Error Handling Matrix

Integration Primitives

• Shortcodes: cloudfold_gallery, cloudfold_album, cloudfold_smart, cloudfold_before_after, cloudfold_video_gallery.
• REST Base: /wp-json/cloudfold/v1/ for admin/public route families.
• Admin SPA routes: hash routes such as #/library, #/galleries, #/gallery-edit/{id}, #/integrations, #/offload-rules, #/job-queue, #/insights, #/license.

<?php
// Source-backed render pattern: shortcode in template context
echo do_shortcode(
    '[cloudfold_gallery id="42" layout="masonry" columns="4"]'
);

Safe Contract Notes

Prefer documented routes and shortcodes over direct plugin internals. Internal service classes may change without public API guarantees.

GET /wp-json/cloudfold/v1/library/media?page=1&per_page=20
X-WP-Nonce: {wp_rest_nonce}

Registered Blocks

The plugin registers several blocks via block.json. You can target these blocks in your own custom patterns or block templates.

• cloudfold/gallery — the core dynamic block; a wrapper that reads the layout attribute to render the correct UI.
• cloudfold/masonry — a dedicated block that forces the Masonry layout interface in the editor sidebar.
• cloudfold/carousel — a block exposing interval and autoplay attributes directly to the editor UI.

Block Attributes

When declaring a CloudFold block programmatically, pass attributes as a JSON object inside the block comment:

<!-- wp:cloudfold/gallery {"id":42,"layout":"justified","rowHeight":300} /-->

Layout Breaking or Overlapping

If your Masonry or Justified grid looks broken or images overlap, it's typically related to caching or theme conflicts.

• Lazy Load Conflicts: disable third-party lazy-loading plugins (like Smush or Autoptimize) for the page containing the gallery. CloudFold uses its own optimized IntersectionObserver.
• Empty Image Dimensions: the Layout Engine relies on the width and height attributes of the <img> tag to calculate the grid before images load. Ensure your theme isn't stripping these attributes.

Folders Missing After Update

If you've recently updated the plugin and your Virtual Folders appear empty, you likely need to run the database migration script. Trigger this manually via WP-CLI:

# Force the database schema sync
wp cloudfold migrate:init --force