Quickstart

This page walks you through the essential steps to get MediaHub running on your site. Each section is kept deliberately brief; links point to the full documentation if you want the detail.

1. Install the module

1. Copy the MediaHub folder into site/modules/MediaHub/. The folder name must be exactly MediaHub.
2. In the ProcessWire admin, go to Modules → Refresh.
3. Find Media Hub in the module list and click Install. ProcessWire installs all three modules (MediaHub, ProcessMediaHub, InputfieldMediaHub) automatically.
4. Click Submit on the configuration screen to accept the defaults.

You should now see Media Hub in the Setup menu. Full details: Installation.

2. Upload your first assets

1. Go to Setup → Media Hub → Upload.
2. Drag and drop images (or click to browse). Multiple files can be dropped at once.
3. Review the upload preview, then confirm.

Each uploaded file becomes its own page in the MediaHub library. You can browse everything you've uploaded from the Library tab.

3. Create a MediaHub field

1. Go to Setup → Fields → Add New Field.
2. Set a Label (e.g. Hero Image) and Name (e.g. hero_image).
3. Under Type, find the Page Reference group and choose Single page: Media Hub Picker.
4. Click Save.
5. On the Details tab, set Page field value type to Multiple pages (PageArray) if you need a gallery, or leave it as Single page for a single image.
6. On the Input tab, expand Selectable pages. Set Parent to the hidden MediaHub → Assets page. (On installs that have not yet upgraded to v1.11.0, this page is still named "Images".) The Template field defaults to pkd-mediahub-asset on a fresh install — confirm it is set to that value, and update it if it is not.
7. Click Save, then add the field to your template's fieldgroup.

Full details and field settings: Adding to Templates.

4. Display assets in your templates

A MediaHub field returns a page reference, not a file. For images, call ->image() to get a standard ProcessWire Pageimage. For other file types, use ->file() or ->fileUrl().

Single image field

$asset = $page->hero_image;
if ($asset && $asset->id) {
$img = $asset->image();
echo "<img src='{$img->width(1200)->url}' alt='{$asset->altText()}'>";
}

Multi-value field (gallery)

foreach ($page->gallery as $asset) {
$img = $asset->image();
if (!$img) continue;
echo "<img src='{$img->size(400, 300)->url}' alt='{$asset->altText()}'>";
}

Non-image assets

Type-checking helpers let you render the right markup for each asset type:

foreach ($page->media as $asset) {
if ($asset->isImage()) {
    echo $asset->imgTag(800, 600, ['loading' => 'lazy']);
} elseif ($asset->isVideo()) {
    echo "<video src='{$asset->fileUrl()}' controls></video>";
} elseif ($asset->isDocument()) {
    $file = $asset->file();
    echo "<a href='{$file->url}'>{$asset->title} ({$asset->extension()})</a>";
}
}

Full API reference: Template API.

5. Create and use crops

1. Open any image asset in the library (Setup → Media Hub, click a tile).
2. In the sidebar, click Crop image.
3. Choose a preset (e.g. Square, 16:9) or use Freeform, position the crop, and save.

In your template, retrieve a crop by its preset key:

$img = $asset->cropImage('square', 400, 400);
if ($img) {
echo "<img src='{$img->url}' alt='{$asset->altText()}'>";
}

If you want the crop to be auto-generated when it doesn't exist yet, use ensureCropImage() instead. It creates a mathematically centred crop on first call and returns the existing crop on subsequent calls. The generated crop is a real crop page: it shows up in the asset's Crops table in the admin, and an editor can adjust its position at any time. It never overwrites an editor-curated crop.

$img = $asset->ensureCropImage('square', 400, 400);

Full details: Crops API.

6. Show crop badges on a field

Crop badges give editors a visual summary of which crops exist for each image, directly on the card in the page editor.

1. Open your MediaHub field in Setup → Fields.
2. Go to the Input tab → Media Hub Picker Settings.
3. Under Inline crop presets, tick the presets you want to surface on this field (e.g. Square, 16:9).
4. Save the field.

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 above). 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 position if the auto-generated centre crop isn't ideal.

7. Import existing images

If your site already has images in standard ProcessWire image fields, you can bring them into the MediaHub library without re-uploading.

1. Go to Setup → Media Hub → Import → Scan & Import.
2. Click Scan For Existing Images. The scanner crawls every image field on every page.
3. Review the results. Each image gets a status badge: New, Already in Hub, or Potential duplicate.
4. Tick the images you want and click Import Selected.

What happens during import

For each imported image, MediaHub creates a new asset page with its own directory under site/assets/files/. The image file is copied, not moved. Your original images remain exactly where they are on their source pages.

This means after import you will have two copies of each image on disk: the original in its source page's file directory, and the new copy in the MediaHub asset page's directory. This is deliberate. It lets you verify everything works before removing the originals.

Cleaning up legacy images

Once you have confirmed that your MediaHub fields are displaying correctly and you no longer need the original image fields:

1. Remove the old image fields from your templates.
2. Delete the old image field definitions from Setup → Fields (ProcessWire will prompt you if any templates still use them).
3. The original image files remain on disk in site/assets/files/{page_id}/ until the page is saved or the files are manually removed. ProcessWire does not automatically clean up orphaned files.

There is no rush to do this. MediaHub and your legacy image fields can coexist on the same template for as long as you need. The Import Page Images feature is specifically designed for this kind of gradual migration.

Next steps

• Configuration for upload limits, file types, crop presets, and permissions
• The Admin for a full walkthrough of the library, tags, folders, and bulk operations
• Template API for the complete method reference
• Per-Reference Metadata for page-specific alt text overrides and display tags