Adding MediaHub Field(s) to Templates

This page covers MediaHub page reference fields: standalone fields you add to a template for structured image or file output (hero images, galleries, downloads). These are the primary way to use MediaHub in your templates.

MediaHub also integrates with TinyMCE for inserting images directly into rich text content. That is a separate workflow covered on the Rich Text Integration page. CKEditor is not currently supported.

Creating a MediaHub field

Because you installed the MediaHub Picker inputfield, it appears directly as a selectable field type when creating a new field; no extra steps are needed to wire it up.

1. Go to Fields → Add New Field.
2. Give the field a Label and Name.
   For example, Label: Hero Image (MediaHub), Name: hero_image. Adding (MediaHub) to the label is a handy convention: it makes the field immediately distinguishable from a native ProcessWire image field at a glance. Adding a _mediahub suffix to the name serves the same purpose when scanning a template's fieldgroup.
3. In the Type dropdown, find the Page Reference group and choose Single page: Media Hub Picker.
   This option appears once InputfieldMediaHub is installed.
4. Click Save.
   The field is created and its configuration tabs appear.
5. Open the Details tab. Under Page field value type, select Multiple pages (PageArray) for a gallery or multi-image field, or leave it as Single page for a single-image field.
6. Open the Input tab and confirm Input field type is set to Media Hub Picker.
   This should be pre-selected based on your choice in step 3.
7. Still on the Input tab, expand the Selectable pages section.
   Under Parent, select the hidden MediaHub → Assets page from the page tree. (On installs that have not yet upgraded to v1.11.0, this page is still named "Images" — the upgrade renames it automatically.)
8. In the Template accordion, choose pkd-mediahub-asset.
9. Click Save, then add the field to your template.

The Settings specific to Media Hub Picker section also appears on the Input tab. This covers asset type filtering, display mode, crop badges, and per-reference tags (all covered in the sections below).

Field settings

Each MediaHub field has its own configuration section under the Input tab, in Media Hub Picker Settings.

Asset type filter

Restrict the picker modal to a specific asset type:

• All types: images, documents, audio, and video (default)
• Images only: hides non-image assets from the picker

Max selectable items

The maximum number of assets an editor can select. Set to 0 for unlimited. Only applies to multi-page (gallery) fields; single-page fields always accept exactly one asset.

Default display mode

How selected assets appear in the field on the page edit screen:

• Grid: square thumbnails with no details, similar to ProcessWire's native Images field
• Proportional: thumbnails at each image's natural aspect ratio. A wide landscape image displays wide; a tall portrait displays narrow. This matches the behaviour of ProcessWire's native Images field in proportional mode.
• Detail: larger cards showing filename, description, and dimensions

Editors can switch between these modes at any time using the view toggle in the field itself. Their preference is saved per field via localStorage and restored on the next page load.

Thumbnail size

A size slider sits to the left of the view toggle buttons in the field. Dragging it resizes image thumbnails smaller for a better overview of a long asset list, or larger if editors need to see the images more clearly. The slider affects images only — non-image assets always render as compact detail cards regardless of the slider position. The setting is saved per field via localStorage.

Non-image asset display

When a MediaHub field contains non-image assets (PDFs, videos, audio files, etc.), those assets automatically render as compact detail-style cards showing a file-type icon, title, filename, and type/size badges. This layout is fixed regardless of the active view mode (grid, proportional, or detail) to ensure non-image assets always have meaningful context rather than just an icon. Edit and remove buttons appear on hover, identical to image cards.

Import from page images

When enabled, an Import page images button appears next to the Choose button in the field. This lets editors import images from other standard image fields on the same page directly into the MediaHub field, which is handy when migrating existing content from legacy image fields.

Selecting crops in the picker

When you click Choose on a MediaHub field, the picker modal opens showing the asset library. Assets that have crops display a ✂ N badge on their tile (where N is the number of crops).

Clicking a tile with a crop badge opens a crop panel on the right side of the picker rather than immediately selecting the source asset. The panel shows:

• The original source asset at the top (always available as an option)
• All crop pages below it, each with a thumbnail, preset label (e.g. "Square", "16:9"), and pixel dimensions
• A grid/list view toggle
• An info button on each card showing dimensions, file size, and creation date

Clicking any item in the panel (original or a specific crop) selects it. In single mode, this immediately confirms the selection and closes the picker. In multi mode, the item is toggled and the picker stays open for further selections.

Back in the page editor, selected crops are displayed with a crop badge (✂ + preset key, e.g. "✂ square") alongside the standard dimension and type badges. This makes it immediately clear whether a field slot holds the source image, a "square" crop, a "16_9" crop, and so on.

Each slot is independent. A multi-value field can hold the source, a 16:9 crop, and a square crop as three separate items, each pointing to a different page ID.

Inline crop badges

Crop badges give editors a visual summary of crop status for each image directly on its card in the page editor.

When the page editor renders, MediaHub automatically generates a centred crop for any configured preset that doesn't already have one (using the same ensureCropImage() logic described in the Crops API). This means that by the time the editor sees the card, every badge is filled. Clicking a badge opens the crop editor so the editor can adjust the auto-generated centre crop if the default position isn't ideal. The editor's adjustment is always preserved: ensureCropImage() never overwrites a manually positioned crop.

If a crop cannot be auto-generated (for example, the file format is not supported by GD), the badge appears hollow. Clicking it opens the crop editor so the crop can be created manually.

To enable crop badges on a field:

1. Open the field's configuration → Input tab → Media Hub Picker Settings
2. Under Inline crop presets, tick the presets you want to surface
3. Save the field

Only ticked presets appear as badges on that field. This means you can scope visible crops to the field's context: staff portrait crops on a team member field, hero banner crops on a hero image field, without either set cluttering the other.

Both built-in and custom presets appear in the list. To create custom presets (e.g. "Hero Banner" at 16:5, or "Instagram Story" at 9:16), see Configuration → Crop Presets. Custom presets can be organised into groups (e.g. "Social Media", "Editorial") so they appear in collapsible sections in the crop editor sidebar.

Freeform presets are excluded from badges because they have no defined ratio for auto-generation.

Per-reference file tags

File tags let editors assign context-specific labels to assets on individual pages, completely separate from the global library tags used for admin organisation.

Configure the tag mode per field under Input tab → File Tags:

Mode	Behaviour
Tags disabled	No tagging in this field (default)
User enters tags by text input	Free-text entry
User selects from predefined tags	Dropdown or checkbox selection only
User selects from predefined tags + can input their own	Combined mode

When tags are enabled, a hidden companion field is automatically created and managed by the module. You don't create or configure this field yourself. Predefined tags are entered as a space-separated list in the field settings (e.g. hero xray diagram).

See Per-Reference Metadata for the full explanation of how description overrides and display tags work, including the template API.