MediaHub 1.15: a unified drawer save model, a dedicated TinyMCE image editor, and Labels

MediaHub 1.15 brings a focused rework across three areas: how the field inputfield drawer commits edits, how MediaHub images interact with TinyMCE's image dialogs, and the separation of two distinct concepts that previously shared the "tags" label. Three follow-up patches refine the crop editor on top of that, and there's a wider visual pass across the inputfield.

This post groups the changes by theme rather than version. The full inventory is in the changelog, including the v1.15.1, v1.15.2 and v1.15.3 entries.

A clearer save model in the inputfield drawer

The biggest change in 1.15 is to the way the field drawer commits edits. The drawer previously exposed its own Save button alongside ProcessWire's page Save, which split the commit model between two separate actions and introduced ambiguity about which one was authoritative. In 1.15 the drawer no longer has its own Save: per-reference Title, Alt/Description and display Tag edits apply as you type, the card updates in real time, and the page's own Save button is the single commit point. A footer hint reads "Changes apply as you type. Save the page to commit them." This brings the drawer in line with how every other ProcessWire field works.

File rename is treated as the separate, immediate operation it is. It has its own "Rename file" button next to the filename input, disabled until the filename stem changes so the affordance only appears when there's something to do. Embedded references in TinyMCE and any field-level crops are kept in sync automatically when the rename runs.

Per-reference overrides are now first-class in the drawer, with a one-click undo to match. When Title or Alt/Description has an override active, a small refresh icon appears next to the label. Clicking it reverts that field to the global library value.

What the new save model also resolves

Splitting the save model from the rename action also closes off four related issues that all shared the same root cause: blurred lines between per-reference overrides, global asset metadata, and the page save itself.

Title and Alt/Description edits in the drawer are now correctly scoped to the page+field they came from, the same way Tags already were. Editing those fields no longer has the side effect of touching the global asset record, so a custom title on one page stays local to that page.

Removing an asset from a field clears the per-reference overrides for that reference, so re-adding the same asset later starts clean instead of re-applying previous overrides.

Thumb cards now render the effective values, so per-reference overrides are visible on the card without having to open the drawer.

The thumb card label for alt text now reads "Alt/Description" to match the drawer field. The same label is used everywhere alt text appears in MediaHub. The slash mirrors ProcessWire's native image field, which uses $image->description as the alt-text accessor; matching the label keeps the mental model consistent. The $assets->description($asset) template helper continues to work as a deprecated alias.

Library Tags are now Labels

1.15 includes one breaking change: the library-wide taxonomy previously called Tags is renamed to Labels.

MediaHub has two distinct concepts that benefit from clearer separation. The first is a library-wide taxonomy used for filtering and search inside the admin: every asset can carry one or more entries, queryable through $pages->find(). The second is a per-reference free-text input on individual field references, used by template code to mark up things like "which gallery item is the hero one?" They've always done different jobs; sharing the "tags" label made them harder to talk about and harder to discover.

1.15 separates the two by name. The library taxonomy is now Labels everywhere it appears: the admin URL, the menu item, the API methods ($asset->tags() becomes $asset->labels(), $asset->hasTag(...) becomes $asset->hasLabel(...)), the selector field name (pkd_mediahub_tags becomes pkd_mediahub_labels), and the documentation. Per-reference display tags keep the "tags" label, because they really are tags in the everyday sense.

The migration is automatic and idempotent. Templates, fields, the admin nav child page, and the container page are all renamed in place when the module upgrades, with existing assignments preserved. Template code is the one thing the migration can't touch: any ->tags() or ->hasTag( call against a MediaHub asset, and any selector referencing pkd_mediahub_tags, needs a search-and-replace. The search-and-replace guide is in the changelog.

A dedicated image editor for TinyMCE

When MediaHub first integrated with TinyMCE in v1.2, inserted images relied on ProcessWire's native image dialog for any post-insert editing. That dialog is built around uploaded-from-filesystem images, so the controls a writer reaches for most often (alignment, dimensions, alt text) are spread across separate parts of the editor.

1.15 ships a dedicated MediaHub image editor that opens whenever you double-click a MediaHub image in TinyMCE, or whenever you insert a new one from the picker. It puts the four controls you actually use side by side: three alignment buttons (left, centre, right, with centre as the default for new inserts), a width input, a matching height input with the aspect ratio always locked so changing one updates the other, a size slider for quick scaling between thumbnail and full size, and an Alt/Description field. A small checkerboard toggle previews transparent PNGs against the chequered background you need to actually see them.

Non-MediaHub images in the same editor continue to use ProcessWire's native dialog. The intent isn't to replace that workflow, it's to give MediaHub images the dimensions, alignment and alt-text trio that ProcessWire developers already expect, with the controls all in one place.

Round-trip safety in TinyMCE

Two MediaHub features depend on the module being able to recognise its own assets after they've been inserted into a TinyMCE field: double-clicking an inserted image should open the MediaHub image editor (rather than ProcessWire's native one), and renaming a file later should update the embed automatically so links don't break.

On certain configurations the marker that links an embed back to its library asset wasn't surviving the page save round trip. The image continued to render correctly, so the issue only showed up when you tried to use a feature that depended on the link, such as double-click-to-edit or rename propagation. 1.15 hardens the round trip so the marker survives saves on every supported asset element type, with double-click on a MediaHub image now reliably opening the MediaHub editor.

The same release tightens the rename request from the inputfield drawer, which had been silently dropping requests on a format mismatch, and adds live propagation so renames from the drawer update any open TinyMCE editor on the page without a refresh.

Crop editor refinements

Three follow-up patches refine the crop editor, both the standalone library crop editor and the inline one that opens from a crop badge on the inputfield.

1.15.1 sets a sensible default crop boundary. For freeform crops it fills the entire image; for preset crops it picks the largest area matching the chosen aspect ratio, centred on the image. Switching presets while the editor is open resizes the boundary to fit the new ratio.

1.15.2 treats the freeform editor as a one-shot action: it always opens fitted to the entire image, regardless of any previously saved freeform selection. Named preset crops (Square, 16:9 and the rest) still restore their saved positions when re-edited from the inline crop badges, because each preset has one canonical position you're refining. The same release corrects a 20px alignment offset in the inline crop editor caused by an outer canvas wrapper's padding being included in the boundary calculation.

1.15.3 turns up the visibility on Cropper.js v2's rule-of-thirds composition grid, so the dashed lines inside the crop boundary are bright enough to use for composition. The eight resize markers on the corners and edges go from Cropper.js v2's default 5×5 px to a 12×12 white square with a thin dark outline, so they're easier to spot and drag, particularly on dense images and high-DPI displays.

Visual polish across the inputfield

A focused pass across the inputfield drawer and the way non-image assets are rendered.

The drawer header now shows a file-type icon next to the title and filename. Images get an image icon, PDFs a document icon, video / audio / spreadsheet / presentation files each get their own. The four field labels in the drawer (Title, Filename, Alt/Description, Tags) share a single CSS rule so the spacing is identical between them. The image preview area has a thin 1px frame consistent with other framed elements in the admin. The "Screen readers and SEO" hint under Alt/Description is gone (the field label is self-explanatory) and so is the Actions section (Download, Copy URL), which duplicated controls already on the asset detail page.

Non-image assets get their own treatment. Inline crop badges no longer appear on PDFs and other non-image files. The checkerboard transparency background is suppressed on non-image cards, replaced with a plain subtle background and a centred type icon. The drawer's image preview area shows the file icon instead of attempting to render an image element. The Alt/Description field is hidden for non-image assets, because alt text is an HTML <img> attribute and isn't part of the standard for any other file type.

In grid and proportional view modes, non-image cards now match the Library tile design: type-specific Lucide icon, bold title, monospace filename, badge row with breathing room, single remove button. The icon column has a white background; the title and filename column has a subtle muted background. File type and size badges are dropped from the compact views to keep the cards tight, and remain in detail view where there's room.

Two toolbar changes round it out. The active view-mode button (Grid / Proportional / Detail) uses the brand pink instead of the dark blue admin-theme colour, so the current view is unambiguous. The size slider has been redesigned: 100px wide, 7px high, no border, with a solid pink fill to the left of the dragged circle.

Documentation

Every MediaHub doc page on this site has been updated for the Labels rename, with API examples, selectors, nav references, and the Tags page rewritten as Labels. Two other doc updates are worth calling out.

The Crops API page now explains the difference between library crops (visible in the Crops table on an asset, reusable from any field, created in the Library) and field-level crops (scoped to a specific page+field combination, hidden from the Library, created by the inline crop badges on the inputfield). The two are stored differently and retrieved through different methods. The lookup chain resolvedCropImage() is documented alongside ensureCropImage().

The TinyMCE integration page has a new note covering how MediaHub embeds keep their link to the library asset across page saves, and what to do if an older or customised TinyMCE config has dropped that link on existing content (re-inserting the image from the picker is the quickest path).

Upgrading

If you're upgrading from a 1.11.x or earlier install, the migration runs automatically when you refresh modules: the Tags-to-Labels rename, the admin nav child page, and any earlier outstanding migrations all run on the same upgrade pass. The one manual step is updating any template code that calls ->tags() or ->hasTag( against a MediaHub asset, or any selector that references the old pkd_mediahub_tags field. The changelog has the search-and-replace guide.

MediaHub 1.15.3 is available now from the downloads page.