Media Library

The Media Library stores files centrally so a single uploaded file can be used in multiple sections and records. Records reference the library file rather than holding their own copy, so replacing the file in the library updates it everywhere it’s used.

The library isn’t a browser for every uploaded file: files uploaded directly to a record’s upload field belong to that record and don’t appear in the library. It holds only files added to it, which upload fields can then reference.

It’s enabled by default. The Use Media Library checkbox under Admin Menu > General Settings (Upload Settings section) controls it. When unchecked, the Media Library menu and the “Select from media library” links on upload fields are hidden.

Managing library files

When enabled, a Media Library section appears in the CMS menu. The list page shows a thumbnail preview plus File Name, File Type, File Size, and Created columns, and can be searched like any other section list.

1. Open Media Library from the CMS menu.

2. Drag files onto the upload box below the list (or click it to browse). Each file creates its own media record.

3. Optionally open a record to set its Title and Caption info fields.

Each media record holds a single file. The default field settings accept gif, jpg, jpeg, png, svg, and webp files up to 5 MB, resize oversized images down to 600×800, and generate two thumbnails (150×150 and 250×250). The Media Library is a regular section, so these limits can be adjusted by editing the Media field in the Database Editor. See Upload Field for the available options.

Used By

The media record edit page includes a Used By list showing every record that references the file, linked to each record’s edit page. Usage inside WYSIWYG content is flagged separately.

A media record can’t be erased while it’s still in use. The CMS blocks the erase with a warning. Remove the references first, then erase the record.

Using library files in upload fields

Upload fields in other sections show a Select from media library link below the upload button.

1. Edit a record and click Select from media library under an upload field.

2. In the popup, page through the library and click Add Media under a file.

This adds a reference to the library file, not a copy: the upload record stores the media record’s number in its mediaNum attribute and reads the file path, dimensions, and thumbnails from the media record. In the editor the entry is labeled (from media library), linking back to the media record.

A few behaviors follow from the file being shared:

• The Title and Caption values display read-only on the referencing record; edit them on the media record itself.
• Removing the upload from a record only removes the reference. The file stays in the library and in any other records using it.
• Replacing the file on the media record changes it in every record that references it.

Using library files in WYSIWYG fields

When a WYSIWYG field allows uploads, its upload window shows two tabs: Upload Files and Add from Media Library. The media tab lists the library with Add Media links, and inserted images can use the full image or any of its thumbnail sizes.

Because WYSIWYG content stores image URLs as static HTML, library images are inserted as links to a mediaView.php redirect script (located in the media upload directory) rather than direct file URLs:

<img src="/uploads/media/mediaView.php?num=5&hash=abc123">

The script redirects to the file’s current location, so replacing the file in the library updates WYSIWYG content automatically even if the new file has a different name. Two caveats: a replacement image with different dimensions can cause layout issues where the HTML has old width/height attributes baked in, and deleting the media record’s upload breaks the inserted links.

In viewers

Media-backed uploads need no special handling in viewer code. Upload rows that reference the library are populated with the media file’s path, URL, dimensions, and thumbnail data when records load, so they display exactly like regular uploads. The mediaNum attribute holds the linked media record number when you need to detect them. See Displaying Uploads.