Rich Text Integration

MediaHub includes a TinyMCE plugin that lets editors insert assets from the library directly into rich text fields — images, videos, audio, and document links. It also integrates with ProcessWire's Insert Link dialog, so editors can link highlighted text to any MediaHub asset without leaving their workflow.

This integration is currently TinyMCE only. CKEditor is not supported.

Setting up the toolbar button

The plugin registers automatically when MediaHub detects that InputfieldTinyMCE is installed. No separate module installation is needed.

To make the button visible in the editor toolbar:

1. Go to Setup → Fields and open your TinyMCE textarea field.
2. On the Input tab, find the TinyMCE toolbar configuration (either the visual toolbar builder or the Custom JSON settings).
3. Add mediahub to the toolbar row where you want the button to appear.
4. Save the field.

The button appears in the toolbar as an image-plus icon. Hovering shows the tooltip "Insert from Media Hub".

A note about the button also appears in the TinyMCE field's configuration under a collapsible Media Hub section, reminding you to add mediahub to the toolbar setting.

Inserting an asset

1. Place your cursor in the TinyMCE editor where you want the asset.
2. Click the Media Hub toolbar button.
3. The picker opens in a fullscreen overlay with the familiar MediaHub library interface: search, type filter, tag filter, collection filter, crop filter, sort, and grid/masonry/list views.
4. Click an asset to select it. The picker is in single-select mode: one click selects the asset.
5. Click the confirm button to embed it into the editor content.

The confirm button label adjusts based on the selected asset type:

Asset type	Button label	Inserted HTML
Image	Insert image	<img> tag with alt text
Video	Insert video	<video controls> tag
Audio	Insert audio	<audio controls> tag
Document (PDF, DOCX, etc.)	Insert link	<a> download link using the filename as link text

All inserted elements include a data-mediahub-id attribute linking them to the asset page ID for rename tracking.

The two-tab picker

When the picker opens from a TinyMCE field on a page that already has MediaHub assets referenced on it, two tabs appear at the top of the picker:

Tab	Shows
On this page	Only assets already referenced on the current page (via any MediaHub page reference field). This is a quick way to re-use an asset that's already assigned to the page without searching the whole library.
Media Hub	The full library. Browse, search, filter, and select from every asset in the system.

If the page has no MediaHub fields or no assets are currently selected, only the Media Hub tab appears.

Selecting crops

If an image asset has crops, clicking its tile opens the crop panel on the right side of the picker (the same panel used in page reference field pickers). You can select the original source image or any specific crop. The selected variant's image URL is what gets inserted into the editor.

Crops apply only to image assets. Non-image assets (PDFs, videos, audio) are inserted directly without a crop panel.

Linking text to a MediaHub asset

When you want to turn highlighted text into a link to a MediaHub asset (e.g. "Download the annual report" → links to a PDF), there are two options in the Insert Link dialog.

Option 1: Select File dropdown

Files from MediaHub fields on the current page automatically appear in the Insert Link dialog's Select File dropdown. They are listed as Media File: filename.ext alongside any files from standard ProcessWire file fields.

1. Highlight text in the TinyMCE editor.
2. Click the Insert Link toolbar button (or press Ctrl/Cmd+K).
3. Expand Select File.
4. Choose the MediaHub file from the dropdown. The Link to URL field is populated automatically.
5. Click Save.

Option 2: Select from Media Hub

If the asset you need isn't on the current page, or you want to browse the full library:

1. Highlight text in the TinyMCE editor.
2. Click the Insert Link toolbar button.
3. Expand the Select from Media Hub section at the bottom of the dialog.
4. Click Browse Media Hub. The MediaHub picker opens as a sub-modal.
5. Find and select the asset you want to link to.
6. Click Confirm. The picker closes and the file's URL and name are populated in the Insert Link dialog.
7. Click Save to create the link.

Both options produce a standard <a> tag pointing to the file URL. The link does not carry a data-mediahub-id attribute — it links to the file path directly.

Rename tracking

Every asset inserted via the MediaHub TinyMCE toolbar button carries a data-mediahub-id attribute with the asset's page ID:

<img src="/site/assets/files/1234/office-photo.jpg"
alt="Our London office"
data-mediahub-id="1234" />

<video src="/site/assets/files/1235/product-demo.mp4"
controls data-mediahub-id="1235"></video>

<a href="/site/assets/files/1236/annual-report.pdf"
data-mediahub-id="1236">annual-report.pdf</a>

When a file is renamed inside MediaHub (via the asset detail page), the module scans all textarea fields across the site for elements with a matching data-mediahub-id and updates their src or href attribute to reflect the new filename. This happens automatically on save; no manual find-and-replace is needed.

This tracking works for all asset types inserted through the MediaHub TinyMCE toolbar button: images, videos, audio, and document links. Assets inserted via the Insert Link dialog do not carry the tracking attribute and will not be updated on rename.

How it differs from page reference fields

MediaHub page reference fields and the TinyMCE plugin serve different purposes:

	Page reference field	TinyMCE plugin
Use case	Structured output: hero images, galleries, download lists. The template controls exactly where and how the asset appears.	Inline content: images, videos, and document links embedded in body text, blog posts, long-form articles. The editor controls placement.
Output	PHP template code renders the asset using the page API (image(), fileUrl(), imgTag()).	HTML is written directly into the rich text: <img>, <video>, <audio>, or <a> tags.
Crops	Inline crop badges auto-generate crops at render time. Template code can call cropImage() or ensureCropImage().	Image crops can be selected in the picker. No auto-generation at render time. Non-image assets have no crop support.
Rename tracking	Automatic: page references point to page IDs, not file paths.	Tracked via data-mediahub-id attribute on assets inserted from the toolbar button. Updated when the file is renamed in MediaHub.
Per-reference metadata	Supported: per-page description overrides and display tags.	Not supported: images use the asset's global alt text; other assets use their filename or title.

Both approaches can be used on the same template. A blog post template might have a structured hero_image MediaHub field for the header image, plus a TinyMCE body field where editors embed additional images, videos, and document links inline.

For setting up page reference fields, see Adding to Templates.