Uplink Media Bridge for Etch

Uplink Media Bridge for Etch adds a native Media > Etch Collections workspace for organizing the WordPress media library with Etch itself. Create and edit two-level collections, upload or select media, assign items to multiple collections, drag selected items into a collection, and use bulk assignment tools without installing another folder plugin.

Read the Uplink Media Bridge for Etch 2.0 overview.

Wicked Folders and HappyFiles remain supported as optional bridge providers. Choose one under Media > Uplink Media Bridge when you want bidirectional synchronization instead of the native-only mode.

To update the plugin settings, open Media > Uplink Media Bridge in the WordPress admin. The settings are located under the Media tab, not the Settings menu.

WordPress 7.0 and newer also exposes the manager and Media Bridge settings through the Command Palette. The manager entry uses the administrator-defined label and is available only in native Etch Collections mode; it is hidden from both the Media menu and Command Palette while Wicked Folders or HappyFiles is selected. WordPress capability checks determine which entries each user can see.

Administrators can white-label the native manager under Media > Media Bridge by changing the Media manager label. The default remains Etch Collections for existing sites. The custom name is used in the Media menu, manager title, information popup, WordPress media-selection tab, and Command Palette. Searching the Command Palette for Etch continues to find both the manager and Media Bridge settings, even when the manager uses a custom name.

An additional option can make the native manager the default Media screen. It is disabled by default and applies only in Etch-only mode. When enabled, the Media menu opens the custom-labeled manager and the legacy Library submenu link is hidden. WordPress’s legacy media library is not disabled: direct links from WordPress, plugins, bookmarks, and attachment workflows continue to work normally.

Optional providers:

• Wicked Folders
• HappyFiles

Native features include collection creation, rename, movement and deletion; Etch drag-and-drop collection ordering; media uploads and permanent deletion; a full-screen attachment editor and compact icon toolbar; title, alt text, decorative state, caption, and description editing; adjustable grid and masonry layouts plus a compact list view; detailed filtering by media and MIME type, uploader, attachment status, date, dimensions, file size, and missing alt text; Media Health scanning; optional EXIF display; Auto, Light, and Dark appearance modes; search; automatic scroll loading; optional numbered pagination; multi-collection assignments; Ctrl/Command-click and Shift-click range selection; drag-and-drop assignment; and bulk add, remove, uncategorize, or delete actions.

Media Health and EXIF

The Health workspace scans attachments for broken or empty files, missing image alt text, missing generated image sizes, oversized files, and obsolete BMP or TIFF formats. It also provides dedicated Decorative and Healthy views. Rescan after changing files outside WordPress; normal Media Bridge edits and attachment changes invalidate the cached scan automatically.

The display popover can reveal camera, lens, aperture, focal length, ISO, exposure, capture date, credit, and copyright metadata in the attachment editor when WordPress extracted those values from the file.

The Image metadata for Etch setting exposes normalized EXIF under each current Etch image object. Use the active object prefix followed by fields such as image.exif.camera_model, image.exif.aperture_display, image.exif.focal_display, image.exif.exposure_display, or image.exif.date_taken. In a repeated item context, for example, this can be item.image.exif.camera_model. When WordPress creates a -scaled image without EXIF, the bridge reads metadata from WordPress’s retained original image. The provider does not register the old featured_image_exif alias.

Embedded GPS coordinates are a separate setting and are disabled by default. When enabled, latitude, longitude, and altitude appear in the attachment editor and are available below image.exif.gps.

Ops Center integration

Uplink Ops Center and other trusted server-side plugins can send commands through the uplink_mbe_execute_media_command filter. Pass null as the first value and a command array as the second value. The filter returns a result array or WP_Error.

Update attachment fields:

$result = apply_filters( 'uplink_mbe_execute_media_command', null, array( 'operation' => 'update', 'attachment_id' => 123, 'fields' => array( 'title' => 'Team photo', 'alt' => 'The support team outside the office', 'decorative' => false, 'caption' => '', 'description' => '' ) ) );

Add attachments to a collection:

$result = apply_filters( 'uplink_mbe_execute_media_command', null, array( 'operation' => 'add', 'attachment_ids' => array( 123, 124 ), 'collection_id' => 45 ) );

The remove operation uses the same IDs. The clear operation removes all Media Bridge collection assignments and does not need collection_id. Commands honor the current user’s WordPress media permissions. A trusted non-interactive integration can opt in with uplink_mbe_media_command_allowed. Media Bridge fires uplink_mbe_attachment_updated after metadata edits and uplink_mbe_media_collections_changed after assignment changes.

Open the native Media Bridge library from an integration with uplink_mbe_get_library_url(). Pass an attachment ID to open that attachment in the details inspector, or pass upload as the second argument to open the uploader:

$attachment_url = uplink_mbe_get_library_url( 123 );

$upload_url = uplink_mbe_get_library_url( 0, 'upload' );

The uplink_mbe_media_library_url filter can change generated URLs. The browser dispatches uplink-mbe:library-ready on document after the library and any requested interface action have initialized. Navigation stays separate from the uplink_mbe_execute_media_command mutation filter.

Etch Collections loads additional media automatically as you scroll. Administrators who prefer page controls can enable numbered pagination under Media > Media Bridge.

Bridge features include folder creation, rename and movement synchronization; attachment assignment synchronization; provider-specific ordering; optional deletion synchronization; fixed or most-recent conflict authority; reconciliation; and a 200-entry sync history.

Etch supports two folder levels. Deeper folders in the selected client-side provider remain untouched. Media assigned below level two is represented in Etch by its nearest supported ancestor.

Migrating from Wicked Folders or HappyFiles

Media Bridge stores synchronized copies as Etch Collections. After those collections and attachment assignments have been reconciled, they remain available in native mode even if Wicked Folders or HappyFiles is deactivated or removed.

Before migrating, make a current site backup. Do not deactivate or remove the folder plugin until the Etch copy has been verified.

Recommended migration procedure:

1. Keep Wicked Folders or HappyFiles active.
2. Open Media > Media Bridge and select the installed folder provider.
3. Disable Synchronize folder deletions during the migration unless copied deletions are specifically required.
4. Save the settings, then run reconciliation.
5. Open Media > Etch Collections and verify the collection names, hierarchy, item counts, and several individual media assignments.
6. Return to Media > Media Bridge, select Etch Collections — no third-party plugin, and save.
7. Deactivate the folder plugin, then verify Media > Etch Collections again.
8. Remove the folder plugin only after verification is complete.

Switching to native mode stops the bridge hooks. It does not delete Etch Collections, attachment assignments, or media files. The original provider data is separate and may remain in the database after deactivation; uninstall behavior depends on that provider.

Etch supports two collection levels. Top-level folders, second-level folders, and their media assignments are preserved. For folders deeper than two levels, the deeper provider folders remain untouched while the bridge is active, but Etch represents their media using the nearest supported two-level ancestor. The exact third-level-or-deeper hierarchy cannot be preserved in native Etch Collections.

For rollback, restore the site backup for a complete restoration of provider-specific data. Alternatively, reinstall or reactivate the provider, select it under Media > Media Bridge, and reconcile from Etch; this can rebuild the supported two-level folder structure and assignments, but it cannot reconstruct provider-only deeper hierarchy or settings that the provider removed during uninstall.

Collection galleries

Collection Gallery is enabled by default. Administrators can turn it off under Media > Media Bridge; doing so unregisters the block and shortcode and hides the gallery generator and documentation.

The Collection Gallery block displays a live gallery fed by an Etch collection. Adding or removing an image from the selected collection updates the rendered gallery without editing the page. Block controls include standard grid, tiled mosaic, circular grid, square tiles, and tiled columns; one to eight columns; image resolution; cropping and aspect ratio; spacing; random order; child collections; and an image limit.

Image behavior can use the custom gallery lightbox, the native WordPress lightbox, or no interaction. The custom lightbox includes optional titles and captions, a horizontal or vertical thumbnail strip, separate lightbox image resolution, fullscreen and zoom controls, customizable colors and font sizes, and information above or below the image. It supports Escape, arrow, Home, End, Tab, Shift+Tab, plus/minus, and zero keyboard controls, traps focus while open, announces slide changes, and restores focus to the originating thumbnail when closed. Images are never linked directly to a media file or attachment page.

Image optimizer compatibility

Media Bridge organizes standard WordPress attachments, so image optimizers that create separate WebP or AVIF files do not interfere with collections or folder synchronization. Front-end delivery needs more care when an optimizer wraps the same gallery image through both wp_get_attachment_image and wp_content_img_tag, because that can create nested <picture> elements.

For WebberZone Image Optimizer 1.0.2, open Media > Image Optimizer > Delivery. Keep Post content images enabled and disable Theme and block images when using the Collection Gallery block or shortcode. This leaves one delivery pass over the finished gallery markup. On WordPress 6.9 or newer, Whole page (buffered) can cover images outside post content if needed. Clear page and CDN caches after changing these settings, then check every gallery layout and lightbox mode used by the site. If a later optimizer release changes its delivery hooks, test the combination again before using it in production.

Thumbnail titles and captions are separate options and are disabled by default. When enabled, their colors, background color and opacity, font sizes, alignment, and top, center, or bottom position are customizable.

The same gallery renderer is available through the [etch_collection_gallery] shortcode. The collection value can be a collection ID or slug:

[etch_collection_gallery collection="airplanes" layout="tiled" columns="4" size="large" lightbox="custom" lightbox_thumbnails="true" lightbox_thumbnail_position="horizontal" limit="24"]

The lightbox value accepts custom, native, or none. Custom-lightbox options include lightbox_title, lightbox_caption, lightbox_thumbnails, lightbox_fullscreen, lightbox_zoom, lightbox_size, lightbox_thumbnail_position, lightbox_info_position, lightbox_background, lightbox_panel, lightbox_title_color, lightbox_caption_color, lightbox_font, lightbox_title_size, lightbox_caption_size, lightbox_title_weight, and lightbox_caption_weight. Font values are inherit, system, serif, or mono. Thumbnail text uses show_title, captions, title_color, caption_color, text_background, background_opacity, title_size, caption_size, text_align, and text_position.

Available shortcode attributes are collection, include_children, layout, columns, size, crop, aspect_ratio, random, show_title, captions, lightbox, title_color, caption_color, title_size, caption_size, text_align, limit, and gap. Layout values are grid, tiled, circles, square, or columns. Images can use the native WordPress lightbox or remain non-clickable; direct image and attachment links are not supported.

Access and permissions

Media Bridge uses WordPress capabilities rather than maintaining a separate role system. Access to Media > Etch Collections and its media-selection tab requires the upload_files capability. Creating, renaming, moving, or deleting collections requires the Etch taxonomy’s manage_terms capability, while assigning media requires its assign_terms capability. Editing attachment details requires edit access to that attachment, and permanent deletion requires delete access to that attachment. WordPress administrators and editors normally have all required capabilities; authors retain the limits configured by WordPress and any role-management plugin.

The WordPress Command Palette follows the same rules. Users with upload_files can open the manager command while native mode is active. Only users with manage_options can see and open the Media Bridge settings command.

Data retention and removal

Deactivating or deleting Media Bridge preserves its settings and bridge metadata by default. Administrators can independently opt into cleanup on deactivation or deletion under Media > Media Bridge. Cleanup removes Media Bridge settings, synchronization history, legacy options, and bridge-specific mapping metadata. Etch Collections, third-party folders, attachment assignments, media records, and files are always preserved.

The deactivation option supports managed environments where plugins are removed through a deployment workflow rather than the WordPress Plugins screen. The deployment must run WordPress’s deactivation hook before removing the plugin files; once those files are gone, Media Bridge cannot execute cleanup code.

On multisite, network administrators can configure off-by-default network-wide cleanup overrides under Network Admin > Settings > Media Bridge. A network override can clean Media Bridge-owned records across every site during network deactivation or plugin deletion, regardless of individual site choices. Site-level deactivation continues to follow that site’s local setting.

Deactivating or deleting Media Bridge stops Collection Gallery blocks, gallery shortcodes, and their Etch builder passthrough from rendering. Saved block and shortcode content remains in WordPress and renders again after the plugin is reactivated or reinstalled.