Per-Reference Metadata

The concept

MediaHub's centralised model means an asset's alt text, title, and tags are set once and used everywhere. That's usually what you want: consistency without repetition.

But sometimes the same image needs different context on different pages. A photo of your office might appear on the About page with the caption "Our London headquarters" and on a blog post with "Where the magic happens." The image is the same; the description is page-specific.

Per-reference metadata solves this. Each time an asset is selected into a MediaHub field, it can carry its own description override and display tags, stored separately from the global asset record and scoped to that specific page and field.

Setting up

Metadata is stored automatically in a dedicated database table. No companion ProcessWire fields are required; the module handles everything.

To enable display tags on a field:

1. Open the page reference field in Setup → Fields
2. Go to the Input tab → File Tags section
3. Choose a tag mode:
   • Tags disabled: description overrides are still available to editors; tags are not shown
   • User enters tags by text input: free-form tag entry
   • User selects from list of predefined tags: editors pick from a fixed list
   • User selects from predefined tags + can input their own: combined mode
4. If using predefined tags (modes 2 or 3), enter a space-separated list in the Predefined tags field (e.g. hero xray diagram)
5. Save the field

No other configuration is needed.

What editors see

When an asset is selected into a field with metadata enabled, the editor can click on the asset card to expand a metadata panel. This shows:

• Description: a text field for the page-specific caption or description
• Tags: depending on the field's tag mode, a text input, dropdown/checkboxes, or both

If the editor leaves the description blank, template code falls back to the asset's global alt text. If they enter a description, it overrides the global value for this specific usage.

Template API

Any multi-value field using the Media Hub Picker inputfield always returns a MediaHubPageArray, regardless of whether the File Tags option is enabled. The extra methods are always available; they just return empty values when no overrides have been saved.

Getting the description

// Per-page description: returns the page-level override,
// or falls back to the asset's alt text if no override exists
$caption = $page->gallery->description($asset);
// Use it in output
foreach ($page->gallery as $asset) {
$desc = $page->gallery->description($asset);
echo "<img src='{$asset->image()->url}' alt='{$desc}'>";
}

Working with display tags

// Get the first asset with a specific tag on this page
$hero = $page->gallery->getTag('hero');
// Get all assets with a specific tag (returns PageArray)
$diagrams = $page->gallery->findTag('diagram');
// Get all tags for a specific asset as an array of strings
$tags = $page->gallery->getDisplayTags($asset);
// e.g. ['hero', 'featured']
// Check if an asset has a specific tag
if ($page->gallery->hasDisplayTag($asset, 'hero')) {
// ...
}

Direct asset API

You can also look up the per-reference description directly from an asset page, without going through the field:

// Auto-detects the first MediaHub field on the page
$caption = $asset->descriptionFor($page);
// Explicit field name
$caption = $asset->descriptionFor($page, 'gallery');

Display tags vs library tags

These are two completely separate systems:

A common pattern is to use library tags for admin organisation (e.g. "Needs review", "Stock photo") and display tags for front-end logic (e.g. "hero", "thumbnail", "print-only").