Image Cropping

Opening the crop editor

From an asset's detail page, click Crop image in the Actions sidebar. The crop editor opens with the image canvas on the left and a preset list on the right.

Select an aspect ratio preset (or use Freeform), drag to position the crop box, then save.

Save options

Two save options are available:

• Save as crop - saves the crop as a child page linked to this asset. The crop appears in the asset's Crops section and is independently selectable in page reference fields via the picker.
• Save as new asset - saves the crop as a completely standalone asset page with no link back to the source. Use this when the cropped version should be treated as its own independent image.

Crops are stored as separate pages with their own image, preset key, coordinates, and metadata. Each crop is a first-class entity with its own page ID, making it independently selectable in page reference fields.

Automatic crop generation

When crop presets are configured, MediaHub automatically generates crops for image assets. Inline crop badges appear next to each image in page reference fields, and the crops are created at badge render time via ensureCropImage().

These auto-generated crops are real crop pages. They appear in the asset's Crops table and can be adjusted by editors at any time. The auto-generation simply saves the step of manually creating each preset; editors can then refine the crop position if the default centre-crop is not ideal.

Developers can also trigger the same lazy creation in template code. See the Crops API for details on ensureCropImage().

Adjusting an existing crop

Saved crops are listed in the Crops section of the asset detail page. Clicking the info icon on any crop opens a detail panel showing its preset, dimensions, file size, filename, creation date, and the raw crop coordinates.

The panel has an Adjust Crop button that re-opens the crop editor with the original selection pre-loaded, so you can reposition or resize without starting from scratch.

Cascade delete

Deleting an asset permanently removes all of its associated crop pages. The delete confirmation on the detail page shows how many crops will be removed.

Custom crop presets

Go to Modules → Configure → MediaHub → Crop Presets to add custom presets. Each preset needs:

• Label - a human-readable name (e.g. "Hero Banner")
• Key - used in code (e.g. hero_banner)
• Ratio - in W:H format (e.g. 16:5). Leave blank for a freeform (unconstrained) crop.

Groups

Custom presets can be assigned to a Group (e.g. "Social", "Editorial", "Front Page"). Presets with the same group name appear together in a collapsible section in the crop editor sidebar, making it easier to find the right preset when you have many.

See the Configuration page for the full list of built-in presets and group configuration.